zerostack: a Rust coding agent built for a 16MB memory footprint

What zerostack is, and who it is aimed at

zerostack is a coding agent that runs in a terminal. The README describes it as minimal and Rust-written, and credits pi and opencode as its inspirations. The pitch is not breadth. It is resource cost: the README states a binary of 26MB, roughly 30k lines of code in the core excluding tests, and an average RAM footprint of about 16MB with peaks near 24MB. It contrasts that with roughly 300MB average and peaks around 700MB for opencode and other JavaScript-based agents. Those numbers come from the project's own README, measured on an Intel i5 7th gen according to the same text, so treat them as the author's figures rather than an independent result.

The audience follows from that. If you already run an agent in a terminal and the thing you notice is the process sitting at several hundred megabytes while it waits for you to type, zerostack is addressed to you. If your interest is a GUI, a plugin marketplace or a hosted service, nothing here is aimed at it. The README also states plainly that Windows support is not tested in any way, and invites bug reports from anyone who tries it. That is an honest boundary and it should be read as one: the supported surface is Linux and macOS.

How the agent is put together: providers, tools, and gated features

The architecture visible in the repository is a single Rust binary with a feature-flag build. Cargo.toml sets the default feature set to loop, git-worktree, mcp, subagents, archmd, status-signals, multithread and export. Everything else is opt-in: acp, memory, multimodal, pdf, advisor, hooks, lsp and rtk. That split is the most consequential design decision in the project. A default cargo install gives you the looping agent, MCP client support, subagents, the architecture file convention and status signals. It does not give you persistent memory, lifecycle hooks, the advisor model or multimodal input unless you ask for them at build time.

On the model side, the README lists OpenRouter, OpenAI, Anthropic, Gemini, Ollama and custom providers, so local inference through Ollama is a first-class path rather than an afterthought. Tools are described as the standard set exposed to coding agents, with the README pointing at the opencode documentation for what that means. Permission handling is a five-mode system with per-tool patterns, session allowlists, and configurable policies for how modes map to rules. Sessions can be saved, loaded and resumed, and the agent auto-compacts to stay inside the context window.

The memory feature, when compiled in, is deliberately unglamorous: a global MEMORY.md plus per-project daily logs, a scratchpad and notes, all plain Markdown, injected into the system prompt each session. Nothing is stored in a vector database, and nothing is hidden in a binary format. Subagents run in parallel and the README scopes them to codebase exploration. Prompt chaining offers to move a task through brainstorm, plan, code and review, with each transition gated by config. Status signals are emitted over a Unix socket as start, stop and git-conflict events, which is what a status bar would subscribe to. The Unix socket detail is another reminder that this is a POSIX-shaped tool.

Installing zerostack and running a first session

The README recommends the install script. It fetches install.sh from the main branch and pipes it to bash, so read the script first if you care what lands on your machine.

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

If you prefer to control the build, Cargo is the second path. The default features are the ones listed in Cargo.toml, so a plain install gives you the loop, git-worktree, MCP, subagents, archmd, status-signals, multithread and export set.

cargo install zerostack

The gated subsystems need to be named explicitly. This is the command the README gives for pulling in ACP, memory, hooks and the advisor together.

cargo install zerostack --features acp,memory,hooks,advisor

Homebrew users get a tap, and the README notes that brew trust is required on Homebrew 6.0.0 and later. The same block mentions multistack, a separate project for orchestrating several zerostack agents from one terminal.

brew tap gi-dellav/tap
brew trust gi-dellav/tap
brew install zerostack

Once the binary is on your PATH, the README's first step is not a config file. It is a slash command inside the agent, which walks you through the documentation and sets the tool up interactively.

/prompt autoconfig

Expect that command to ask about providers and prompts rather than to write a finished config for you. The README also points at a separate GET_STARTED.md in the docs directory for a longer walkthrough, and at a Matrix room for questions.

Sandbox mode is a seatbelt, and the README says so

zerostack can run every bash command inside an isolated environment when you pass --sandbox. On Linux the backend is bubblewrap, installed from the distribution package manager. On macOS bubblewrap is not available, so the README points at zerobox as an alternative backend, installed with cargo install zerobox, and configured with sandbox-backend = "zerobox".

# Debian/Ubuntu
apt install bubblewrap

