# hmbown/codewhale architecture

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

- Interactive diagram: https://gitdiagram.com/hmbown/codewhale
- Repository: https://github.com/hmbown/codewhale

## Overview

1. This is a Rust monorepo centered on an agent harness, not a single app. The primary runtime is split between a terminal UI (`crates/tui`) and a CLI/headless entrypoint (`crates/cli`), with shared logic factored into many Rust crates under `crates/*`.

2. The main execution path starts in the TUI/CLI entrypoints, then flows into the core agent engine in `crates/tui/src/core`. That engine owns turn management, dispatch, streaming, approvals, tool execution, and loop control. It is the orchestration layer that coordinates everything else.

3. User interaction is UI-driven in `crates/tui/src/tui`: command palette, session picker, model/provider picker, transcript rendering, status/footer, onboarding, and input handling. The TUI does not implement agent logic itself; it renders state from the core engine and sends user intents back into the turn loop.

4. The agent loop builds each turn from session state, project context, memory, skills, prompts, and model/provider configuration. Relevant subsystems here are `project_context`, `memory`, `skills`, `prompts`, `model_catalog`, `model_routing`, `provider_adapter`, and `session_manager`. This is where the harness decides what the model sees and which route/model is used.

5. Provider access is abstracted behind client/adapters in `crates/tui/src/client`, `llm_client`, `oauth`, `tls`, and model/provider registry modules. The README makes clear that the system supports many providers plus local runtimes like Ollama, vLLM, and SGLang, and that Anthropic/OpenAI are handled through native adapters rather than a generic shim.

6. Tool use is a first-class subsystem. The tool registry and implementations live under `crates/tui/src/tools`, covering file access, shell, git, web/search, MCP, subagents, patch/apply, review, tasking, and specialized utilities. Tool calls are parsed by the core engine, routed to the right executor, and their outputs are fed back into the same turn.

7. Safety is enforced as runtime policy, not prompt text. Tool execution goes through approval gates, exec-policy checks, and OS sandbox backends under `crates/tui/src/sandbox` and `crates/execpolicy`. The repository explicitly supports multiple sandbox mechanisms such as bwrap, Landlock, Seatbelt, seccomp, and Windows-specific handling.

8. Persistence and rollback are built into session handling. The system includes session/state crates, side-snapshot logic, composer/history/stash support, and `/restore` behavior that can roll back prior turns without touching the user’s main git history. The architecture therefore keeps “session memory” separate from the project repository.

9. There is a separate agent-runtime surface for embedding and remote use. `crates/app-server` exposes an HTTP/chat-completions style server, while the TUI also contains runtime and ACP/MCP-related modules. The README and docs indicate this is intended for GUI/editor integrations, mobile, and service-style usage, not just terminal interaction.

10. Multi-agent and multi-worker orchestration is another boundary. `crates/tui/src/fleet` handles scheduling, workers, ledgers, task specs, and host/runtime coordination, while `subagent` tooling supports concurrent helper agents inside a session. This is the layer for parallel investigation/implementation rather than single-threaded turns.

11. Configuration, secrets, and trust are handled as dedicated subsystems rather than ad hoc env reads. `crates/config`, `crates/secrets`, `crates/state`, and `crates/hooks` manage provider keys, persisted settings, repo-local constitution/hooks, and durable state. The README also notes compatibility with older config paths and repo-level policy files.

12. The repo includes several integration surfaces outside the Rust harness. `integrations/*` contains Node-based bridges for Feishu, Telegram, and Weixin; `extensions/vscode` provides a VS Code extension; `web/` is a Next.js/Tailwind site with admin/feed/API routes; and `npm/*` packages wrap the Rust binaries for distribution. These are front-ends and connectors, not the core agent engine.

13. Release, deployment, and distribution are first-class parts of the architecture. There are Docker, Nix, Homebrew, Cargo, npm, GitHub Actions, Tencent Lighthouse deployment assets, and release scripts. That means the repo ships the same core harness through multiple packaging and hosting channels, but the central runtime remains the Rust workspace.

14. For an architecture diagram, the clearest high-level flow is: user/UI or remote API → session/core engine → prompt/context assembly → provider client → streamed model response → tool/approval/sandbox execution → updated session state and transcript → optional rollback/persistence. Everything else in the repo supports one of those stages or provides an alternate entry surface into them.

Main entry points: [`crates/tui/src/core/engine.rs`](https://github.com/hmbown/codewhale/blob/main/crates/tui/src/core/engine.rs) (Agent engine), [`crates/tui/src/runtime_api.rs`](https://github.com/hmbown/codewhale/blob/main/crates/tui/src/runtime_api.rs) (Runtime API), [`crates/tui/src/project_context.rs`](https://github.com/hmbown/codewhale/blob/main/crates/tui/src/project_context.rs) (Context builder), [`crates/tui/src/tools/mod.rs`](https://github.com/hmbown/codewhale/blob/main/crates/tui/src/tools/mod.rs) (Tools)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_rust_runtime["Rust runtime"]
  node_agent_engine{{"Agent engine<br/>orchestrator<br/>[engine.rs]"}}
  node_session_core[("Session core<br/>turn state<br/>[session.rs]")]
  node_context_builder["Context builder<br/>assembly<br/>[project_context.rs]"]
  node_prompting["Prompts<br/>prompt assembly<br/>[prompts.rs]"]
  node_routing{{"Model routing<br/>model policy<br/>[model_routing.rs]"}}
  node_provider_adapter["Provider adapter<br/>provider abstraction"]
  node_llm_clients["LLM clients<br/>provider client<br/>[client.rs]"]
  node_tools{{"Tools<br/>tool registry<br/>[mod.rs]"}}
  node_fleet{{"Fleet<br/>multi-worker orchestration<br/>[mod.rs]"}}
  node_runtime_server["Runtime API<br/>embedding surface<br/>[runtime_api.rs]"]
end

subgraph group_safety_state["Safety & state"]
  node_safety_policy["Exec policy<br/>safety policy<br/>[mod.rs]"]
  node_sandbox["Sandbox<br/>[mod.rs]"]
  node_state_store[("State<br/>persistence<br/>[lib.rs]")]
  node_session_mgr[("Session manager<br/>session lifecycle<br/>[session_manager.rs]")]
  node_config_secrets["Config & secrets<br/>settings<br/>[lib.rs]"]
end

subgraph group_surfaces["Entry surfaces"]
  node_cli_entry["CLI<br/>entrypoint<br/>[main.rs]"]
  node_tui_entry["TUI<br/>entrypoint<br/>[main.rs]"]
  node_app_server["App server<br/>http server<br/>[lib.rs]"]
  node_tui_ui["TUI UI<br/>ui shell<br/>[app.rs]"]
end

subgraph group_integrations["Integrations & delivery"]
  node_vscode_ext["VS Code<br/>editor extension<br/>[extension.ts]"]
  node_node_bridges["Chat bridges<br/>node integration<br/>[index.mjs]"]
  node_web_site["Web site<br/>next.js site<br/>[page.tsx]"]
  node_npm_wrapper["npm wrapper<br/>distribution<br/>[codewhale.js]"]
end

node_cli_entry -->|"start"| node_agent_engine
node_tui_entry -->|"launches"| node_tui_ui
node_tui_ui -->|"drives"| node_agent_engine
node_app_server -->|"exposes"| node_runtime_server
node_runtime_server -->|"dispatches"| node_agent_engine
node_agent_engine -->|"uses"| node_session_core
node_agent_engine -->|"assembles"| node_context_builder
node_context_builder -->|"fills"| node_prompting
node_context_builder -->|"selects"| node_routing
node_routing -->|"chooses"| node_provider_adapter
node_provider_adapter -->|"calls"| node_llm_clients
node_agent_engine -->|"invokes"| node_tools
node_tools -->|"checks"| node_safety_policy
node_tools -->|"runs in"| node_sandbox
node_agent_engine -->|"persists"| node_session_mgr
node_session_mgr -->|"stores"| node_state_store
node_session_mgr -->|"reads"| node_config_secrets
node_agent_engine -->|"coordinates"| node_fleet
node_tui_ui -->|"manages"| node_fleet
node_agent_engine -->|"configures"| node_config_secrets
node_vscode_ext -->|"connects"| node_runtime_server
node_node_bridges -->|"bridges"| node_runtime_server
node_web_site -.->|"documents"| node_runtime_server
node_npm_wrapper -->|"wraps"| node_cli_entry

click node_cli_entry "https://github.com/hmbown/codewhale/blob/main/crates/cli/src/main.rs"
click node_tui_entry "https://github.com/hmbown/codewhale/blob/main/crates/tui/src/main.rs"
click node_app_server "https://github.com/hmbown/codewhale/blob/main/crates/app-server/src/lib.rs"
click node_tui_ui "https://github.com/hmbown/codewhale/blob/main/crates/tui/src/tui/app.rs"
click node_agent_engine "https://github.com/hmbown/codewhale/blob/main/crates/tui/src/core/engine.rs"
click node_session_core "https://github.com/hmbown/codewhale/blob/main/crates/tui/src/core/session.rs"
click node_context_builder "https://github.com/hmbown/codewhale/blob/main/crates/tui/src/project_context.rs"
click node_prompting "https://github.com/hmbown/codewhale/blob/main/crates/tui/src/prompts.rs"
click node_routing "https://github.com/hmbown/codewhale/blob/main/crates/tui/src/model_routing.rs"
click node_provider_adapter "https://github.com/hmbown/codewhale/blob/main/crates/tui/src/provider_adapter.rs"
click node_llm_clients "https://github.com/hmbown/codewhale/blob/main/crates/tui/src/client.rs"
click node_tools "https://github.com/hmbown/codewhale/blob/main/crates/tui/src/tools/mod.rs"
click node_safety_policy "https://github.com/hmbown/codewhale/blob/main/crates/tui/src/execpolicy/mod.rs"
click node_sandbox "https://github.com/hmbown/codewhale/blob/main/crates/tui/src/sandbox/mod.rs"
click node_state_store "https://github.com/hmbown/codewhale/blob/main/crates/state/src/lib.rs"
click node_session_mgr "https://github.com/hmbown/codewhale/blob/main/crates/tui/src/session_manager.rs"
click node_config_secrets "https://github.com/hmbown/codewhale/blob/main/crates/config/src/lib.rs"
click node_fleet "https://github.com/hmbown/codewhale/blob/main/crates/tui/src/fleet/mod.rs"
click node_runtime_server "https://github.com/hmbown/codewhale/blob/main/crates/tui/src/runtime_api.rs"
click node_vscode_ext "https://github.com/hmbown/codewhale/blob/main/extensions/vscode/src/extension.ts"
click node_node_bridges "https://github.com/hmbown/codewhale/blob/main/integrations/feishu-bridge/src/index.mjs"
click node_web_site "https://github.com/hmbown/codewhale/blob/main/web/app/[locale]/page.tsx"
click node_npm_wrapper "https://github.com/hmbown/codewhale/blob/main/npm/codewhale/bin/codewhale.js"

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_agent_engine,node_session_core,node_context_builder,node_prompting,node_routing,node_provider_adapter,node_llm_clients,node_tools,node_fleet,node_runtime_server toneBlue
class node_safety_policy,node_sandbox,node_state_store,node_session_mgr,node_config_secrets toneAmber
class node_cli_entry,node_tui_entry,node_app_server,node_tui_ui toneMint
class node_vscode_ext,node_node_bridges,node_web_site,node_npm_wrapper toneRose
```

## Components

### Rust runtime

Primary agent harness and shared workspace crates.

- [Agent engine](https://github.com/hmbown/codewhale/blob/main/crates/tui/src/core/engine.rs): orchestrator · Turn loop, dispatch, streaming, approvals, and tool coordination. · `crates/tui/src/core/engine.rs`
- [Session core](https://github.com/hmbown/codewhale/blob/main/crates/tui/src/core/session.rs): turn state · Session lifecycle and per-turn state carried through the harness. · `crates/tui/src/core/session.rs`
- [Context builder](https://github.com/hmbown/codewhale/blob/main/crates/tui/src/project_context.rs): assembly · Builds what the model sees from project context, memory, prompts, and skills. · `crates/tui/src/project_context.rs`
- [Prompts](https://github.com/hmbown/codewhale/blob/main/crates/tui/src/prompts.rs): prompt assembly · Prompt templates, modes, approvals, and memory guidance. · `crates/tui/src/prompts.rs`
- [Model routing](https://github.com/hmbown/codewhale/blob/main/crates/tui/src/model_routing.rs): model policy · Chooses model/provider routes and provider readiness. · `crates/tui/src/model_routing.rs`
- [Provider adapter](https://github.com/hmbown/codewhale/blob/main/crates/tui/src/provider_adapter.rs): provider abstraction · Normalizes access to provider clients and local runtimes. · `crates/tui/src/provider_adapter.rs`
- [LLM clients](https://github.com/hmbown/codewhale/blob/main/crates/tui/src/client.rs): provider client · Native provider clients, auth, TLS, and request/response handling. · `crates/tui/src/client.rs`
- [Tools](https://github.com/hmbown/codewhale/blob/main/crates/tui/src/tools/mod.rs): tool registry · File, shell, git, web, MCP, subagent, patch, review, and task tools. · `crates/tui/src/tools/mod.rs`
- [Fleet](https://github.com/hmbown/codewhale/blob/main/crates/tui/src/fleet/mod.rs): multi-worker orchestration · Worker scheduling, ledgers, hosts, and task execution across sessions. · `crates/tui/src/fleet/mod.rs`
- [Runtime API](https://github.com/hmbown/codewhale/blob/main/crates/tui/src/runtime_api.rs): embedding surface · Runtime-facing API and ACP/MCP-related surface for embedding and remote use. · `crates/tui/src/runtime_api.rs`

### Safety & state

Policy, persistence, configuration, and secrets management.

- [Exec policy](https://github.com/hmbown/codewhale/blob/main/crates/tui/src/execpolicy/mod.rs): safety policy · Approval gates and policy decisions for tool execution. · `crates/tui/src/execpolicy/mod.rs`
- [Sandbox](https://github.com/hmbown/codewhale/blob/main/crates/tui/src/sandbox/mod.rs): runtime sandbox · OS sandbox backends and process hardening for tool runs. · `crates/tui/src/sandbox/mod.rs`
- [State](https://github.com/hmbown/codewhale/blob/main/crates/state/src/lib.rs): persistence · Durable state, snapshots, and rollback-oriented session persistence. · `crates/state/src/lib.rs`
- [Session manager](https://github.com/hmbown/codewhale/blob/main/crates/tui/src/session_manager.rs): session lifecycle · Creates, loads, restores, and persists sessions. · `crates/tui/src/session_manager.rs`
- [Config & secrets](https://github.com/hmbown/codewhale/blob/main/crates/config/src/lib.rs): settings · Provider config, secrets, and durable settings. · `crates/config/src/lib.rs`

### Entry surfaces

Terminal, server, and UI entrypoints into the harness.

- [CLI](https://github.com/hmbown/codewhale/blob/main/crates/cli/src/main.rs): entrypoint · Headless command-line runtime entrypoint. · `crates/cli/src/main.rs`
- [TUI](https://github.com/hmbown/codewhale/blob/main/crates/tui/src/main.rs): entrypoint · Terminal UI runtime entrypoint. · `crates/tui/src/main.rs`
- [App server](https://github.com/hmbown/codewhale/blob/main/crates/app-server/src/lib.rs): http server · HTTP/chat-completions style remote runtime surface. · `crates/app-server/src/lib.rs`
- [TUI UI](https://github.com/hmbown/codewhale/blob/main/crates/tui/src/tui/app.rs): ui shell · Command palette, transcript, pickers, and user input handling. · `crates/tui/src/tui/app.rs`

### Integrations & delivery

External bridges, web presence, and distribution wrappers.

- [VS Code](https://github.com/hmbown/codewhale/blob/main/extensions/vscode/src/extension.ts): editor extension · Editor integration that embeds or drives the runtime. · `extensions/vscode/src/extension.ts`
- [Chat bridges](https://github.com/hmbown/codewhale/blob/main/integrations/feishu-bridge/src/index.mjs): node integration · Feishu, Telegram, and Weixin connectors around the core harness. · `integrations/feishu-bridge/src/index.mjs`
- [Web site](https://github.com/hmbown/codewhale/blob/main/web/app/[locale]/page.tsx): next.js site · Documentation, feed, admin, and install-facing web front end. · `web/app/[locale]/page.tsx`
- [npm wrapper](https://github.com/hmbown/codewhale/blob/main/npm/codewhale/bin/codewhale.js): distribution · Packaged Node wrappers for shipping the Rust binaries. · `npm/codewhale/bin/codewhale.js`

## Connections

- CLI → Agent engine: start · CLI starts the shared agent engine.
- TUI → TUI UI: launches · TUI entrypoint boots the interactive UI.
- TUI UI → Agent engine: drives · UI sends user intents into the turn loop.
- App server → Runtime API: exposes · Server exposes remote runtime endpoints.
- Runtime API → Agent engine: dispatches · Remote requests enter the same orchestration layer.
- Agent engine → Session core: uses · Engine operates on per-session turn state.
- Agent engine → Context builder: assembles · Engine builds model context for each turn.
- Context builder → Prompts: fills · Context assembly pulls prompt templates and modes.
- Context builder → Model routing: selects · Context and settings influence model/provider routing.
- Model routing → Provider adapter: chooses · Routing selects an adapter path for the request.
- Provider adapter → LLM clients: calls · Adapter hands off to concrete provider clients.
- Agent engine → Tools: invokes · Tool calls are parsed and executed through the registry.
- Tools → Exec policy: checks · Tool execution is gated by policy and approvals.
- Tools → Sandbox: runs in · Tool execution is constrained by sandbox backends.
- Agent engine → Session manager: persists · Turns update session lifecycle and persistence.
- Session manager → State: stores · Session data is written to durable state.
- Session manager → Config & secrets: reads · Session setup consumes config and secrets.
- Agent engine → Fleet: coordinates · Fleet handles parallel workers and multi-agent coordination.
- TUI UI → Fleet: manages · UI surfaces fleet/worker status and controls.
- Agent engine → Config & secrets: configures · Runtime behavior depends on provider and policy settings.
- VS Code → Runtime API: connects · Editor integration talks to the runtime surface.
- Chat bridges → Runtime API: bridges · Messaging bridges forward work into the runtime.
- Web site → Runtime API: documents · Web front end presents runtime-adjacent content and controls.
- npm wrapper → CLI: wraps · npm package ships the CLI/TUI binaries.