# gi-dellav/zerostack architecture

> Architecture diagram of the GitHub repository gi-dellav/zerostack, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/gi-dellav/zerostack
- Repository: https://github.com/gi-dellav/zerostack

## Overview

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: [`src/extras/mod.rs`](https://github.com/gi-dellav/zerostack/blob/main/src/extras/mod.rs) (Extras), [`src/agent/mod.rs`](https://github.com/gi-dellav/zerostack/blob/main/src/agent/mod.rs) (Agent Core), [`src/cli.rs`](https://github.com/gi-dellav/zerostack/blob/main/src/cli.rs) (CLI), [`src/ui/mod.rs`](https://github.com/gi-dellav/zerostack/blob/main/src/ui/mod.rs) (TUI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime & Entry"]
  node_main(("Main<br/>entrypoint<br/>[main.rs]"))
  node_cli["CLI<br/>flag parser<br/>[cli.rs]"]
  node_ui["TUI<br/>terminal ui<br/>[mod.rs]"]
  node_event(("Events<br/>event bus<br/>[event.rs]"))
end

subgraph group_core["Agent Core"]
  node_agent["Agent Core<br/>orchestrator<br/>[mod.rs]"]
  node_builder["Builder<br/>agent setup<br/>[builder.rs]"]
  node_runner["Runner<br/>execution loop<br/>[runner.rs]"]
  node_prompt["Prompt<br/>[prompt.rs]"]
  node_tools["Tools<br/>[mod.rs]"]
  node_provider[("Provider<br/>llm boundary<br/>[provider.rs]")]
  node_auth["Auth<br/>credentials<br/>[auth.rs]"]
  node_catalog["Models Catalog<br/>model registry<br/>[models_catalog.rs]"]
end

subgraph group_safety["Safety & Policy"]
  node_permission["Permissions<br/>policy engine<br/>[mod.rs]"]
  node_sandbox["Sandbox<br/>shell isolation<br/>[sandbox.rs]"]
end

subgraph group_state["State & Context"]
  node_context["Context<br/>[mod.rs]"]
  node_session[("Session<br/>persistent state<br/>[mod.rs]")]
  node_memory["Memory<br/>persistent notes<br/>[mod.rs]"]
end

subgraph group_integration["Extensions & Protocols"]
  node_extras["Extras<br/>feature-gated extensions<br/>[mod.rs]"]
  node_mcp[("MCP<br/>tool protocol<br/>[mod.rs]")]
  node_acp[("ACP<br/>server protocol<br/>[mod.rs]")]
  node_subagents["Subagents<br/>parallel agents<br/>[mod.rs]"]
  node_loop["Loop Mode<br/>long-horizon flow<br/>[mod.rs]"]
  node_worktree["Worktree<br/>workspace management<br/>[mod.rs]"]
end

node_main -->|"startup"| node_cli
node_cli -->|"interactive mode"| node_ui
node_cli -->|"headless run"| node_agent
node_cli -->|"server mode"| node_acp
node_ui -->|"input/output"| node_event
node_event -->|"turns"| node_agent
node_agent -->|"configure"| node_builder
node_builder -->|"assemble"| node_prompt
node_agent -->|"execute"| node_runner
node_runner -->|"llm request"| node_provider
node_provider -->|"credentials"| node_auth
node_provider -->|"model lookup"| node_catalog
node_runner -->|"tool calls"| node_tools
node_tools -->|"gate actions"| node_permission
node_tools -->|"shell safety"| node_sandbox
node_agent -->|"load context"| node_context
node_context -->|"resume state"| node_session
node_context -->|"inject notes"| node_memory
node_extras -->|"protocol extension"| node_mcp
node_extras -->|"serve agent"| node_acp
node_extras -->|"parallel work"| node_subagents
node_extras -->|"iterative mode"| node_loop
node_extras -->|"isolated workspace"| node_worktree
node_agent -.->|"feature gates"| node_extras
node_ui -->|"save/resume"| node_session

click node_main "https://github.com/gi-dellav/zerostack/blob/main/src/main.rs"
click node_cli "https://github.com/gi-dellav/zerostack/blob/main/src/cli.rs"
click node_ui "https://github.com/gi-dellav/zerostack/blob/main/src/ui/mod.rs"
click node_event "https://github.com/gi-dellav/zerostack/blob/main/src/event.rs"
click node_agent "https://github.com/gi-dellav/zerostack/blob/main/src/agent/mod.rs"
click node_builder "https://github.com/gi-dellav/zerostack/blob/main/src/agent/builder.rs"
click node_runner "https://github.com/gi-dellav/zerostack/blob/main/src/agent/runner.rs"
click node_prompt "https://github.com/gi-dellav/zerostack/blob/main/src/agent/prompt.rs"
click node_tools "https://github.com/gi-dellav/zerostack/blob/main/src/agent/tools/mod.rs"
click node_provider "https://github.com/gi-dellav/zerostack/blob/main/src/provider.rs"
click node_auth "https://github.com/gi-dellav/zerostack/blob/main/src/auth.rs"
click node_catalog "https://github.com/gi-dellav/zerostack/blob/main/src/models_catalog.rs"
click node_permission "https://github.com/gi-dellav/zerostack/blob/main/src/permission/mod.rs"
click node_sandbox "https://github.com/gi-dellav/zerostack/blob/main/src/sandbox.rs"
click node_context "https://github.com/gi-dellav/zerostack/blob/main/src/context/mod.rs"
click node_session "https://github.com/gi-dellav/zerostack/blob/main/src/session/mod.rs"
click node_memory "https://github.com/gi-dellav/zerostack/blob/main/src/extras/memory/mod.rs"
click node_extras "https://github.com/gi-dellav/zerostack/blob/main/src/extras/mod.rs"
click node_mcp "https://github.com/gi-dellav/zerostack/blob/main/src/extras/mcp/mod.rs"
click node_acp "https://github.com/gi-dellav/zerostack/blob/main/src/extras/acp/mod.rs"
click node_subagents "https://github.com/gi-dellav/zerostack/blob/main/src/extras/subagents/mod.rs"
click node_loop "https://github.com/gi-dellav/zerostack/blob/main/src/extras/loop/mod.rs"
click node_worktree "https://github.com/gi-dellav/zerostack/blob/main/src/extras/git_worktree/mod.rs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_cli,node_ui,node_event toneBlue
class node_agent,node_builder,node_runner,node_prompt,node_tools,node_provider,node_auth,node_catalog toneAmber
class node_permission,node_sandbox toneMint
class node_context,node_session,node_memory toneRose
class node_extras,node_mcp,node_acp,node_subagents,node_loop,node_worktree toneIndigo
```

## Components

### Runtime & Entry

Startup, mode selection, terminal interaction, and process boundaries.

- [Main](https://github.com/gi-dellav/zerostack/blob/main/src/main.rs): entrypoint · Bootstraps the app and selects operating mode. · `src/main.rs`
- [CLI](https://github.com/gi-dellav/zerostack/blob/main/src/cli.rs): flag parser · Parses commands, flags, and mode selection. · `src/cli.rs`
- [TUI](https://github.com/gi-dellav/zerostack/blob/main/src/ui/mod.rs): terminal ui · Interactive terminal interface for chat, status, and commands. · `src/ui/mod.rs`
- [Events](https://github.com/gi-dellav/zerostack/blob/main/src/event.rs): event bus · Connects user input, model output, tool events, and prompts. · `src/event.rs`

### Agent Core

Main orchestration loop, prompt assembly, provider calls, and local tools.

- [Agent Core](https://github.com/gi-dellav/zerostack/blob/main/src/agent/mod.rs): orchestrator · Builds the agent, assembles context, and runs the loop. · `src/agent/mod.rs`
- [Builder](https://github.com/gi-dellav/zerostack/blob/main/src/agent/builder.rs): agent setup · Configures tools, policies, and runtime dependencies. · `src/agent/builder.rs`
- [Runner](https://github.com/gi-dellav/zerostack/blob/main/src/agent/runner.rs): execution loop · Drives model turns, tool calls, and completion. · `src/agent/runner.rs`
- [Prompt](https://github.com/gi-dellav/zerostack/blob/main/src/agent/prompt.rs): prompt assembly · Constructs system and task prompts from templates and context. · `src/agent/prompt.rs`
- [Tools](https://github.com/gi-dellav/zerostack/blob/main/src/agent/tools/mod.rs): local tools · Filesystem and shell capabilities exposed to the model. · `src/agent/tools/mod.rs`
- [Provider](https://github.com/gi-dellav/zerostack/blob/main/src/provider.rs): llm boundary · Abstracts remote model backends and API calls. · `src/provider.rs`
- [Auth](https://github.com/gi-dellav/zerostack/blob/main/src/auth.rs): credentials · Handles provider authentication and token setup. · `src/auth.rs`
- [Models Catalog](https://github.com/gi-dellav/zerostack/blob/main/src/models_catalog.rs): model registry · Loads supported models and provider metadata. · `src/models_catalog.rs`

### Safety & Policy

Permission checks and shell sandboxing around side-effecting actions.

- [Permissions](https://github.com/gi-dellav/zerostack/blob/main/src/permission/mod.rs): policy engine · Decides whether actions are auto-approved, denied, or confirmed. · `src/permission/mod.rs`
- [Sandbox](https://github.com/gi-dellav/zerostack/blob/main/src/sandbox.rs): shell isolation · Constrains shell execution for unsafe or privileged commands. · `src/sandbox.rs`

### State & Context

Session history, prompt resources, and persistent memory inputs.

- [Context](https://github.com/gi-dellav/zerostack/blob/main/src/context/mod.rs): context assembly · Loads docs, themes, prompts, and repo context into runs. · `src/context/mod.rs`
- [Session](https://github.com/gi-dellav/zerostack/blob/main/src/session/mod.rs): persistent state · Stores chat history and resumable session metadata. · `src/session/mod.rs`
- [Memory](https://github.com/gi-dellav/zerostack/blob/main/src/extras/memory/mod.rs): persistent notes · Optional markdown memory injected across sessions. · `src/extras/memory/mod.rs`

### Extensions & Protocols

Optional feature-gated integrations and execution strategies.

- [Extras](https://github.com/gi-dellav/zerostack/blob/main/src/extras/mod.rs): feature-gated extensions · Holds optional integrations and alternative execution strategies. · `src/extras/mod.rs`
- [MCP](https://github.com/gi-dellav/zerostack/blob/main/src/extras/mcp/mod.rs): tool protocol · Connects external tool servers into the agent toolset. · `src/extras/mcp/mod.rs`
- [ACP](https://github.com/gi-dellav/zerostack/blob/main/src/extras/acp/mod.rs): server protocol · Exposes zerostack as a protocol server for editors. · `src/extras/acp/mod.rs`
- [Subagents](https://github.com/gi-dellav/zerostack/blob/main/src/extras/subagents/mod.rs): parallel agents · Spawns smaller task-focused agents for exploration. · `src/extras/subagents/mod.rs`
- [Loop Mode](https://github.com/gi-dellav/zerostack/blob/main/src/extras/loop/mod.rs): long-horizon flow · Runs iterative plan/transcript execution for long tasks. · `src/extras/loop/mod.rs`
- [Worktree](https://github.com/gi-dellav/zerostack/blob/main/src/extras/git_worktree/mod.rs): workspace management · Creates branch-per-task git worktrees for isolated changes. · `src/extras/git_worktree/mod.rs`

## Connections

- 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.