Stunning! 17KB Code, 16MB RAM, 26MB Binary — This Rust Coding Agent Takes “Minimalism” to the Extreme

Stunning! 17KB Code, 16MB RAM, 26MB Binary — This Rust Coding Agent Takes “Minimalism” to the Extreme

At a time when AI coding tools routinely consume hundreds of megabytes of RAM and are built on Electron or Node.js, a coding agent written in Rust is turning heads with astonishing performance numbers: roughly 17,000 lines of code, a 26MB binary, and an average memory footprint of 16MB (peak 24MB). Meet zerostack — a minimalist coding agent inspired by pi and opencode, built for those who demand maximum efficiency.

If you’re fed up with JavaScript-based tools that idly eat 2% CPU and spike to 20% under load, zerostack will completely reshape your expectations of what an AI coding tool can be.

1. Project Overview: When “Minimalist” Becomes a Design Statement

zerostack is a minimalist coding agent built in Rust by the gi-dellav team. Its core mission isn’t “most features,” but to pack complete functionality into the tightest resource envelope possible.

1.1 Performance Comparison: Data Doesn’t Lie

Metric	zerostack	opencode (JS-based)
Code Size	~17k LoC	Hundreds of thousands
Binary Size	26MB	Hundreds of MB
RAM (avg / peak)	~16MB / ~24MB	~300MB / ~700MB
CPU Idle Usage	0.0%	~2%
CPU Working Usage	~1.5%	~20%

These measurements were taken on an Intel i5 7th gen processor. zerostack leverages Rust’s zero-cost abstractions and fine-grained memory management to achieve 20x less memory and 13x less CPU than conventional solutions. This isn’t optimization — it’s a paradigm shift.

1.2 Core Features at a Glance

Despite its minimalist philosophy, zerostack doesn’t compromise on functionality:

• Multi-model support: OpenRouter (default), OpenAI, Anthropic, Gemini, Ollama, and any custom Provider
• Standard toolset: Full file read/write/edit, Bash execution, Grep search, file lookup, and other standard coding agent tools
• Five-tier permission system: From “ask for every operation” to “fully automatic,” with fine-grained rules per tool and per path glob/regex
• Session management: Save/load/resume sessions, with automatic history compression to fit context windows
• Terminal UI: Custom TUI built on crossterm, supporting Markdown rendering, mouse selection/copy, scrollback, and toggleable reasoning visibility
• Prompt system: Built-in modes for code, plan, review, debug, ask, brainstorm, and more — switch at runtime without managing Skills
• MCP support: Connect MCP servers to extend tool capabilities (compile-time feature)
• Integrated Exa search: Built-in WebFetch and WebSearch tools
• Loop tasks: Ralph Wiggum loops for long-running iterative tasks
• Git Worktrees: Branch-level task isolation with one-command /worktree switching
• ACP protocol: Agent Communication Protocol support — editors like Zed can connect directly
• Persistent memory: Cross-session Markdown memory system (memory feature)
• Sub-agents: Parallel sub-agents for codebase exploration
• ARCHITECTURE.md: Project-level architecture document injection, providing shared context for all agents

2. Design Philosophy: Every Line Serves Subtraction

zerostack’s design philosophy can be summed up in one sentence: “Subtract until you can subtract no more, then run what’s left at peak efficiency.”

2.1 Architecture Minimalism: Single Crate, No Workspace

zerostack rejects the common Rust practice of multi-crate workspaces, opting instead for a single crate of ~17k lines of tightly packed code. All source lives under src/:

Path	Responsibility
src/main.rs	Entry, CLI dispatch, mode routing
src/cli.rs	clap-derived argument parsing
src/provider.rs	LLM Provider abstraction (type-erased enum)
src/agent/	Agent lifecycle, system prompt, 11 tool implementations
src/session/	Session state, auto-compression, persistence
src/permission/	Security: glob+regex double-layer rules, Doom-loop detection
src/ui/	Custom TUI (crossterm, no ratatui)
src/context/	Context: prompt themes, AGENTS.md/ARCHITECTURE.md loading
src/config/	Configuration loading (TOML/JSON)
src/extras/	Feature-gated extensions: loop, mcp, acp, memory, subagents, etc.

2.2 Custom TUI Instead of ratatui

The team deliberately avoids ratatui and built the TUI from scratch on crossterm. This sidesteps widget tree overhead and keeps the binary small. The project includes its own line buffer, Markdown renderer, scroll/selection system. The Renderer operates directly on a viewport buffer, outputting via crossterm drawing commands.

