Show HN: Alter Zero: an open-source terminal agent harness I built in Rust

Read, build, debug, and review code with an agent that works alongside you.

Use the same tools for cybersecurity research, technical investigation, and everyday automation.

Quick start · Features · Model providers · Commands & shortcuts · Support · Acknowledgements

Alter Zero is an open-source AI coding agent written in Rust. It works directly in your project: reading files, making edits, running commands, and checking results while you follow along in your terminal. Coding is its focus, with the flexibility to investigate security issues, explore unfamiliar systems, and automate tasks using your existing tools.

Alter Zero runs on Linux (x86_64, arm64) and macOS (Intel, Apple silicon) in a modern terminal.

One line on Linux or macOS:

curl -fsSL https://raw.githubusercontent.com/linuztx/alter-zero/main/install.sh | shIt picks the build for your machine, verifies its SHA-256 against the checksum published with the release, installs alter-zero into ~/.local/bin, and tells you if that directory is not on your PATH.

Install options

Set ALTER_ZERO_INSTALL_DIR to install somewhere else, or ALTER_ZERO_VERSION=vX.Y.Z to pin a release. CHANGELOG.md records what changed between versions.

ALTER_ZERO_INSTALL_DIR="$HOME/bin" ALTER_ZERO_VERSION=v0.1.0 \

sh -c "$(curl -fsSL https://raw.githubusercontent.com/linuztx/alter-zero/main/install.sh)"For a manual install, each release's notes list every archive with its SHA-256, so you can download, verify, and extract one by hand.

Run it in a Kali Linux container

docker/ builds a small headless Kali Rolling image around the latest release, with a working set of command-line tools, for Docker or Podman. One command builds it and starts a container on a folder of yours:

docker/build.sh ~/projects/site # add --engine podman for Podman

docker exec -it -e TERM -e COLORTERM -e TERM_PROGRAM -e KITTY_WINDOW_ID -e TMUX \

alter-zero-kali alter-zeroOutside a multiplexer, the -e flags hand over your terminal's identity so

pictures render as real images rather than half-blocks. The

container guide covers workspaces, the published ports,

pasting images, and adding tools.

Inside tmux, enable allow-passthrough on the host and explicitly select the

outer terminal's image protocol for that docker exec; the

tmux instructions include a

ready-to-run Podman example.

You need rustup and a C compiler. The repository pins the Rust toolchain, which rustup installs automatically.

git clone https://github.com/linuztx/alter-zero.git

cd alter-zero

cargo install --path .

alter-zeroWithout a configured provider, Alter Zero opens an offline demo with scripted turns so you can explore the interface. To work on your own tasks:

- Run /loginand choose a supported subscription, API provider, or local model server. Follow the prompts to connect.

- Run /modelto choose a model. Alter Zero remembers your selection for this directory.

- Describe a task, review any approval prompts, and follow the work as it happens.

Sign-ins added through /login are saved to ~/.alter-zero/.env, outside your repository. Use / to browse commands or ? in an empty composer to see shortcuts.

Connect with environment variables

You can also select your provider before launch. Set its API key variable and provider ID, then start the app. For example, with OpenRouter:

export OPENROUTER_API_KEY="your-api-key"

export ALTER_ZERO_PROVIDER=openrouter

alter-zeroChoose a model with /model, or set ALTER_ZERO_MODEL to its model ID before launching.

Start with a concrete task and let the agent work through it with you.

Connect to a supported subscription service, API provider, or local model server. Use /login to connect and /model to choose your model.

The footer shows your active model, thinking mode, speed tier and context usage. Ctrl+T cycles the model's supported reasoning levels, a ChatGPT model that lists speed tiers gets a command per tier (/fast, /ultrafast) that switches it to that processing (faster replies at increased plan usage), vision support is checked before sending images, and requests support prompt caching where the provider allows it.

- Readable file changes. Numbered, syntax-highlighted file views and diffs highlight the characters that changed, so edits are easy to review.

- Live commands and task progress. Command output streams into the conversation, long results collapse into expandable previews, and a checklist tracks multi-step work.

- Parallel and background work. Tool batches are announced before execution. Move a running command to the background with Ctrl+B, then use Down from an empty composer to inspect or stop it.

