# intelligent-internet/zenith architecture

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

- Interactive diagram: https://gitdiagram.com/intelligent-internet/zenith
- Repository: https://github.com/intelligent-internet/zenith

## Overview

Zenith is a long-running coding-agent harness: a host orchestrator submits a mission and plan, then repeatedly advances task state, dispatching workers and validators, handling attention and replanning, and requesting terminal review before stopping. The MCP server exposes separate orchestrator, worker, and reviewer surfaces; the CLI initializes host-agent assets and project setup. The graph emphasizes the documented control loop and sampled call relationships. Some subsystems, including attention scoring and provider configuration, are indexed or documented but their runtime wiring was not fully sampled.

Main entry points: [`zenith/src/zenith_harness/controller.py`](https://github.com/intelligent-internet/zenith/blob/main/zenith/src/zenith_harness/controller.py) (Project controller), [`zenith/src/zenith_harness/server.py`](https://github.com/intelligent-internet/zenith/blob/main/zenith/src/zenith_harness/server.py) (MCP surfaces), [`zenith/src/zenith_harness/coordinator.py`](https://github.com/intelligent-internet/zenith/blob/main/zenith/src/zenith_harness/coordinator.py) (Mission coordinator), [`zenith/src/zenith_harness/storage.py`](https://github.com/intelligent-internet/zenith/blob/main/zenith/src/zenith_harness/storage.py) (Project store)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User entry"]
  node_cli["Setup CLI<br/>[cli.py]"]
  node_server["MCP surfaces<br/>[server.py]"]
end

subgraph group_control["Mission control"]
  node_controller["Project controller<br/>[controller.py]"]
  node_coordinator["Mission coordinator<br/>[coordinator.py]"]
  node_validation["Task validation<br/>[task_validation.py]"]
  node_patching["Plan patching<br/>[task_list_patch.py]"]
  node_attention["Attention analysis<br/>[attention.py]"]
  node_envelope["State envelope<br/>[envelope.py]"]
end

subgraph group_execution["Agent execution"]
  node_dispatcher["Node dispatch<br/>[dispatcher.py]"]
  node_acp["ACP runner<br/>[acp_runner.py]"]
  node_worker(("Worker agent"))
  node_validator(("Validator agent"))
  node_reviewer(("Terminal reviewer"))
end

subgraph group_state["Project state"]
  node_store[("Project store<br/>[storage.py]")]
  node_models["Runtime schemas<br/>[models.py]"]
end

subgraph group_assets["Prompts and providers"]
  node_config["Harness config<br/>[config.py]"]
  node_assetsloader["Asset loader<br/>[assets.py]"]
  node_providers["Provider adapters<br/>[providers.py]"]
  node_prompts["Bundled prompts"]
  node_skills["Bundled skills"]
end

node_user(("Host agent"))

node_user -->|"initializes"| node_cli
node_user -->|"invokes tools"| node_server
node_server -->|"routes tools"| node_controller
node_controller -->|"advances mission"| node_coordinator
node_controller -->|"reads and writes"| node_store
node_controller -->|"validates plans"| node_validation
node_controller -->|"applies patches"| node_patching
node_controller -->|"builds response"| node_envelope
node_coordinator -->|"dispatches tasks"| node_dispatcher
node_coordinator -->|"loads and saves"| node_store
node_coordinator -->|"scores gaps"| node_attention
node_coordinator -.->|"requests review"| node_reviewer
node_dispatcher -.->|"implemented by"| node_acp
node_acp -->|"runs sessions"| node_worker
node_acp -.->|"runs sessions"| node_validator
node_worker -->|"submits handoff"| node_server
node_validator -->|"submits verdict"| node_server
node_reviewer -->|"submits review"| node_server
node_server -.->|"persists handoffs"| node_store
node_store -->|"stores records"| node_models
node_cli -->|"discovers settings"| node_config
node_cli -->|"loads assets"| node_assetsloader
node_assetsloader -->|"uses paths"| node_config
node_config -->|"selects providers"| node_providers
node_assetsloader -->|"reads prompts"| node_prompts
node_assetsloader -->|"loads skills"| node_skills
node_store -->|"seeds skills"| node_skills

click node_cli "https://github.com/intelligent-internet/zenith/blob/main/zenith/src/zenith_harness/cli.py"
click node_server "https://github.com/intelligent-internet/zenith/blob/main/zenith/src/zenith_harness/server.py"
click node_controller "https://github.com/intelligent-internet/zenith/blob/main/zenith/src/zenith_harness/controller.py"
click node_coordinator "https://github.com/intelligent-internet/zenith/blob/main/zenith/src/zenith_harness/coordinator.py"
click node_validation "https://github.com/intelligent-internet/zenith/blob/main/zenith/src/zenith_harness/task_validation.py"
click node_patching "https://github.com/intelligent-internet/zenith/blob/main/zenith/src/zenith_harness/task_list_patch.py"
click node_attention "https://github.com/intelligent-internet/zenith/blob/main/zenith/src/zenith_harness/attention.py"
click node_envelope "https://github.com/intelligent-internet/zenith/blob/main/zenith/src/zenith_harness/envelope.py"
click node_dispatcher "https://github.com/intelligent-internet/zenith/blob/main/zenith/src/zenith_harness/dispatcher.py"
click node_acp "https://github.com/intelligent-internet/zenith/blob/main/zenith/src/zenith_harness/acp_runner.py"
click node_store "https://github.com/intelligent-internet/zenith/blob/main/zenith/src/zenith_harness/storage.py"
click node_models "https://github.com/intelligent-internet/zenith/blob/main/zenith/src/zenith_harness/models.py"
click node_config "https://github.com/intelligent-internet/zenith/blob/main/zenith/src/zenith_harness/config.py"
click node_assetsloader "https://github.com/intelligent-internet/zenith/blob/main/zenith/src/zenith_harness/assets.py"
click node_providers "https://github.com/intelligent-internet/zenith/blob/main/zenith/src/zenith_harness/providers.py"
click node_prompts "https://github.com/intelligent-internet/zenith/tree/main/zenith/src/zenith_harness/bundled/prompts"
click node_skills "https://github.com/intelligent-internet/zenith/tree/main/zenith/src/zenith_harness/bundled/skills"

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_server toneBlue
class node_controller,node_coordinator,node_validation,node_patching,node_attention,node_envelope toneAmber
class node_dispatcher,node_acp,node_worker,node_validator,node_reviewer toneMint
class node_store,node_models toneRose
class node_config,node_assetsloader,node_providers,node_prompts,node_skills,node_user toneIndigo
```

## Components

### User entry

- [Setup CLI](https://github.com/intelligent-internet/zenith/blob/main/zenith/src/zenith_harness/cli.py): `zenith/src/zenith_harness/cli.py`
- [MCP surfaces](https://github.com/intelligent-internet/zenith/blob/main/zenith/src/zenith_harness/server.py): `zenith/src/zenith_harness/server.py`

### Mission control

- [Project controller](https://github.com/intelligent-internet/zenith/blob/main/zenith/src/zenith_harness/controller.py): `zenith/src/zenith_harness/controller.py`
- [Mission coordinator](https://github.com/intelligent-internet/zenith/blob/main/zenith/src/zenith_harness/coordinator.py): `zenith/src/zenith_harness/coordinator.py`
- [Task validation](https://github.com/intelligent-internet/zenith/blob/main/zenith/src/zenith_harness/task_validation.py): `zenith/src/zenith_harness/task_validation.py`
- [Plan patching](https://github.com/intelligent-internet/zenith/blob/main/zenith/src/zenith_harness/task_list_patch.py): `zenith/src/zenith_harness/task_list_patch.py`
- [Attention analysis](https://github.com/intelligent-internet/zenith/blob/main/zenith/src/zenith_harness/attention.py): `zenith/src/zenith_harness/attention.py`
- [State envelope](https://github.com/intelligent-internet/zenith/blob/main/zenith/src/zenith_harness/envelope.py): `zenith/src/zenith_harness/envelope.py`

### Agent execution

- [Node dispatch](https://github.com/intelligent-internet/zenith/blob/main/zenith/src/zenith_harness/dispatcher.py): `zenith/src/zenith_harness/dispatcher.py`
- [ACP runner](https://github.com/intelligent-internet/zenith/blob/main/zenith/src/zenith_harness/acp_runner.py): `zenith/src/zenith_harness/acp_runner.py`
- **Worker agent**
- **Validator agent**
- **Terminal reviewer**

### Project state

- [Project store](https://github.com/intelligent-internet/zenith/blob/main/zenith/src/zenith_harness/storage.py): `zenith/src/zenith_harness/storage.py`
- [Runtime schemas](https://github.com/intelligent-internet/zenith/blob/main/zenith/src/zenith_harness/models.py): `zenith/src/zenith_harness/models.py`

### Prompts and providers

- [Harness config](https://github.com/intelligent-internet/zenith/blob/main/zenith/src/zenith_harness/config.py): `zenith/src/zenith_harness/config.py`
- [Asset loader](https://github.com/intelligent-internet/zenith/blob/main/zenith/src/zenith_harness/assets.py): `zenith/src/zenith_harness/assets.py`
- [Provider adapters](https://github.com/intelligent-internet/zenith/blob/main/zenith/src/zenith_harness/providers.py): `zenith/src/zenith_harness/providers.py`
- [Bundled prompts](https://github.com/intelligent-internet/zenith/tree/main/zenith/src/zenith_harness/bundled/prompts): `zenith/src/zenith_harness/bundled/prompts`
- [Bundled skills](https://github.com/intelligent-internet/zenith/tree/main/zenith/src/zenith_harness/bundled/skills): `zenith/src/zenith_harness/bundled/skills`

### Other components

- **Host agent**

## Connections

- Host agent → Setup CLI: initializes (evidence: `README.md`)
- Host agent → MCP surfaces: invokes tools (evidence: `README.md`)
- MCP surfaces → Project controller: routes tools (evidence: `zenith/src/zenith_harness/server.py`)
- Project controller → Mission coordinator: advances mission (evidence: `zenith/src/zenith_harness/controller.py`)
- Project controller → Project store: reads and writes (evidence: `zenith/src/zenith_harness/controller.py`)
- Project controller → Task validation: validates plans (evidence: `zenith/src/zenith_harness/controller.py`)
- Project controller → Plan patching: applies patches (evidence: `zenith/src/zenith_harness/controller.py`)
- Project controller → State envelope: builds response (evidence: `zenith/src/zenith_harness/controller.py`)
- Mission coordinator → Node dispatch: dispatches tasks (evidence: `zenith/src/zenith_harness/coordinator.py`)
- Mission coordinator → Project store: loads and saves (evidence: `zenith/src/zenith_harness/coordinator.py`)
- Mission coordinator → Attention analysis: scores gaps (evidence: `zenith/src/zenith_harness/coordinator.py`)
- Mission coordinator → Terminal reviewer: requests review
- Node dispatch → ACP runner: implemented by (evidence: `zenith/src/zenith_harness/acp_runner.py`)
- ACP runner → Worker agent: runs sessions (evidence: `zenith/src/zenith_harness/acp_runner.py`)
- ACP runner → Validator agent: runs sessions
- Worker agent → MCP surfaces: submits handoff (evidence: `zenith/src/zenith_harness/server.py`)
- Validator agent → MCP surfaces: submits verdict (evidence: `zenith/src/zenith_harness/server.py`)
- Terminal reviewer → MCP surfaces: submits review (evidence: `zenith/src/zenith_harness/server.py`)
- MCP surfaces → Project store: persists handoffs (evidence: `zenith/src/zenith_harness/server.py`)
- Project store → Runtime schemas: stores records (evidence: `zenith/src/zenith_harness/storage.py`)
- Setup CLI → Harness config: discovers settings (evidence: `zenith/src/zenith_harness/cli.py`)
- Setup CLI → Asset loader: loads assets (evidence: `zenith/src/zenith_harness/cli.py`)
- Asset loader → Harness config: uses paths (evidence: `zenith/src/zenith_harness/assets.py`)
- Harness config → Provider adapters: selects providers (evidence: `zenith/src/zenith_harness/config.py`)
- Asset loader → Bundled prompts: reads prompts (evidence: `zenith/src/zenith_harness/assets.py`)
- Asset loader → Bundled skills: loads skills (evidence: `zenith/src/zenith_harness/assets.py`)
- Project store → Bundled skills: seeds skills (evidence: `zenith/src/zenith_harness/storage.py`)