2.3 Type-Erased Enum, No Dynamic Dispatch

In src/provider.rs, zerostack uses AnyClient / AnyModel / AnyAgent enums to wrap the various Provider clients from the rig framework, instead of dyn CompletionModel trait objects. This avoids vtable lifetime issues — enum matching is faster than dynamic dispatch.

2.4 Single-Threaded Tokio by Default

zerostack defaults to #[tokio::main(flavor = "current_thread")], unless the multithread feature is explicitly enabled. For a CLI tool, a single thread handles user input and LLM streaming responses just fine, eliminating multi-threading overhead.

2.5 Feature Gates: Core Doesn’t Bloat

loop, mcp, acp, memory, subagents, git-worktree, archmd are all compile-time features. The default build includes only the core, and users opt into extensions as needed, keeping the binary lean.

2.6 Two-Layer Permissions: Fast Path + Exact Match

The permission system uses a glob (fast path) + regex (complex patterns) two-layer architecture. Glob handles common rules, regex handles exact matches. It also includes Doom-loop detection: if the same tool call repeats more than 3 times, a warning or denial is triggered, preventing runaway agent destruction.

3. Detailed Tutorial: From Installation to Mastery

3.1 Installation

Method 1: One-liner script (recommended)

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

Method 2: Nix (for NixOS users)

# Run directly
nix run github:gi-dellav/zerostack

# Install to profile
nix profile install github:gi-dellav/zerostack

Method 3: Cargo (for Rust developers)

# Default features: loop, git-worktree, mcp, subagents, archmd
cargo install zerostack

# All features
cargo install zerostack --all-features

# Specific features
cargo install zerostack --features acp,memory,multithread

Optional: Sandbox mode

For --sandbox protection, install bubblewrap:

# Debian/Ubuntu
apt install bubblewrap

# Fedora
dnf install bubblewrap

# Arch
pacman -S bubblewrap

3.2 Quick Start

# Set API key (default uses OpenRouter)
export OPENROUTER_API_KEY="your-api-key"

# Interactive session (default prompt: code)
zerostack

# No-color TUI
zerostack --no-color

# Single question mode
zerostack -p "Explain this project"

# Resume last session
zerostack -c

# Specify provider and model
zerostack --provider openrouter --model deepseek/deepseek-v4-flash

On first run, execute /prompt autoconfig to launch the interactive configuration wizard, guiding you through all settings.

3.3 Configuration Details

zerostack reads configuration files in the following priority:

• $ZS_CONFIG_DIR/config.toml or config.json
• ~/.config/zerostack/config.toml or config.json
• ~/.local/share/zerostack/config.toml or config.json

On macOS, the path is ~/Library/Application Support/zerostack/.

TOML format is recommended (more friendly for permission rules):

provider = "openrouter"
model = "deepseek/deepseek-v4-flash"
max_tokens = 16384
temperature = 0.7
context_window = 128000
reserve_tokens = 16384
keep_recent_tokens = 10000
compact_enabled = true
default_prompt = "code"
default_permission_mode = "standard"
show_tool_details = 3

[quick_models.fast]
provider = "openai"
model = "gpt-4o-mini"

[custom_providers.local-vllm]
provider_type = "openai"
base_url = "http://localhost:8000/v1"
api_key_env = "VLLM_API_KEY"

[permission]
"*" = "ask"

[permission.read]
"**/*.rs" = "allow"
"**" = "ask"

[permission.bash]
"cargo test" = "allow"
"rm **" = "deny"

[permission.write]
"src/**/*.rs" = "allow"
"**" = "ask"

Key configuration fields explained:

Field	Description
context_window	Session context window size (default 128k)
reserve_tokens	Tokens to reserve before triggering compression
keep_recent_tokens	Token budget for recent conversation to keep during compression
compact_enabled	Automatic conversation compression (prevents context overflow)
deny_repeated_reads	Prohibit repeated reads of the same file segment (default true)
edit_system	similarity (default, SEARCH/REPLACE) or hashedit (CRC-32 tag-based editing)
show_tool_details	Number of tool result preview lines shown in TUI

3.4 Permission System in Practice

zerostack provides five permission modes, switchable via CLI flags or the /mode command:

Mode	Flag	Behavior
restrictive	-R / --restrictive	Ask for every operation
readonly	--read-only	Only read operations allowed
guarded	--guarded	Read auto-allowed, write/edit/execute ask
standard	(default)	Path tools within CWD auto-allowed, safe bash auto-allowed, external paths and unknown commands ask
yolo	--yolo	All allowed, but destructive bash commands (rm/dd etc.) still ask

