zerostack

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

blogposts: what we built in 2 weeks memory design subagents design xavier's memory analysis

note: Want to support? Consider donating here; if you are a company interested in sponsoring zerostack, contact me here.

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
• Lifecycle hooks (gated): observe or gate tool calls, prompts, and session lifecycle events via external commands, using a settings.json schema largely compatible with Claude Code hooks
• Advisor (gated): a second model the agent can consult mid-session for strategic guidance, with an optional human-handoff mode
• Multimodal input (gated): attach images and PDFs to messages
• Subagents: Parallel and fast, used for exploring the codebase
• ARCHITECTURE.md: Our own companion file for AGENTS.md, it allows to offer a shared core knowledge for all agents working on the same codebase
• Prompt chaining: offers to advance brainstorm → plan → code → review as each phase finishes, config-gated per transition
• Status signals: emits start/stop/git-conflict events over a Unix socket for external status bars or tooling

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: ~30k LoC (core, excluding tests)
• 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)

Star History

(NEW) Get Started

You can now read a complete Get Started guide for zerostack here!

Installation

Script (recommended)

curl -fsSL https://raw.githubusercontent.com/gi-dellav/zerostack/main/install.sh | bash

Or pick a tarball manually from GitHub Releases.

Cargo

# Default: loop, git-worktree, mcp, subagents, archmd, status-signals, multithread
cargo install zerostack

# With all features
cargo install zerostack --all-features

# With specific features
cargo install zerostack --features acp,memory,hooks,advisor

Homebrew

brew tap gi-dellav/tap
brew trust gi-dellav/tap   # required for Homebrew 6.0.0+
brew install zerostack
# brew install multistack   # Run this to also install multistack (parallel agent manager)

Nix

Run directly with nix-run:

$ nix-run https://github.com/gi-dellav/zerostack/archive/refs/heads/main.tar.gz

Add to profile:

$ nix profile add --file https://github.com/gi-dellav/zerostack/archive/refs/heads/main.tar.gz

Add as an overlay to your system/project:

let
  pkgs = import nixpkgs {
    overlays = [
      # src thru input pinning mechanism, or use builtins.fetchTarball
      (import "${zerostack-src}/nix/overlay")
    ];
  };
in
pkgs.zerostack

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.

If you want to orchestrate multiple zerostack agents from the terminal, also install multistack.

Optional: sandbox mode

Install bubblewrap for --sandbox, which runs every bash command inside an isolated environment to contain the damage a mistaken command can do to your system (a seatbelt, not a boundary against untrusted code):

# Debian/Ubuntu
apt install bubblewrap

# Fedora
dnf install bubblewrap

# Arch
pacman -S bubblewrap

There is also support for zerobox as an alternative sandbox backend. bubblewrap is Linux only, so on macOS install zerobox (cargo install zerobox) and set sandbox-backend = "zerobox".

--sandbox is best effort: when the selected backend binary is missing, bash commands still run, but unsandboxed, with a warning in the logs. Add --sandbox-required (or sandbox-required = true in the config) to turn that into a guarantee: bash commands are refused whenever the backend is unavailable, and the rest of the session keeps working. See SECURITY.md for what the sandbox does and does not protect against.

With the bwrap backend, well-known credential directories (~/.ssh, ~/.aws, ~/.gnupg, ~/.kube, ~/.docker, and the gh, gcloud, op and sops/age directories under the config base) are masked by default, so sandboxed commands read them as empty rather than as your keys and tokens, and the advertised ssh-agent is unreachable. sandbox-expose (config key or repeatable --sandbox-expose <path> flag) restores read-only access to one entry or a subpath of one. See docs/CONFIG.md for the key and SECURITY.md for the full threat model.

Sandboxed commands keep the host network by default. sandbox-network = false (or --sandbox-network=false) takes it away, which is what stops a command that read something sensitive from sending it anywhere. Each bash call then gets a fresh network namespace with only its own private loopback: a server the command starts and uses within that same command still works, but the internet, the LAN, and anything already listening on your machine (a dev server, a local registry) are unreachable, and the namespace itself is gone by the next bash call, taking anything bound to it (like a backgrounded server) with it; the working directory, by contrast, is shared with the host and persists across calls. That tradeoff is why the network stays open unless you ask.

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: