# hkuds/clawteam architecture

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

- Interactive diagram: https://gitdiagram.com/hkuds/clawteam
- Repository: https://github.com/hkuds/clawteam

## Overview

1. **Overall shape**
   - ClawTeam is a **local-first multi-agent orchestration system** built in Python 3.10+.
   - The core idea is: a human or leader agent issues CLI commands, the tool spawns worker agents, and all coordination state is persisted on the local filesystem rather than in a database or central server.

2. **Primary entrypoints**
   - The repo exposes a **Typer-based CLI** under `clawteam/__main__.py` and `clawteam/cli/commands.py`.
   - There is also an **MCP server** in `clawteam/mcp/server.py` for external model clients, and a **board server** in `clawteam/board/server.py` for monitoring.
   - These are separate front doors into the same underlying team/state machinery.

3. **Persistence boundary**
   - Persistent state lives under `~/.clawteam` by default, configured in `clawteam/config.py` and path helpers in `clawteam/paths.py`.
   - The state layer is file-backed (`clawteam/store/file.py`) with atomic write behavior, so the system does not rely on Redis, Postgres, or any other service.
   - Core persisted concepts include teams, tasks, inbox messages, workspaces, plans, snapshots, and cost/state records.

4. **Team coordination domain**
   - The `clawteam/team` package is the main coordination domain: team lifecycle, task tracking, routing, inbox/mailbox behavior, waiting, watcher logic, snapshots, costs, and plan handling.
   - This layer defines the rules for who belongs to a team, how tasks move through states, how dependencies unblock work, and how messages are delivered between agents.

5. **Agent spawning and runtime execution**
   - The `clawteam/spawn` package is responsible for starting agent processes in a chosen backend.
   - Backends include **tmux**, **plain subprocess**, and a **Windows shell/RPC path** (`wsh_backend.py`, `wsh_rpc.py`), with `tmux` as the common interactive default.
   - Spawn also handles command validation, CLI environment setup, session tracking, profiles/presets, and injecting the coordination prompt that teaches agents how to use `oh task`, `oh inbox`, and lifecycle commands.

6. **Workspace isolation**
   - Each agent can receive its own **git worktree** through `clawteam/workspace`.
   - The workspace manager and Git helpers isolate parallel agent edits, detect conflicts, and support checkpoint/merge/cleanup flows.
   - This is a key architectural boundary: agent work is separated at the filesystem and branch level, not via containers.

7. **Messaging and transport**
   - Inter-agent communication is abstracted by `clawteam/transport`.
   - The default transport is **file-based inbox exchange**, which works on a shared filesystem.
   - An optional **ZeroMQ P2P transport** exists for lower-latency or distributed use, with fallback behavior back to files.

8. **Monitoring and operator visibility**
   - The `clawteam/board` package turns live team state into operator views.
   - It includes a collector, renderer, terminal-friendly board output, a `gource`-style visualization helper, and a small static web UI served by the board server.
   - This is the read-only observability surface; it consumes team/task/inbox state rather than owning it.

9. **Higher-level orchestration**
   - The `clawteam/harness` package is the structured workflow engine: conductors, orchestrators, phases, roles, contracts, strategies, prompt builders, recovery logic, and artifact/exit journaling.
   - The `templates/` TOML files define reusable team archetypes and launchable workflows such as research, software dev, or hedge-fund-style teams.
   - This layer sits above basic task routing and encodes repeatable multi-agent procedures.

10. **Extensibility and integration boundaries**
   - `clawteam/plugins` provides a plugin manager and plugin base for custom behaviors.
   - `clawteam/mcp/tools/*` exposes selected team, task, workspace, board, plan, cost, and mailbox actions as model-callable tools.
   - Together these make ClawTeam extensible without changing the core local state model.

11. **Supporting structure**
   - Utilities such as `identity.py`, `fileutil.py`, `timefmt.py`, and `events/*` support naming, timestamps, safe file handling, and internal event propagation.
   - The `docs/`, `website/`, and `skills/` directories are packaging and user-experience layers: documentation, generated site assets, and agent skills, not core runtime subsystems.

12. **End-to-end data flow**
   - A leader or external client invokes the CLI/MCP entrypoint.
   - The core team/task layer updates file-backed state.
   - Spawn launches workers with isolated workspaces and injected coordination instructions.
   - Workers communicate through inbox/transport, update task state, and report lifecycle events.
   - Board and other observers read the same persisted state to show progress.