Fine-grained configuration example:

[permission]
"*" = "ask"  # default ask

[permission.write]
"**/*.rs" = "allow"   # .rs files auto-allowed for writing
"**/*.md" = "allow"   # .md files auto-allowed for writing
"**" = "ask"          # other files ask

[permission.bash]
"cargo test" = "allow"     # tests auto-allowed
"cargo check" = "allow"    # checks auto-allowed
"git status" = "allow"     # git status auto-allowed
"rm **" = "deny"           # deletion denied
"sudo **" = "ask"          # sudo asks

Session whitelist: Once you approve an operation within a session, zerostack remembers that decision and won’t ask again.

3.5 Prompt System: Context Switching Without Skills

zerostack has several built-in prompt modes, switchable at runtime with /prompt:

Prompt	Purpose
code (default)	Coding mode, full file and bash tool access, TDD workflow
plan	Plan only — explore and generate a plan, no code writing
review	Code review — check correctness, design, tests, and impact
debug	Debug mode — find root cause first, then propose fix
ask	Read-only mode — only allow read/grep/find_files
brainstorm	Design mode — explore ideas and present designs, no code writing
frontend-design	Frontend design mode — production-ready UI design
review-security	Security audit mode — look for exploitable vulnerabilities
simplify	Code simplification mode — optimize clarity without changing behavior
write-prompt	Prompt writing mode — create and refine Agent prompts

Custom prompts: Place Markdown files in ~/.local/share/zerostack/prompts/, then invoke them via /prompt <filename>.

Prompt directives: The first line of a custom prompt file can contain %%mode=standard etc. to automatically switch security modes.

3.6 Session Management

# List all sessions
/session

# Save current session
/session save my-feature

# Load a specific session
zerostack --session my-feature

# Resume most recent session
zerostack -c

# Browse and select a session
zerostack -r

Sessions are auto-saved to $XDG_DATA_HOME/zerostack/sessions/. zerostack automatically compresses history: when token count nears the context window, older messages are summarized and discarded, preserving a summary prefix and the most recent full conversation.

3.7 Advanced Features

3.7.1 Loop Tasks

Great for long-running iterative tasks:

# Start a loop
/loop Implement the user authentication system

# Check status
/loop status

# Stop the loop
/loop stop

Headless mode (for CI/CD):

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

3.7.2 Git Worktrees

Branch-level isolation without polluting the main workspace:

# Create and enter a worktree
/worktree feature-x

# Work... then merge back to main
/wt-merge

# Or exit without merging
/wt-exit

3.7.3 Parallel Sub-Agent (/btw)

Ask parallel questions without interrupting the main agent:

# Quick side question (read-only tools)
/btw How does the error handling work in this module?

# Point to a specific file
/btw @src/main.rs how does the auth flow work?

/btw forks the current context, uses 4 read-only tools to answer, does not write to conversation history, and token consumption is shown separately in the status bar.

3.7.4 Input Queue

While the agent is running, you can keep typing; your input is automatically queued and executed sequentially after the current task completes:

/queue ls      # view queued inputs
/queue clear   # clear the queue
/queue pop     # remove the last item

3.8 ACP Mode (Editor Integration)

After enabling the acp feature, zerostack can serve as an ACP Agent server for editors like Zed:

# stdio mode (editor launches as parent process)
zerostack --acp

# TCP mode
zerostack --acp --acp-host 0.0.0.0 --acp-port 7243

4. Best Practices: Squeezing Every Drop of Performance from zerostack

4.1 Configuration Best Practices

1. Use TOML instead of JSON for permissions

TOML’s table structure naturally fits zerostack’s permission rules, avoiding deep nesting of JSON:

permission-allow = { read = ["src/**", "tests/**"] }
permission-ask = { bash = ["rm **", "docker **"] }
permission-deny = { write = ["/etc/**", "/usr/**"] }

2. Create separate configs for different projects

Use the ZS_CONFIG_DIR environment variable to point to per-project configurations:

# Project A
export ZS_CONFIG_DIR=~/projects/a/.zerostack
zerostack

# Project B
export ZS_CONFIG_DIR=~/projects/b/.zerostack
zerostack

3. Tune context window appropriately

If your model supports 128k context, keep defaults. For smaller models, lower context_window and reserve_tokens:

context_window = 32000
reserve_tokens = 4096
keep_recent_tokens = 5000

4. Enable hashedit editing system (for large files)

For frequent large-file editing, hashedit is more token-efficient than similarity:

edit_system = "hashedit"