- Decisions in context. Inline questions support multiple-choice and free-text answers. Send a message with Enter to steer the running turn, or use Tab to queue a follow-up.

- Review at the approval prompt. Inspect proposed file content, diffs, and commands before approving them. Approve once, allow a session rule, or reject with instructions using Tab. Ctrl+E asks for a command explanation.

- Four permission modes. manualasks before file changes and commands;editallows file changes;autoadds a reviewer for routine commands;masterruns unattended. Cycle modes with Shift+Tab and keep rules per project.

- Checkpoints and rewind. Enable checkpoints per directory to snapshot your working files in a separate store. Esc Esc returns to an earlier message and, when a checkpoint is available, restores the files with it.

- Project trust. Review project-defined agents, hooks, and MCP servers with /trustbefore they can run.

- Subagents. Delegate focused work to agents with their own context, model, and tool access. Built-in general-purposeandexploreagents are editable, and you can open a running agent's session to chat, send follow-up work, or stop it.

- Skills. Add reusable SKILL.mdfolders, mention one with$, or browse them with/skills. A built-inskill-creatorhelps you write your own.

- MCP servers. Connect tools over stdio, HTTP, or SSE, including remote servers with OAuth. Manage connections with /mcporalter-zero mcp.

- Hooks and project instructions. Use hooks.jsonto approve, reject, or adjust tool calls and supply context.AGENTS.mdfiles carry your project's conventions;/inithelps create one.

- Saved conversations. /resumeopens a searchable session picker. Use--continuefor the latest session in this directory or--resume <id>for a specific one.

- Settings that stay with the project. Model choices, permissions, skills, and appearance are remembered per directory, and every saved conversation resumes on the model it was using. Input history carries across sessions and is searchable with Ctrl+R.

- Managed context. /compactsummarises long conversations, with automatic compaction as the context window fills. A session scratchpad holds temporary scripts and notes outside your project.

- Rich output. Stream Markdown, tables, highlighted code, and collapsible reasoning blocks, with clickable URLs and file paths in supported terminals.

- Inline images. Paste screenshots with Ctrl+V. Images render natively in kitty, iTerm2, and sixel terminals, with a character-based fallback elsewhere.

- Inspect the session. Ctrl+O opens the expanded transcript; Ctrl+D shows the context sent to the model. Start a line with !for a shell command or use@to pick a file.

- Live customisation. Preview eleven themes with /theme, six mascots with/mascot, and nine spinner styles with/spinner./settingsbrings the remaining controls together in a searchable menu.

The essentials are always one keystroke away: / opens commands, and ? in an empty composer shows shortcuts.

Slash commands

Keyboard shortcuts

Command-line options

Usage: alter-zero [OPTIONS] [PROMPT]

alter-zero mcp <COMMAND>

alter-zero update

Arguments:

[PROMPT] Send this message as the first turn

Options:

-c, --continue Continue the most recent conversation in this directory

-r, --resume [ID] Resume a conversation by id, or pick one from a list

-h, --help Print help

-V, --version Print version

Start a task directly, or continue the work from your last session:

alter-zero "fix the failing test"

alter-zero -c "now review the changes"Run alter-zero mcp --help for MCP server management commands, and alter-zero update to install the newest release over the binary you are running.

Your sign-ins, saved sessions, input history, and per-directory settings live under ~/.alter-zero/. Keep shared extensions there, or add project-specific ones alongside your code.

Configuration and extension paths

Claude Code-style .claude/skills/ and .mcp.json files are also supported. Project-defined agents, hooks, and MCP servers require approval through /trust.

Alter Zero is free and open source. If it earns a place in your terminal, a donation keeps the work going. /donate shows these addresses inside the app, each in a copyable box.

Important: Send only on a network listed for that address. Confirm that the asset and selected network match before sending. An address may look valid on another network, but funds sent on an unlisted or mismatched network may be unrecoverable.

Thank you.

Alter Zero is released under the Apache License 2.0. Copyright 2026 linuztx.

Alter Zero is made possible by the people, projects, and communities behind it:

- Agent Zero and its team for supporting the development of Alter Zero, including the free A0T inference credits used during testing.

- Claude Code and Codex CLI for the interaction patterns that helped shape Alter Zero.

- ratatui and crossterm for the foundation of the terminal UI.

See the additional technical credits.