Alter Zero

Give your terminal a coding agent.

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

Watch the video demo on YouTube

Alter Zero is an open-source AI coding agent written in Rust, inspired by Claude Code and Codex CLI. 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 | sh

It 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.

Or install the same build with npm:

npm install -g @linuztx/alter-zero

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)"

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-zero

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-zero

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

1. Run /login and choose a supported subscription, API provider, or local model server. Follow the prompts to connect.
2. Run /model to choose a model. Alter Zero remembers your selection for this directory.
3. 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.

export OPENROUTER_API_KEY="your-api-key"
export ALTER_ZERO_PROVIDER=openrouter
alter-zero

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.

[providers.groq]
name = "Groq"
api_key_url = "https://console.groq.com/keys"

[providers.groq.kwargs]
api_base = "https://api.groq.com/openai/v1"

• 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. manual asks before file changes and commands; edit allows file changes; auto, the default, adds a reviewer for routine commands; master runs 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.
• Nothing runs on its own unseen. When the app starts, it lists any new or changed hook, yours or a project's, and any new project MCP server, showing exactly what each runs. A hook runs only once you trust it, a server only once you enable it, and /hooks and /mcp change either later.
• Credentials by placeholder. Store a credential with /secrets and the agent can use its placeholder without seeing the value. See how secrets are stored and used.

• Subagents. Delegate focused work to agents with their own context, model, and tool access. Built-in general-purpose and explore agents are editable, and you can open a running agent's session to chat, send follow-up work, or stop it — while the main agent does the same by each agent's id: checks its progress, sends a finished agent a follow-up with its context intact, or stops it.
• Skills. Add reusable SKILL.md folders, mention one with $, or browse them with /skills. Built-in skill-creator helps you write your own; web-search searches the web through Exa, Parallel, Tavily and Jina Reader with no key; jina-reader reads public webpages and PDFs through Jina Reader; yt-dlp guides media downloads with the separately installed CLI.
• Public tunnels. The built-in flaredantic skill guides you through exposing a local service via Cloudflare, Microsoft Dev Tunnels, or Serveo using the separately installed flare CLI. A tunnel makes the service publicly reachable; review what you expose.
• MCP servers. Connect tools over stdio, HTTP, or SSE, including remote servers with OAuth. Manage connections with /mcp or alter-zero mcp.
• Hooks and project instructions. Use hooks.json to approve, reject, or adjust tool calls and supply context. AGENTS.md files carry your project's conventions; /init helps create one.

• Saved conversations. /resume opens a searchable session picker. Use --continue for 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. /context shows what fills the context window and how much of it the prompt cache served, and /usage how much of each subscription's plan is left. /compact summarises long conversations, with automatic compaction as the 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. /settings brings the remaining controls together in a searchable menu.
• Works with herdr. In a herdr pane, the sidebar shows when the agent is working, waiting on your approval, or done, and a restarted herdr resumes the conversation. There is nothing to set up.

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

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

alter-zero "fix the failing test"
alter-zero -c "now review the changes"

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.

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.