hashedit uses CRC-32 line labels and file-level CAS tokens — no need to copy old text, making deletion and bulk edits significantly more token-efficient.

4.2 Security Best Practices

1. Default to guarded mode for exploring new projects

When entering an unfamiliar codebase, start with --guarded mode. Confirm the agent’s behavior matches expectations before switching to standard or yolo.

2. Fine-grained bash permissions

Never globally allow rm or sudo:

[permission.bash]
"rm **" = "deny"
"sudo **" = "ask"
"dd **" = "deny"
"mkfs **" = "deny"

3. Use sandbox to protect your system

zerostack --sandbox

bubblewrap creates isolated environments for each bash command, preventing accidental or malicious damage.

4. Leverage ARCHITECTURE.md for project context

Create an ARCHITECTURE.md (or enable the archmd feature) at the root of your repository to describe your project’s architecture. zerostack automatically injects it into the system prompt, giving all agents (including sub-agents) shared knowledge.

4.3 Workflow Best Practices

1. Plan → Code → Review three-stage workflow

# Step 1: Plan
/prompt plan
"Design a user authentication system with JWT, refresh tokens, and role-based permissions"

# Step 2: Code
/prompt code
"Implement the authentication system according to PLAN.md"

# Step 3: Review
/prompt review
"Review all code under src/auth/"

2. Use Git Worktrees for parallel development

# Keep main branch clean
/worktree feature-a
# ... work ...
/wt-merge

/worktree feature-b
# ... work ...
/wt-merge

3. Use Loop + validation commands for long tasks

zerostack --loop --loop-prompt "Optimize all SQL queries" --loop-run "cargo test --test integration" --loop-max 5

4. Naming convention for sessions

/session save 20250610-refactor-auth
/session save 20250610-fix-race-condition

Makes retrieval and resumption easier later.

4.4 Performance Best Practices

1. Default build is sufficient for daily use

Unless you need ACP, Memory, or sub-agents, stick with the default build:

cargo install zerostack

2. Use mimalloc

zerostack already bundles mimalloc as the global allocator — no extra configuration needed for best memory performance.

3. Limit tool details display

show_tool_details = 3

Reduces TUI rendering load, especially on low‑performance terminals.

5. Overall Assessment: Who Should Choose zerostack?

5.1 Ideal For

• Resource‑sensitive developers: On old laptops, cloud servers, or when running multiple agents concurrently, zerostack’s low footprint is a huge advantage.
• Rust ecosystem developers: Rust projects using Rust tools – consistent philosophy on types and memory safety.
• Terminal / CLI enthusiasts: Custom crossterm TUI is snappy, no Electron sluggishness.
• Security‑conscious users: Five‑tier permissions + glob/regex granularity + Doom‑loop detection give maximum control.
• Multi‑model switchers: OpenRouter by default, one‑key switch to OpenAI/Anthropic/Gemini/Ollama.

5.2 Not Ideal For

• Pure GUI users: zerostack is a terminal tool – no graphical interface.
• Primary Windows users: The project explicitly notes Windows support is untested.
• Out‑of‑box‑experience users: Compared to opencode, zerostack requires more manual configuration (though /prompt autoconfig has greatly improved this).

5.3 Comparison with Competitors

Dimension	zerostack	opencode	Claude Code
Language	Rust	TypeScript/Node	TypeScript
RAM Usage	~16MB	~300MB	~200MB+
Binary Size	26MB	Hundreds of MB	Hundreds of MB
Permission Control	Five‑tier + glob/regex	Basic	Basic
Editing System	similarity/hashedit	Standard	Standard
Self‑built TUI	Yes (crossterm)	No	No
MCP Support	Compile‑time feature	Built‑in	Built‑in
ACP Support	Compile‑time feature	No	No
Open‑Source License	GPL-3.0	Depends on project	Closed‑source

5.4 Conclusion

zerostack proves that “minimalist” does not equal “bare‑bones.” With roughly 17k lines of Rust, a 26MB binary, and 16MB RAM, it builds a fully‑featured, secure, and performance‑crushing coding agent. Its design philosophy — single‑crate architecture, type‑erased enums, custom TUI, feature‑gated extensions, two‑layer permissions — demonstrates an obsessive pursuit of resource efficiency.

In an era of increasingly bloated AI tools, zerostack is like a precision scalpel: no unnecessary ornamentation, but every millimeter is tempered. If you believe code should be as concise as poetry, and tools as sharp as a blade, zerostack deserves a place at the core of your toolkit.

Project repo: https://github.com/gi-dellav/zerostack Matrix chat room: Link provided in the project README License: GPL-3.0-only