zerostack — minimal coding agent

Overview

Minimal coding agent written in Rust — ~13k LoC, 12.9 MB binary, ~16 MB RAM. Peak RAM ~24 MB vs ~700 MB for JS-based agents. CPU: 0.0% idle, ~1.5% under load.

~13k

Lines of Code

12.9 MB

Binary Size

~16 MB

RAM (avg)

0.0%

CPU (idle)

Multi-provider — OpenRouter, OpenAI, Anthropic, Gemini, Ollama
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
Loop system — iterative coding for long-horizon tasks
Git Worktrees — branch-per-task workflow
ACP support — editor integration (Zed, etc.)
Sandbox mode — bubblewrap / zerobox isolation
Exa search — WebFetch & WebSearch tools

/prompt autoconfig

Run this inside zerostack after install to explore the docs and configure everything interactively.

--parallel

Run multiple agents on the same repo. Each gets a temporary git worktree, merged & cleaned up on exit.

Matrix chatroom

Questions? Ideas? Join the zerostack-general room on 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

# Set your API key (OpenRouter is default)
export OPENROUTER_API_KEY="[api_key]"

# Interactive session (default prompt: code)
zerostack

# Monochrome TUI
zerostack --no-color

# One-shot mode
zerostack -p "Explain this project"

# Continue last session
zerostack -c

# Explicit provider/model
zerostack --provider openrouter --model deepseek/deepseek-v4-flash

Installation

Requires Cargo and git:

# Default — MCP, loop, and git-worktree included
cargo install zerostack

# With ACP support
cargo install zerostack --features acp

Pre-built binaries are also available on GitHub Releases.

Once installed, run /prompt autoconfig inside zerostack to configure the tool interactively.

Optional: Sandbox

# Debian/Ubuntu
apt install bubblewrap

# Fedora
dnf install bubblewrap

# Arch
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:

# Stdio mode (editor spawns as subprocess)
zerostack --acp

# TCP mode
zerostack --acp --acp-host 0.0.0.0 --acp-port 7243

Providers

OpenRouter (default)
OpenAI-compatible (vLLM, LiteLLM, etc.)
Anthropic
Gemini
Ollama

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.

License

GPL-3.0-only