gi-dellav/zerostack

zerostack – a lightweight, Rust‑based coding assistant

What it does – zerostack is a terminal‑based AI “coding agent” that can write, plan, review, debug, and refactor code for you. It talks to large‑language‑model providers (OpenAI, Anthropic, Gemini, OpenRouter, Ollama, etc.) and then uses a toolbox of built‑in utilities (file read/write, grep, git, shell commands, web search, etc.) to carry out the requested task. The whole system runs as a single native binary (≈ 26 MB) written in Rust, aiming for low memory/CPU usage compared with JavaScript‑based alternatives.

Key features

• Multi‑provider support – plug in any LLM service, plus a custom‑provider hook.
• Rich prompt library – switch at runtime between built‑in system prompts such as code, plan, review, debug, brainstorm, frontend‑design, etc., or add your own markdown prompts.
• Permission system – five safety modes (restrictive, readonly, guarded, standard, yolo) that control which tools the agent may invoke, with per‑tool glob rules and a session‑wide allow‑list.
• Session persistence – save, load, and resume sessions; automatic context‑window compaction; optional plain‑markdown memory that is injected into the system prompt across runs.
• Terminal UI – crossterm TUI with markdown rendering, mouse copy, scrollback, and a toggle to show the model’s “thinking” trace.
• Extensibility – optional compile‑time features for:
  • MCP (agent‑communication protocol) to connect editors like Zed.
  • Advisor – a second model that can be consulted for strategic guidance or handed off to a human.
  • Hooks – external commands that can observe or veto tool calls, using the same JSON contract as Claude Code.
  • Multimodal input – attach images or PDFs (if the provider supports it).
  • Status signals – emit run‑state events over a Unix socket for external status bars.
• Subagents & parallel work – spawn fast, parallel sub‑agents to explore a codebase or run multistack for managing several agents simultaneously.
• Sandboxing – optional bubblewrap (Linux) or zerobox (macOS) isolation for any shell command the agent runs, with fine‑grained exposure of credential directories and network control.

How you use it

1. Install via the provided script, Cargo, Homebrew, or Nix.
2. Export an API key for your LLM provider (OpenRouter is the default).
3. Run zerostack – you get a TUI where you can type natural‑language requests.
4. Change the agent’s behavior on the fly with /prompt <name> or /mode <permission‑mode>.
5. Save the session (/session save) and resume later (zerostack -c).

Why it matters

• Performance – ~16 MiB RAM and near‑zero idle CPU, making it suitable for low‑end machines or long‑running sessions.
• Safety – the permission system and sandboxing aim to prevent accidental destructive commands, a common concern with autonomous coding bots.
• Native Rust – avoids the heavyweight Node.js runtimes that many competing agents require, giving faster start‑up and a smaller attack surface.
• Customizable workflow – prompt chaining lets you move from brainstorming → planning → coding → review in a guided, repeatable process.

Getting started – The repo includes a full Get Started guide, a quick‑install script, and a dedicated Matrix chatroom for community support.

---

All details above are taken directly from the project's README.