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

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.

Prompt chaining

When brainstorm, plan, or code finishes, zerosta