zerostack

Minimal coding agent written in Rust, inspired by pi and opencode.

blogposts: what we built in 2 weeks

Features

• Multi-provider: OpenRouter, OpenAI, Anthropic, Gemini, Ollama, plus custom providers
• Standard tools: all of the standard tools exposed to coding agents, as described by the opencode documentation.
• Permission system: five configurable modes with per-tool patterns, session allowlists, and configurable mode-to-rule application policies
• Session management: save/load/resume sessions, auto-compaction to stay within context windows
• Terminal UI: crossterm-based, markdown rendering, mouse selection/copy, scrollback, reasoning visibility toggle
• Prompts system: switch between system prompt modes at runtime (code, plan, review, debug, etc.) to tailor the agent's behavior to the task without having to manage Skills.
• MCP support: connect MCP servers for extended tooling (exposed as an optional compile-time feature)
• Integrated Exa search: allows for WebFetch and WebSearch tools
• Integrated Ralph Wiggum loops: looping capabilities for long-horizon tasks
• Integrated Git Worktrees integration: Use /worktree to move the agent from one worktree to another.
• ACP support (gated): Agent Communication Protocol server — lets editors (Zed, etc.) connect to zerostack as an ACP agent
• Persistent memory (gated): plain-Markdown memory across sessions: a global MEMORY.md plus per-project daily logs, scratchpad, and notes, injected into the system prompt each session

NOTE: Windows support is not tested is any way, but feel free to try and open an issue if you encounter any bugs!

Performance

zerostack is one of the smallest and most performant coding agents on the market.

• Lines of code: ~16k LoC
• Binary size: 26MB
• RAM footprint: ~16MB on average, with peaks at ~24MB (vs ~300MB with peaks at ~700MB for opencode or other JS-based coding agents)
• CPU usage: 0.0% on idle, ~1.5% when using tools (measured on an Intel i5 7th gen, vs ~2% on idle and ~20% when working for opencode)

Installation

In order to install zerostack, you must have Cargo and git installed. Then, run:

# Default: MCP, loop, git-worktree and subagents
cargo install zerostack

# With ACP (Agent Communication Protocol) support for editor integration
cargo install zerostack --features acp

# With Memory support
cargo install zerostack --features memory

You are now ready to work with a lightweight coding agent! (You can also find pre-built binaries on Github Releases)

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

note: If you have questions or you want to collaborate on the project, please join the dedicated Matrix chatroom.

Optional: sandbox mode

Install bubblewrap for --sandbox, which runs every bash command inside an isolated environment to protect your system from accidental or malicious damage:

# Debian/Ubuntu
apt install bubblewrap

# Fedora
dnf install bubblewrap

# Arch
pacman -S bubblewrap

There is also support for zerobox as an alternative sandbox backend.

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

Configuration

See docs/CONFIG.md for config file location, accepted keys, provider aliases, permission rules, and MCP server configuration.

You can run /prompt autoconfig in order to use a specialized agent that allows to navigate the documentation and customize your zerostack setup.

Prompts system

zerostack includes a set of built-in system prompts that change the agent's behavior and tone. The idea is to build a complete suite of prompts that can fully substitute skills like superpower or the Claude's official skills. You can switch between different prompts or list all registered prompts using /prompt.

Built-in prompts:

| Prompt | Description | | --------------------- | ------------------------------------------------------------------------ | | code (default) | Coding mode with full file and bash tool access, TDD workflow | | plan | Planning-only mode — explores and produces a plan without writing code | | review | Code review mode — reviews for correctness, design, testing, and impact | | debug | Debug mode — finds root cause before proposing fixes | | ask | Read-only mode — only read/grep/find_files permitted, no writes or bash | | brainstorm | Design-only mode — explores ideas and presents designs without code | | frontend-design | Frontend design mode — distinctive, production-grade UI | | review-security | Security review mode — finds exploitable vulnerabilities | | simplify | Code simplification mode — refines for clarity without changing behavior | | write-prompt | Prompt writing mode — creates and optimizes agent prompts |

You can also create custom prompts by placing markdown files in $XDG_CONFIG_HOME/zerostack/prompts/ and referencing them by name.

Additionally, the agent automatically loads AGENTS.md or CLAUDE.md from the project root or any ancestor directory, injecting their contents into the system prompt. When enabled (feature archmd), ARCHITECTURE.md is also loaded the same way, providing high-level design context to speed up exploration. Use -n / --no-context-files to disable all context file loading.

Permission system

zerostack has five permission modes:

| Mode | CLI flag | Behavior | |------|----------|----------| | restrictive | -R / --restrictive | Ask for every operation. Config rules are ignored by default (can be enabled via permission-modes). | | readonly | --read-only | Allow read/grep/find_files/list_dir. Deny writes, edits, bash, and everything else. Config rules ignored by default. | | guarded | --guarded | Allow read tools. Ask for writes, edits, bash, and everything else. Config rules apply. | | standard | (default) | Allow path tools (read/write/edit/list_dir) within CWD and subdirectories. Safe bash commands (ls, cat, git log, cargo check) auto-allowed. Ask for external paths and unrecognized commands. Config rules apply and override mode defaults. | | yolo | --yolo | Allow everything, but prompt for destructive bash commands (rm, dd, mkfs, etc.). Config rules apply. |

The --dangerously-skip-permissions flag completely bypasses all permission checks, allowing every tool operation without any guard. This is not a mode and cannot be toggled at runtime.

Permissions can be configured per-tool with granular glob patterns in the config file. For example, you can allow write **.rs automatically while always asking before writing to other files.

A session allowlist persists approved decisions for the duration of the session, so you don't have to repeatedly confirm the same operation.

Doom-loop detection: identical tool calls repeated 3+ times trigger a warning prompt (or denial depending on your config), preventing runaway agents from spamming destructive operations.

Slash commands

This is a list of the most important slash commands:

• /model — Switch model
• /thinking — Set thinking level
• /clear — Clear conversation
• /session — List/save/load sessions
• /loop — Schedule recurring prompts
• /prompt — List or change the agent's prompt
• /mode — Set the permission system's mode

To see all of the commands, use /help.

Session management

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.

Memory

NOTE: Memory is gated behind the memory feature and is not included in the default build. Install with cargo install zerostack --features memory.

With the memory feature, zerostack keeps plain-Markdown notes on disk and injects the relevant ones into the system prompt at the start of every session, so it remembers your preferences and recent context across runs.

Global memory files are stored in $XDG_DATA_HOME/zerostack/agent/memory/.

Parallel Agent

If you want to make multiple agents work on the same repository without having to work with git worktrees, zerostack now ships with --parallel, which enables full management of a temporary git worktree that will be merged and removed before exiting the agent.

Loop system

zerostack includes an iterative coding loop for long-horizon tasks. The agent repeatedly reads the task, picks an item from the plan, works on it, runs tests, updates the plan, and loops until the task is complete or the iteration limit is reached.

NOTE The loop system is an experimental feature.

Loop usage

/loop Implement the user authentication system
/loop stop
/loop status

• /loop <prompt> — Start a loop with the given prompt
• /loop stop — Stop the active loop
• /loop status — Show current loop state

Each iteration includes the ori