# zerostack

> Minimal AI coding agent for the terminal written in Rust, featuring sandboxed execution, granular permissions, MCP support, and multi-provider LLM access.

zerostack is a lightweight, open-source AI coding agent built in Rust by Giuseppe Della Vedova, designed to run entirely in the terminal with a minimal resource footprint. It is licensed under GPL-3.0 and installable via Cargo, Homebrew, Nix, or a curl script. The project is actively maintained, with its latest release (v1.8.4) published in September 2026.

## What It Is

zerostack is a terminal-based coding agent that connects to multiple LLM providers and exposes a rich set of tools for reading, writing, editing, and executing code — all from a crossterm-based TUI with markdown rendering and mouse support. It is inspired by pi and opencode, and positions itself as a performance-conscious alternative to JavaScript-based coding agents. The README states a RAM footprint of approximately 16 MB on average (with peaks around 24 MB), compared to approximately 300 MB for opencode, and a binary size of 26 MB.

## Architecture and Performance Profile

zerostack is written entirely in Rust, which the project credits for its low memory and CPU overhead. Key performance figures published in the README:

- ~30,000 lines of code (core, excluding tests)
- 26 MB binary size
- ~16 MB average RAM, ~24 MB peak
- 0.0% CPU at idle, ~1.5% when using tools (measured on an Intel i5 7th gen)

The agent runs as a single CLI binary and communicates with LLM providers over HTTP. It emits run-state events over a Unix domain socket (`--status-socket`) for integration with external status bars or tooling.

## Permission System and Sandbox

One of zerostack's distinguishing design choices is its five-tier permission system:

- **restrictive** — asks for every operation
- **readonly** — allows only read/grep/list; denies writes, edits, and bash
- **guarded** — allows reads, asks for writes and bash
- **standard** (default) — allows path tools within the current working directory; safe bash commands auto-allowed
- **yolo** — allows everything, prompts only for destructive commands

Per-tool glob patterns, session allowlists, and doom-loop detection (identical tool calls repeated 3+ times trigger a warning or denial) are built in. An optional sandbox mode uses bubblewrap (Linux) or zerobox (macOS) to isolate bash commands, masking credential directories like `~/.ssh` and `~/.aws` by default.

## Feature Set and Gated Capabilities

The default build includes multi-provider support (OpenRouter, OpenAI, Anthropic, Gemini, Ollama, and custom providers), MCP server integration, session save/load/resume with auto-compaction, 14 built-in switchable system prompts, Git worktree integration, parallel subagents, iterative coding loops, Exa web search, and prompt chaining (brainstorm → plan → code → review). Several advanced features are compile-time gated and require explicit feature flags:

- **memory** — plain-Markdown persistent memory across sessions
- **hooks** — lifecycle hooks compatible with Claude Code's `settings.json` schema
- **advisor** — a second model consulted mid-session for strategic guidance
- **acp** — Agent Communication Protocol server for editor integration (e.g., Zed)
- **multimodal / pdf** — image and PDF attachment support

## Update: v1.8.4

The GitHub metadata shows the latest release is v1.8.4, published on 2026-09-07, with the repository last updated on 2026-09-14. The project has accumulated over 1,600 stars and 135 forks since its creation in May 2026. The developer has published blog posts covering the memory design, subagent architecture, and a "what we built in 2 weeks" retrospective, signaling rapid early development. A companion tool, multistack, is available separately for orchestrating multiple zerostack agents in parallel from the terminal.

## Features
- Multi-provider LLM support (OpenRouter, OpenAI, Anthropic, Gemini, Ollama, custom)
- Five-tier permission system with per-tool glob patterns and session allowlists
- Sandboxed bash execution via bubblewrap or zerobox
- MCP server integration
- 14 built-in switchable system prompts (code, plan, review, debug, brainstorm, etc.)
- Session save/load/resume with auto-compaction
- Crossterm TUI with markdown rendering, mouse support, and scrollback
- Git worktree integration for branch-per-task workflow
- Parallel subagents for fast codebase exploration
- Iterative coding loops (Ralph Wiggum loops) for long-horizon tasks
- Prompt chaining (brainstorm → plan → code → review)
- Exa web search (WebFetch and WebSearch tools)
- Persistent memory across sessions (gated feature)
- Lifecycle hooks compatible with Claude Code settings.json schema (gated feature)
- Advisor: second model consulted mid-session (gated feature)
- ACP server for editor integration e.g. Zed (gated feature)
- Multimodal input: images and PDFs (gated feature)
- Status signals over Unix domain socket
- Doom-loop detection to prevent runaway agents
- Input queue for typing while agent is running
- Side questions via /btw without interrupting main agent
- Custom prompts via markdown files in XDG config directory
- ARCHITECTURE.md shared context file for all agents on a codebase

## Integrations
OpenRouter, OpenAI, Anthropic, Gemini, Ollama, Exa search, bubblewrap (sandbox), zerobox (sandbox), MCP servers, Zed editor (via ACP), Git, Nix, Homebrew, Cargo

## Platforms
WINDOWS, MACOS, LINUX, API, CLI

## Pricing
Open Source

## Version
v1.8.4

## Links
- Website: https://gi-dellav.github.io/zerostack/
- Documentation: https://gi-dellav.github.io/zerostack/GET_STARTED.html
- Repository: https://github.com/gi-dellav/zerostack
- EveryDev.ai: https://www.everydev.ai/tools/zerostack