Overview #
Minimal coding agent written in Rust — ~16k LoC, 26MB binary, ~16 MB RAM (avg), ~24 MB (peak). Peak RAM ~24 MB vs ~700 MB for JS-based agents. CPU: 0.0% idle, ~1.5% under load.
Multi-provider— OpenRouter, OpenAI, Anthropic, Gemini, Ollama, plus custom providers** Standard tools**— all tools exposed to coding agents (as described by opencode)** Permission system**— 5 modes, per-tool patterns, session allowlists** Terminal UI**— crossterm, markdown rendering, mouse support, scrollback** Prompts system**— 10 built-in prompts, switchable at runtime** Session management**— save/load/resume, auto-compaction** MCP support**— connect external tool servers** Ralph Wiggum loops**— iterative coding for long-horizon tasks** Git Worktrees**— branch-per-task workflow** ACP support**(gated) — editor integration (Zed, etc.)** Persistent memory**(gated) — plain-Markdown memory across sessions** Subagents**— parallel, fast codebase exploration** ARCHITECTURE.md**— shared core knowledge for all agents on the same codebase** Sandbox mode**— bubblewrap / zerobox isolation** Exa search**— WebFetch & WebSearch tools
zerostack-general roomon Matrix.
Prompts #
Built-in system prompts that change the agent's behavior and tone — switch at runtime with /prompt
:
| Prompt | Description |
|---|---|
code |
Coding mode with full file & bash access, TDD workflow |
plan |
Planning-only — explores and produces a plan without code |
review |
Code review for correctness, design, testing, and impact |
debug |
Finds root cause before proposing fixes |
ask |
Read-only mode — no writes or bash |
brainstorm |
Design-only — explores ideas without code |
frontend-design |
Distinctive, production-grade UI |
review-security |
Finds exploitable vulnerabilities |
simplify |
Refines for clarity without behavior change |
write-prompt |
Creates and optimizes agent prompts |
Custom prompts can be created by placing markdown files in $XDG_CONFIG_HOME/zerostack/prompts/
.
Permissions #
| Mode | CLI | Behavior |
|---|---|---|
| restrictive | -R |
Ask for every operation |
| readonly | --read-only |
Read/grep/list only. Deny writes, edits, bash |
| guarded | --guarded |
Allow reads. Ask for writes, edits, bash |
| standard | (default) | Allow path tools within CWD. Safe bash auto-allowed |
| yolo | --yolo |
Allow everything, prompt for destructive commands |
Per-tool granular glob patterns, session allowlists, and doom-loop detection prevent runaway agents. The --dangerously-skip-permissions
flag bypasses all checks.
Commands #
/model— Switch model
/thinking— Set thinking level
/clear— Clear conversation
/session— List/save/load sessions
/loop— Schedule recurring prompts
/prompt— List or change system prompt
/mode— Set permission mode
/worktree— Create git worktree and move into it
/wt-merge— Merge worktree branch, push, clean up, return
/wt-exit— Return to main repo without merging
/help— Show all commands
Quick Start #
export OPENROUTER_API_KEY="[api_key]"
zerostack
zerostack --no-color
zerostack -p "Explain this project"
zerostack -c
zerostack --provider openrouter --model deepseek/deepseek-v4-flash
Installation #
Requires Cargo and git:
cargo install zerostack
cargo install zerostack --features acp
cargo install zerostack --features memory
cargo install zerostack --features multithread
Pre-built binaries are also available on GitHub Releases.
Once installed, run /prompt autoconfig
inside zerostack to configure the tool interactively.
Optional: Sandbox
apt install bubblewrap
dnf install bubblewrap
pacman -S bubblewrap
Parallel Agent #
Run multiple zerostack agents on the same repository simultaneously without manual git worktree management.
zerostack --parallel
Each parallel agent operates in a temporary git worktree. Changes are merged and the worktree is removed when the agent exits.
ACP (Agent Communication Protocol) #
With the acp
feature, zerostack acts as an ACP Agent server, allowing editors like Zed to connect to it as a coding agent backend:
zerostack --acp
zerostack --acp --acp-host 0.0.0.0 --acp-port 7243
Providers #
OpenRouter(default)** OpenAI-compatible**(vLLM, LiteLLM, etc.)** AnthropicGeminiOllama**
Custom providers can be configured with any base URL and API key environment variable.
Sessions #
Sessions are saved to $XDG_DATA_HOME/zerostack/sessions/
. Use -c
to resume the most recent session, -r
to browse and select one, or --session <id>
to load a specific session.