Main entry points: [`clawteam/team/manager.py`](https://github.com/hkuds/clawteam/blob/main/clawteam/team/manager.py) (Team manager), [`clawteam/spawn/base.py`](https://github.com/hkuds/clawteam/blob/main/clawteam/spawn/base.py) (Spawn), [`clawteam/harness/orchestrator.py`](https://github.com/hkuds/clawteam/blob/main/clawteam/harness/orchestrator.py) (Harness), [`clawteam/workspace/manager.py`](https://github.com/hkuds/clawteam/blob/main/clawteam/workspace/manager.py) (Workspace)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entrypoints"]
  node_cli["CLI<br/>typer entrypoint<br/>[__main__.py]"]
  node_mcp_server["MCP server<br/>model server<br/>[server.py]"]
  node_board_server["Board server<br/>monitor server<br/>[server.py]"]
end

subgraph group_core["Core runtime"]
  node_config_paths["Config & paths<br/>settings<br/>[config.py]"]
  node_store[("File store<br/>atomic persistence<br/>[file.py]")]
  node_team_manager["Team manager<br/>coordination core<br/>[manager.py]"]
  node_tasks["Tasks<br/>task state<br/>[tasks.py]"]
  node_mailbox["Mailbox<br/>inbox state<br/>[mailbox.py]"]
  node_router["Router<br/>routing logic<br/>[router.py]"]
  node_plan["Plans<br/>planning state<br/>[plan.py]"]
  node_snapshot["Snapshots<br/>state capture<br/>[snapshot.py]"]
  node_costs["Costs<br/>accounting<br/>[costs.py]"]
  node_events(("Events<br/>event bus<br/>[bus.py]"))
end

subgraph group_execution["Execution"]
  node_spawn["Spawn<br/>agent launcher<br/>[base.py]"]
  node_workspace["Workspace<br/>git worktree<br/>[manager.py]"]
  node_transport["Transport<br/>[base.py]"]
  node_harness["Harness<br/>workflow engine<br/>[orchestrator.py]"]
end

subgraph group_observability["Observability"]
  node_board["Board<br/>observer UI<br/>[renderer.py]"]
end

subgraph group_extensibility["Extensibility"]
  node_plugins["Plugins<br/>extension system<br/>[manager.py]"]
  node_mcp_tools["MCP tools<br/>tool surface<br/>[__init__.py]"]
end

node_cli -->|"manage"| node_team_manager
node_cli -->|"launch"| node_spawn
node_cli -->|"prepare"| node_workspace
node_mcp_server -->|"expose"| node_mcp_tools
node_mcp_tools -->|"act on"| node_team_manager
node_mcp_tools -->|"operate on"| node_workspace
node_board_server -->|"serve"| node_board
node_board -->|"read"| node_team_manager
node_team_manager -->|"tracks"| node_tasks
node_team_manager -->|"routes"| node_mailbox
node_team_manager -->|"dispatches"| node_router
node_team_manager -->|"plans"| node_plan
node_team_manager -->|"captures"| node_snapshot
node_team_manager -->|"records"| node_costs
node_team_manager -->|"emits"| node_events
node_store -->|"persists"| node_team_manager
node_config_paths -->|"locates"| node_store
node_spawn -->|"uses"| node_workspace
node_spawn -->|"communicates"| node_transport
node_spawn -->|"reports"| node_events
node_workspace -->|"supports"| node_team_manager
node_transport -->|"delivers"| node_mailbox
node_harness -->|"orchestrates"| node_spawn
node_harness -->|"directs"| node_team_manager
node_harness -->|"observes"| node_events
node_plugins -->|"extends"| node_harness
node_plugins -->|"extends"| node_spawn
node_plugins -->|"extends"| node_team_manager

click node_cli "https://github.com/hkuds/clawteam/blob/main/clawteam/__main__.py"
click node_mcp_server "https://github.com/hkuds/clawteam/blob/main/clawteam/mcp/server.py"
click node_board_server "https://github.com/hkuds/clawteam/blob/main/clawteam/board/server.py"
click node_config_paths "https://github.com/hkuds/clawteam/blob/main/clawteam/config.py"
click node_store "https://github.com/hkuds/clawteam/blob/main/clawteam/store/file.py"
click node_team_manager "https://github.com/hkuds/clawteam/blob/main/clawteam/team/manager.py"
click node_tasks "https://github.com/hkuds/clawteam/blob/main/clawteam/team/tasks.py"
click node_mailbox "https://github.com/hkuds/clawteam/blob/main/clawteam/team/mailbox.py"
click node_router "https://github.com/hkuds/clawteam/blob/main/clawteam/team/router.py"
click node_plan "https://github.com/hkuds/clawteam/blob/main/clawteam/team/plan.py"
click node_snapshot "https://github.com/hkuds/clawteam/blob/main/clawteam/team/snapshot.py"
click node_costs "https://github.com/hkuds/clawteam/blob/main/clawteam/team/costs.py"
click node_events "https://github.com/hkuds/clawteam/blob/main/clawteam/events/bus.py"
click node_spawn "https://github.com/hkuds/clawteam/blob/main/clawteam/spawn/base.py"
click node_workspace "https://github.com/hkuds/clawteam/blob/main/clawteam/workspace/manager.py"
click node_transport "https://github.com/hkuds/clawteam/blob/main/clawteam/transport/base.py"
click node_harness "https://github.com/hkuds/clawteam/blob/main/clawteam/harness/orchestrator.py"
click node_board "https://github.com/hkuds/clawteam/blob/main/clawteam/board/renderer.py"
click node_plugins "https://github.com/hkuds/clawteam/blob/main/clawteam/plugins/manager.py"
click node_mcp_tools "https://github.com/hkuds/clawteam/blob/main/clawteam/mcp/tools/__init__.py"

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_mcp_server,node_board_server toneBlue
class node_config_paths,node_store,node_team_manager,node_tasks,node_mailbox,node_router,node_plan,node_snapshot,node_costs,node_events toneAmber
class node_spawn,node_workspace,node_transport,node_harness toneMint
class node_board toneRose
class node_plugins,node_mcp_tools toneIndigo
```

## Components

### Entrypoints

Command and service front doors into the shared coordination state.

- [CLI](https://github.com/hkuds/clawteam/blob/main/clawteam/__main__.py): typer entrypoint · Human-facing command entrypoint for local team control. · `clawteam/__main__.py`
- [MCP server](https://github.com/hkuds/clawteam/blob/main/clawteam/mcp/server.py): model server · External model-client front door for tools and shared actions. · `clawteam/mcp/server.py`
- [Board server](https://github.com/hkuds/clawteam/blob/main/clawteam/board/server.py): monitor server · Serves live operator visibility over the current team state. · `clawteam/board/server.py`

### Core runtime

Persistence, team coordination, messaging, and shared support code.

- [Config & paths](https://github.com/hkuds/clawteam/blob/main/clawteam/config.py): settings · Resolves local-first configuration and filesystem locations. · `clawteam/config.py`
- [File store](https://github.com/hkuds/clawteam/blob/main/clawteam/store/file.py): atomic persistence · Filesystem-backed state store with atomic writes and no external database. · `clawteam/store/file.py`
- [Team manager](https://github.com/hkuds/clawteam/blob/main/clawteam/team/manager.py): coordination core · Owns team lifecycle and shared coordination state. · `clawteam/team/manager.py`
- [Tasks](https://github.com/hkuds/clawteam/blob/main/clawteam/team/tasks.py): task state · Tracks task definitions, status, and dependencies. · `clawteam/team/tasks.py`
- [Mailbox](https://github.com/hkuds/clawteam/blob/main/clawteam/team/mailbox.py): inbox state · Handles agent message delivery and inbox behavior. · `clawteam/team/mailbox.py`
- [Router](https://github.com/hkuds/clawteam/blob/main/clawteam/team/router.py): routing logic · Chooses how work and messages flow between team members. · `clawteam/team/router.py`
- [Plans](https://github.com/hkuds/clawteam/blob/main/clawteam/team/plan.py): planning state · Stores and evolves team plans and execution structure. · `clawteam/team/plan.py`
- [Snapshots](https://github.com/hkuds/clawteam/blob/main/clawteam/team/snapshot.py): state capture · Captures point-in-time team state for recovery and history. · `clawteam/team/snapshot.py`
- [Costs](https://github.com/hkuds/clawteam/blob/main/clawteam/team/costs.py): accounting · Tracks usage and cost records for team activity. · `clawteam/team/costs.py`
- [Events](https://github.com/hkuds/clawteam/blob/main/clawteam/events/bus.py): event bus · Internal event propagation and hooks across the runtime. · `clawteam/events/bus.py`

### Execution

Agent spawning, workspaces, and workflow orchestration.

- [Spawn](https://github.com/hkuds/clawteam/blob/main/clawteam/spawn/base.py): agent launcher · Starts worker agents in a selected backend and session model. · `clawteam/spawn/base.py`
- [Workspace](https://github.com/hkuds/clawteam/blob/main/clawteam/workspace/manager.py): git worktree · Isolates agent edits in per-agent workspaces and manages conflicts. · `clawteam/workspace/manager.py`
- [Transport](https://github.com/hkuds/clawteam/blob/main/clawteam/transport/base.py): message transport · Moves inter-agent messages through file inboxes or optional P2P. · `clawteam/transport/base.py`
- [Harness](https://github.com/hkuds/clawteam/blob/main/clawteam/harness/orchestrator.py): workflow engine · Defines structured multi-agent workflows, roles, phases, and recovery. · `clawteam/harness/orchestrator.py`

### Observability

Read-only operator views over persisted team state.

- [Board](https://github.com/hkuds/clawteam/blob/main/clawteam/board/renderer.py): observer UI · Collects and renders live team state for operators. · `clawteam/board/renderer.py`

### Extensibility

Plugin and model-tool integration boundaries.

- [Plugins](https://github.com/hkuds/clawteam/blob/main/clawteam/plugins/manager.py): extension system · Loads custom behaviors without changing core state mechanics. · `clawteam/plugins/manager.py`
- [MCP tools](https://github.com/hkuds/clawteam/blob/main/clawteam/mcp/tools/__init__.py): tool surface · Exposes team, task, workspace, board, plan, cost, and mailbox actions as tools. · `clawteam/mcp/tools/__init__.py`

## Connections

- CLI → Team manager: manage · CLI commands create, update, and inspect team state.
- CLI → Spawn: launch · CLI can start worker agents through the spawn layer.
- CLI → Workspace: prepare · CLI workflows may provision isolated workspaces.
- MCP server → MCP tools: expose · Server presents selected model-callable operations.
- MCP tools → Team manager: act on · Tools read and mutate the shared coordination domain.
- MCP tools → Workspace: operate on · Workspace actions are available through the tool surface.
- Board server → Board: serve · Board server delivers rendered monitoring views.
- Board → Team manager: read · Board consumes persisted team state rather than owning it.
- Team manager → Tasks: tracks · Task lifecycle and dependency state are maintained here.
- Team manager → Mailbox: routes · Team coordination includes inbox and message delivery behavior.
- Team manager → Router: dispatches · Routing policy determines how work moves between agents.
- Team manager → Plans: plans · Team plans shape execution and coordination.
- Team manager → Snapshots: captures · Snapshots persist team state for recovery and history.
- Team manager → Costs: records · Cost accounting is attached to team activity.
- Team manager → Events: emits · State changes propagate through the internal event bus.
- File store → Team manager: persists · File-backed storage is the persistence boundary for team state.
- Config & paths → File store: locates · Configuration and path helpers define where state lives.
- Spawn → Workspace: uses · Spawned agents are paired with isolated workspaces.
- Spawn → Transport: communicates · Workers communicate via the selected transport mechanism.
- Spawn → Events: reports · Launch and lifecycle activity is surfaced through events.
- Workspace → Team manager: supports · Workspace state supports coordinated task execution.
- Transport → Mailbox: delivers · The transport layer carries inbox-style messages.
- Harness → Spawn: orchestrates · Workflow engine coordinates agent startup and execution.
- Harness → Team manager: directs · Structured workflows drive task and plan progression.
- Harness → Events: observes · Harness logic consumes lifecycle and recovery signals.
- Plugins → Harness: extends · Plugins customize orchestration behavior.
- Plugins → Spawn: extends · Plugins can alter spawn-time behavior and prompts.
- Plugins → Team manager: extends · Plugins can hook into core coordination behavior.
