# gitlawb/zero architecture

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

- Interactive diagram: https://gitdiagram.com/gitlawb/zero
- Repository: https://github.com/gitlawb/zero

## Overview

Zero is a local-terminal AI coding agent. Its principal workflow starts with an interactive prompt or headless command, runs an agent turn against a configured model, invokes workspace and command tools under permission and sandbox controls, then presents results and preserves session state locally. Other documented capabilities include provider setup, MCP and specialist extensions, language-server diagnostics, and resumable sessions. The map follows the README and repository paths; sampled excerpts are incomplete, so uncertain internal wiring is omitted.

Main entry points: [`internal/cli/app.go`](https://github.com/gitlawb/zero/blob/main/internal/cli/app.go) (CLI Router), [`internal/agent/loop.go`](https://github.com/gitlawb/zero/blob/main/internal/agent/loop.go) (Agent Loop), [`internal/tools/builtin_catalog.go`](https://github.com/gitlawb/zero/blob/main/internal/tools/builtin_catalog.go) (Workspace Tools), [`internal/tui/run.go`](https://github.com/gitlawb/zero/blob/main/internal/tui/run.go) (Terminal UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["User Interaction"]
  node_cli["CLI Router<br/>[app.go]"]
  node_tui["Terminal UI<br/>[run.go]"]
end

subgraph group_agent["Agent Runtime"]
  node_agent_loop["Agent Loop<br/>[loop.go]"]
  node_lsp["Code Diagnostics<br/>[manager.go]"]
end

subgraph group_safety["Tools and Safety"]
  node_tool_registry["Tool Registry<br/>[registry.go]"]
  node_workspace_tools["Workspace Tools<br/>[builtin_catalog.go]"]
  node_sandbox["Sandbox Policy<br/>[engine.go]"]
  node_execution["Command Execution<br/>[runner.go]"]
end

subgraph group_state["Local State"]
  node_session_store[("Session Store<br/>[store.go]")]
  node_config["Provider Configuration<br/>[resolver.go]"]
  node_credentials[("Credential Store<br/>[credstore.go]")]
  node_daemon["Session Daemon<br/>[server.go]"]
end

subgraph group_extensions["Providers and Extensions"]
  node_providers["Model Providers<br/>[factory.go]"]
  node_oauth["OAuth Login<br/>[manager.go]"]
  node_mcp["MCP Integration<br/>[registry.go]"]
  node_specialists["Specialist Agents<br/>[runtime.go]"]
  node_skills_plugins["Skills and Plugins<br/>[skills.go]"]
  node_hooks["Hooks<br/>[dispatch.go]"]
end

node_user(("Terminal User"))
node_model_service(("Model API"))
node_workspace["Project Files"]
node_mcp_server(("MCP Servers"))

node_user -->|"runs commands"| node_cli
node_cli -->|"starts TUI"| node_tui
node_cli -->|"runs headless turn"| node_agent_loop
node_tui -->|"submits prompt"| node_agent_loop
node_cli -->|"loads configuration"| node_config
node_cli -->|"opens sessions"| node_session_store
node_agent_loop -->|"requests completion"| node_providers
node_providers -->|"sends model request"| node_model_service
node_agent_loop -->|"dispatches tool calls"| node_tool_registry
node_tool_registry -->|"resolves tools"| node_workspace_tools
node_workspace_tools -->|"reads and edits"| node_workspace
node_workspace_tools -->|"checks permissions"| node_sandbox
node_workspace_tools -->|"runs commands"| node_execution
node_execution -->|"operates in workspace"| node_workspace
node_workspace_tools -.->|"requests diagnostics"| node_lsp
node_agent_loop -->|"persists turns"| node_session_store
node_config -->|"resolves secrets"| node_credentials
node_cli -->|"manages login"| node_oauth
node_oauth -->|"stores tokens"| node_credentials
node_cli -->|"configures servers"| node_mcp
node_mcp -.->|"connects tools"| node_mcp_server
node_agent_loop -.->|"runs subagents"| node_specialists
node_cli -->|"manages extensions"| node_skills_plugins
node_cli -->|"dispatches hooks"| node_hooks
node_cli -.->|"starts daemon"| node_daemon

click node_cli "https://github.com/gitlawb/zero/blob/main/internal/cli/app.go"
click node_tui "https://github.com/gitlawb/zero/blob/main/internal/tui/run.go"
click node_agent_loop "https://github.com/gitlawb/zero/blob/main/internal/agent/loop.go"
click node_providers "https://github.com/gitlawb/zero/blob/main/internal/providers/factory.go"
click node_tool_registry "https://github.com/gitlawb/zero/blob/main/internal/tools/registry.go"
click node_workspace_tools "https://github.com/gitlawb/zero/blob/main/internal/tools/builtin_catalog.go"
click node_sandbox "https://github.com/gitlawb/zero/blob/main/internal/sandbox/engine.go"
click node_execution "https://github.com/gitlawb/zero/blob/main/internal/execution/runner.go"
click node_lsp "https://github.com/gitlawb/zero/blob/main/internal/lsp/manager.go"
click node_session_store "https://github.com/gitlawb/zero/blob/main/internal/sessions/store.go"
click node_config "https://github.com/gitlawb/zero/blob/main/internal/config/resolver.go"
click node_credentials "https://github.com/gitlawb/zero/blob/main/internal/credstore/credstore.go"
click node_oauth "https://github.com/gitlawb/zero/blob/main/internal/oauth/manager.go"
click node_mcp "https://github.com/gitlawb/zero/blob/main/internal/mcp/registry.go"
click node_specialists "https://github.com/gitlawb/zero/blob/main/internal/specialist/runtime.go"
click node_skills_plugins "https://github.com/gitlawb/zero/blob/main/internal/skills/skills.go"
click node_hooks "https://github.com/gitlawb/zero/blob/main/internal/hooks/dispatch.go"
click node_daemon "https://github.com/gitlawb/zero/blob/main/internal/daemon/server.go"

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_cli,node_tui,node_user toneBlue
class node_agent_loop,node_lsp toneAmber
class node_tool_registry,node_workspace_tools,node_sandbox,node_execution,node_model_service,node_mcp_server toneMint
class node_session_store,node_config,node_credentials,node_daemon toneRose
class node_providers,node_oauth,node_mcp,node_specialists,node_skills_plugins,node_hooks,node_workspace toneIndigo
```

## Components

### User Interaction

- [CLI Router](https://github.com/gitlawb/zero/blob/main/internal/cli/app.go): `internal/cli/app.go`
- [Terminal UI](https://github.com/gitlawb/zero/blob/main/internal/tui/run.go): `internal/tui/run.go`

### Agent Runtime

- [Agent Loop](https://github.com/gitlawb/zero/blob/main/internal/agent/loop.go): `internal/agent/loop.go`
- [Code Diagnostics](https://github.com/gitlawb/zero/blob/main/internal/lsp/manager.go): `internal/lsp/manager.go`

### Tools and Safety

- [Tool Registry](https://github.com/gitlawb/zero/blob/main/internal/tools/registry.go): `internal/tools/registry.go`
- [Workspace Tools](https://github.com/gitlawb/zero/blob/main/internal/tools/builtin_catalog.go): `internal/tools/builtin_catalog.go`
- [Sandbox Policy](https://github.com/gitlawb/zero/blob/main/internal/sandbox/engine.go): `internal/sandbox/engine.go`
- [Command Execution](https://github.com/gitlawb/zero/blob/main/internal/execution/runner.go): `internal/execution/runner.go`

### Local State

- [Session Store](https://github.com/gitlawb/zero/blob/main/internal/sessions/store.go): `internal/sessions/store.go`
- [Provider Configuration](https://github.com/gitlawb/zero/blob/main/internal/config/resolver.go): `internal/config/resolver.go`
- [Credential Store](https://github.com/gitlawb/zero/blob/main/internal/credstore/credstore.go): `internal/credstore/credstore.go`
- [Session Daemon](https://github.com/gitlawb/zero/blob/main/internal/daemon/server.go): `internal/daemon/server.go`

### Providers and Extensions

- [Model Providers](https://github.com/gitlawb/zero/blob/main/internal/providers/factory.go): `internal/providers/factory.go`
- [OAuth Login](https://github.com/gitlawb/zero/blob/main/internal/oauth/manager.go): `internal/oauth/manager.go`
- [MCP Integration](https://github.com/gitlawb/zero/blob/main/internal/mcp/registry.go): `internal/mcp/registry.go`
- [Specialist Agents](https://github.com/gitlawb/zero/blob/main/internal/specialist/runtime.go): `internal/specialist/runtime.go`
- [Skills and Plugins](https://github.com/gitlawb/zero/blob/main/internal/skills/skills.go): `internal/skills/skills.go`
- [Hooks](https://github.com/gitlawb/zero/blob/main/internal/hooks/dispatch.go): `internal/hooks/dispatch.go`

### Other components

- **Terminal User**
- **Model API**
- **Project Files**
- **MCP Servers**

## Connections

- Terminal User → CLI Router: runs commands
- CLI Router → Terminal UI: starts TUI
- CLI Router → Agent Loop: runs headless turn
- Terminal UI → Agent Loop: submits prompt
- CLI Router → Provider Configuration: loads configuration
- CLI Router → Session Store: opens sessions
- Agent Loop → Model Providers: requests completion
- Model Providers → Model API: sends model request
- Agent Loop → Tool Registry: dispatches tool calls
- Tool Registry → Workspace Tools: resolves tools
- Workspace Tools → Project Files: reads and edits
- Workspace Tools → Sandbox Policy: checks permissions
- Workspace Tools → Command Execution: runs commands
- Command Execution → Project Files: operates in workspace
- Workspace Tools → Code Diagnostics: requests diagnostics
- Agent Loop → Session Store: persists turns
- Provider Configuration → Credential Store: resolves secrets
- CLI Router → OAuth Login: manages login
- OAuth Login → Credential Store: stores tokens
- CLI Router → MCP Integration: configures servers
- MCP Integration → MCP Servers: connects tools
- Agent Loop → Specialist Agents: runs subagents
- CLI Router → Skills and Plugins: manages extensions
- CLI Router → Hooks: dispatches hooks
- CLI Router → Session Daemon: starts daemon