The important part is the failure mode. The README states that --sandbox is best effort: when the selected backend binary is missing, bash commands still run, but unsandboxed, with a warning in the logs. If you want the run to stop instead, --sandbox-required, or sandbox-required = true in the config, turns the missing backend into a hard failure. The README's own framing is the right one to repeat: this is a seatbelt, not a boundary against untrusted code. If your threat model is a hostile repository rather than your own typo, a sandbox that degrades to no sandbox with a log line is not the control you are looking for.

Where zerostack is the wrong tool

The gated features are the first limitation, and it is easy to miss. Persistent memory, hooks, the advisor, multimodal input and PDF attachment are not in the default build. A user who installs with the script or a plain cargo install and then looks for MEMORY.md will not find it. The README lists these under a gated heading, so the information is there, but the feature list at the top of the page reads as if everything is present. Check Cargo.toml before you assume a capability exists in your binary.

Windows is the second. The README says support is not tested in any way and asks for issues from anyone who tries. Combined with the Unix socket used for status signals and the bubblewrap sandbox on Linux, the practical target is Linux and macOS. Running it on Windows is an experiment, not a supported configuration.

The third limitation is what the performance numbers do not cover. Binary size and resident memory say nothing about answer quality, tool-call reliability or how the agent behaves on a large repository. The README's comparison against JavaScript-based agents is a comparison of process cost, and it is the project's own measurement. If your reason for picking an agent is the quality of its edits, this page gives you no evidence either way.

Finally, the release cadence visible in the repository is fast: v1.8.2, v1.8.3 and v1.8.4 all landed within a few days of each other in early September 2026, and the last push to main was on 2026-09-09. That is a project moving quickly, which means configuration keys and feature flags can shift between versions. Pin a version if you are scripting around the config.

zerostack compared with opencode and pi

The README names both comparisons itself, so the honest starting point is that zerostack is a reimplementation of a shape that already exists. opencode is the reference for the tool surface: zerostack's README describes its own tools as the standard set described by the opencode documentation, which means the two should feel similar at the level of what the agent can do to your files. The difference is the runtime. opencode is JavaScript-based, and the README's memory and CPU figures put it at roughly 300MB average with peaks near 700MB, against about 16MB and 24MB for zerostack. If you have ever watched a Node process idle at a few percent CPU, the 0.0% idle figure the README gives for zerostack is the concrete difference.

pi is the other named influence, and the README's prompts system reads as the clearest point of divergence from a skills-based design. Rather than managing Skills, zerostack lets you switch system prompt modes at runtime between code, plan, review and debug, and the README frames that as the reason to prefer it. Whether runtime prompt switching is better than a skill library is a workflow question, not a benchmark one. What is measurable is that a mode switch is a config change inside one process, while a skill system typically means loading additional instruction files.

There is also a sibling project rather than a competitor: multistack, from the same author, orchestrates multiple zerostack agents from the terminal. If your problem is running several agents at once, that is the tool the README points you to, not zerostack itself.

Licence and the cost of keeping up

Cargo.toml declares license = "GPL-3.0-only" and the repository carries a LICENSE file. That is a copyleft licence, and it is worth noting that the README's own framing is about personal use and donations rather than commercial embedding. If you distribute a modified zerostack binary, or build a product around it, the licence terms apply to that distribution. This is a factual observation about the declared licence, not legal advice; check with someone qualified before you ship anything derived from it.

The upgrade cost is mostly build cost. Because so much of the interesting surface sits behind feature flags, an upgrade can change what a given feature set compiles to, and the version in Cargo.toml is synced into packaging files by scripts/sync-version.sh, which tells you the project treats version drift across packaging as a real problem. The justfile shows the maintenance loop the maintainer uses: just check runs cargo fmt --check plus clippy on all targets with all features and again with no default features, and just test runs the suite. If you build from source, running the same check with no default features is the quickest way to find out whether a feature you rely on has drifted.

There is no documented rollback procedure in the README for a bad upgrade. Keep the previous binary or the previous Cargo.lock if that matters to you.

Editorial conclusion

Adopt zerostack if you work in a terminal on Linux or macOS, want a coding agent whose resident memory the README puts at around 16MB, and are willing to build gated features such as memory, hooks and the advisor yourself. Do not adopt it if you need a supported Windows build, or if you expect the optional subsystems to be on in a stock install. Before committing, check the gated feature list in Cargo.toml against the workflows you actually want, and decide whether the GPL-3.0-only licence fits how you ship the binary.

Frequently asked questions

Official sources

1. gi-dellav/zerostack on GitHub
2. License: GPL-3.0
3. Project website
4. README
5. Releases