How gi-dellav/zerostack works
1. What this repository is
- zerostack is a Rust-based interactive coding agent CLI with a terminal UI.
- Its core architecture is a loop between the user, the local agent runtime, local tools, and a remote LLM provider.
- The repo is organized around a small always-on core plus several optional feature-gated subsystems.
2. Entry points and top-level control flow
- src/main.rs and src/cli.rs handle startup, flag parsing, feature selection, and mode selection.
- The main runtime can enter interactive TUI mode, one-shot prompt mode, session resume mode, ACP server mode, or loop/worktree modes depending on CLI flags.
- The CLI layer is the boundary that decides whether the process behaves like a terminal app, a headless automation tool, or a protocol server.
3. Core agent execution pipeline
- src/agent/ contains the agent builder, prompt assembly, and run loop.
- The agent receives a user prompt, combines it with context, permissions, memory/prompts, and available tools, then sends requests to a provider.
- Responses from the model are turned into tool calls or assistant text, and the loop continues until completion.
- This is the central orchestration layer connecting UI, providers, permissions, and filesystem tools.
4. Provider boundary: remote LLMs vs local runtime
- src/provider.rs, src/auth.rs, src/models_catalog.rs, and data/models.json implement model/provider discovery and API authentication.
- Supported backends include OpenRouter, OpenAI-compatible APIs, Anthropic, Gemini, Ollama, and custom providers.
- This boundary isolates network/API concerns from the agent logic, so the agent speaks in a provider-agnostic way.
5. Tooling subsystem: local capabilities exposed to the model
- src/agent/tools/ implements the standard agent tools such as read, write, edit, grep, list_dir, find_files, bash, todo, and normalization helpers.
- Tools are the agent’s interface to the local repository and shell; they are the main source of side effects.
- Tool execution is separated from the model provider, which lets permissions and sandboxing be enforced locally before anything runs.
6. Permission and safety boundary
- src/permission/ implements the policy engine for deciding whether a tool action is auto-approved, denied, or must be confirmed.
- The readme describes multiple modes: restrictive, readonly, guarded, standard, and yolo, plus per-tool glob rules and a session allowlist.
- src/sandbox.rs and the bash tool together define the execution safety boundary for shell commands, including optional sandbox backends such as bubblewrap/zerobox.
7. UI and interaction model
- src/ui/ contains the crossterm-based terminal UI, markdown rendering, status line, pickers, slash command handling, and input queue management.
- src/ui/event_handler.rs, src/ui/events.rs, and src/event.rs coordinate user input, model output, tool events, and permission prompts.
- The UI is not just presentation: it is the interaction hub for model selection, session control, prompt switching, queueing, and side-question workflows like /btw.
8. Context assembly and prompt system
- src/context/ and src/agent/prompt.rs assemble the system prompt from built-in prompt templates, docs, theme/resource data, and repo context files.
- Built-in prompts live in prompts/ and are exposed through slash commands like /prompt; these change the agent’s behavior without changing code.
- AGENTS.md and optionally ARCHITECTURE.md are treated as shared context inputs, which is important because the repo is designed to cooperate with other agents and editors.
9. Persistent state: sessions, memory, and history
- src/session/ stores chat history and session metadata so runs can be resumed, saved, or compacted.
- Session data is persisted under the user’s data directory; this is part of the long-lived state boundary outside the repo checkout.
- Optional memory support under src/extras/memory/ adds Markdown-based persistent memory injected into prompts across sessions.
10. Optional “extras” subsystems
- src/extras/ houses feature-gated capabilities that extend the core agent without changing its base architecture.
- Notable extras include MCP client support, ACP server support, subagents, loop automation, git worktree management, advisor/archmd integrations, multimodal support, truncation helpers, and status signals.
- These are all integration layers: they either add new external protocols, parallel task execution, or richer control workflows on top of the same agent/tool/provider core.
11. Subagents, loops, and worktrees as execution strategies
- src/extras/subagents/ runs smaller parallel agents for exploration tasks.
- src/extras/loop/ implements iterative long-horizon task execution with a plan/transcript loop.
- src/extras/git_worktree/ manages branch-per-task worktrees, which changes the filesystem workspace boundary without changing the agent core.
12. MCP and ACP integration boundaries
- MCP support under src/extras/mcp/ lets the agent connect to external tool servers over a protocol boundary, effectively extending the tool catalog.
- ACP support under src/extras/acp/ turns zerostack into a protocol server for editors like Zed.
- Both features are optional and sit at the edge of the architecture: one imports external tools, the other exports the agent as a backend service.
13. Supporting assets, docs, and distribution
- docs/, ARCHITECTURE.md, and README.md document the runtime behavior, config, commands, and feature boundaries.
- Packaging is broad: Cargo, Nix, Homebrew, AUR, Conda, and release workflows are all present, but they do not change runtime architecture.
- The presence of CI, release automation, model catalog generation, and packaging scripts indicates a project optimized for distributable CLI deployment rather than a server-centric runtime.
14. How data flows through the system
- User input enters through the TUI or CLI, becomes a session turn, is merged with prompt/context state, and is sent to a provider.
- The provider returns model text or tool-call intent; the agent resolves tool calls locally through permissions, sandboxing, and filesystem/shell access.
- Tool results and assistant text feed back into session history and the UI, with optional persistence to session storage, memory files, worktrees, or loop transcripts.
Main entry points: extras/mod.rs Extras · agent/mod.rs Agent Core · cli.rs CLI · ui/mod.rs TUI
Components 23
Runtime & Entry
Startup, mode selection, terminal interaction, and process boundaries.
Agent Core
Main orchestration loop, prompt assembly, provider calls, and local tools.
- Agent Core · Builds the agent, assembles context, and runs the loop.
src/agent/mod.rs - Builder · Configures tools, policies, and runtime dependencies.
src/agent/builder.rs - Runner · Drives model turns, tool calls, and completion.
src/agent/runner.rs - Prompt · Constructs system and task prompts from templates and context.
src/agent/prompt.rs - Tools · Filesystem and shell capabilities exposed to the model.
src/agent/tools/mod.rs - Provider · Abstracts remote model backends and API calls.
src/provider.rs - Auth · Handles provider authentication and token setup.
src/auth.rs - Models Catalog · Loads supported models and provider metadata.
src/models_catalog.rs
Safety & Policy
Permission checks and shell sandboxing around side-effecting actions.
- Permissions · Decides whether actions are auto-approved, denied, or confirmed.
src/permission/mod.rs - Sandbox · Constrains shell execution for unsafe or privileged commands.
src/sandbox.rs
State & Context
Session history, prompt resources, and persistent memory inputs.
Extensions & Protocols
Optional feature-gated integrations and execution strategies.
- Extras · Holds optional integrations and alternative execution strategies.
src/extras/mod.rs - MCP · Connects external tool servers into the agent toolset.
src/extras/mcp/mod.rs - ACP · Exposes zerostack as a protocol server for editors.
src/extras/acp/mod.rs - Subagents · Spawns smaller task-focused agents for exploration.
src/extras/subagents/mod.rs - Loop Mode · Runs iterative plan/transcript execution for long tasks.
src/extras/loop/mod.rs - Worktree · Creates branch-per-task git worktrees for isolated changes.
src/extras/git_worktree/mod.rs
Connections 25
- Main → CLI: startup · Main hands control to CLI parsing and mode selection.
- CLI → TUI: interactive mode · CLI can launch the terminal UI for chat sessions.
- CLI → Agent Core: headless run · CLI can invoke the agent directly for one-shot or resume modes.
- CLI → ACP: server mode · CLI can start the ACP protocol server.
- TUI → Events: input/output · UI emits and consumes events for user actions and model responses.
- Events → Agent Core: turns · Events feed agent execution and side-question workflows.
- Agent Core → Builder: configure · Agent construction prepares tools, prompts, and policies.
- Builder → Prompt: assemble · Builder wires context into the prompt pipeline.
- Agent Core → Runner: execute · Runner performs the core model-tool loop.
- Runner → Provider: llm request · Runner sends prompts and receives model output from a provider.
- Provider → Auth: credentials · Provider setup depends on authentication and API configuration.
- Provider → Models Catalog: model lookup · Provider selection uses the model/provider registry.
- Runner → Tools: tool calls · Model tool intents are resolved through local tools.
- Tools → Permissions: gate actions · Tool execution is checked against approval policy before side effects.
- Tools → Sandbox: shell safety · Bash-style execution may be constrained by sandboxing.
- Agent Core → Context: load context · Agent assembles repo docs, prompts, themes, and resources.
- Context → Session: resume state · Session history and metadata contribute to the active run.
- Context → Memory: inject notes · Optional memory content is merged into prompts across sessions.
- Extras → MCP: protocol extension · MCP extends the tool boundary with external servers.
- Extras → ACP: serve agent · ACP exposes the agent through a protocol server boundary.
- Extras → Subagents: parallel work · Subagents provide multi-agent task decomposition.
- Extras → Loop Mode: iterative mode · Loop mode adds long-horizon planning and transcript tracking.
- Extras → Worktree: isolated workspace · Worktree management changes the filesystem workspace boundary.
- Agent Core → Extras: feature gates · Core agent can enable optional subsystems when configured.
- TUI → Session: save/resume · UI interacts with session storage for persistent conversations.