New discovery: coding agents can be this lightweight — 16MB memory, 0% idle CPU, 26MB binary. These numbers are almost unheard of in the agent space. Built with Rust and just 17k LoC, it packs all standard tools, permission system, session management, and MCP into a tiny footprint. The core philosophy is “everything optional goes behind a feature gate” — so memory, ACP, multithreaded subagents all must be manually enabled at compile time.

Such a small package makes you wonder: what were those agents that used hundreds of MB actually consuming?

gi-dellav/zerostack

Source: https://github.com/gi-dellav/zerostack

banner

zerostack

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

blogposts:
what we built in 2 weeks
memory design
subagents design

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

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: ~17k 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:

``bash

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

With experimental multi-threaded subagents

cargo install zerostack –features multithread
``

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:

``bash

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

``bash

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.

Permission system

zerostack has five permission modes:

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
• /queue — Manage input queued while the agent is busy
• /btw — Ask a quick side question in parallel without interrupting the agent

To see all of the commands, use /help.

Input queue

You can keep typing while the agent is running. Plain text is not sent right away and never starts a second concurrent run; it is queued and replayed as the next prompt once the current run finishes. Each queued line is shown as queued: .

Manage the queue with /queue, which works even while a run is active:

• /queue ls lists the pending inputs (bare /queue does the same)
• /queue clear empties the queue
• /queue pop removes the last queued input, to undo a mis-typed line

Selecting /queue in the command picker opens a second-level menu with these three subcommands, so you do not need to remember them.

Commands (input starting with /, ., or !) are not queued while a run is active: wait for it to finish, or press Ctrl-C. Ctrl-C cancels the running agent for real, including any child processes it spawned, and clears the queue.

Side questions (/btw)

/btw <question> asks a quick “by the way” question in parallel with the main agent, without interrupting it. Like /queue, it works even while the agent is busy. It forks the current context (including a trace of the agent’s in-flight turn, when one is running) and answers using four read-only tools (read, grep, find_files, list_dir); it cannot write files or run commands. It then prints the reply inline. Nothing is written to conversation history, and its token usage is tracked separately in the status bar as btw:.... Press Ctrl-C to cancel an in-flight /btw without disturbing the main agent.

You can point a question at a specific file with @: pick /btw from the command menu, then type @ to open the file picker (for example /btw then @src/main.rs then “how does this work?”), and /btw reads the file you reference.

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 <name> 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 original task, the evolving LOOP_PLAN.md, a summary of the previous iteration, and any validation output. Non-slash input is blocked while a loop is active.

Headless loops via CLI

zerostack --loop --loop-prompt "Refactor the API" --loop-max 10 --loop-run "cargo test"

Git worktrees integration

zerostack provides a branch-per-task workflow using git worktrees. You can create, work in, merge, and exit worktrees entirely from the chat UI.

NOTE The git worktrees integration is an experimental feature.

Git worktree usage

The worktrees integrations offers 3 slash commands:

Example workflow for git worktrees

1. Create — /worktree feature-x creates a new branch and worktree directory and moves you there.
2. Work — Use zerostack normally; changes stay on the feature branch.
3. Merge — /wt-merge tells the agent to merge the branch, push, clean up, and return to the main repo.
4. Exit — /wt-exit immediately returns to the main repo without merging.

ACP (Agent Communication Protocol) support

ACP is a JSON-RPC based protocol that standardizes communication between code editors (IDEs, text-editors, etc.) and coding agents. With the acp feature enabled, zerostack acts as an ACP Agent server, allowing editors like Zed to connect to it as a coding agent backend.

NOTE: ACP support is gated behind the acp feature and is not included in the default build.

ACP usage

``bash

Start zerostack in ACP stdio mode (editor spawns this as a subprocess)

zerostack –acp

Start zerostack in ACP TCP mode (listen on 0.0.0.0:7243)

zerostack –acp –acp-host 0.0.0.0 –acp-port 7243
``

ACP config

In ~/.local/share/zerostack/config.json:

json { "acp_servers": { "my-editor": { "host": "127.0.0.1", "port": 7243 } } }

ACP mode requires setting up an LLM provider (the standard --provider, --model, and API key env vars apply). Without it, zerostack cannot process prompts.

Supported 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 in ~/.local/share/zerostack/config.json.

License

GPL-3.0-only