How hkuds/clawteam works
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: team/manager.py Team manager · base.py Spawn · orchestrator.py Harness · workspace/manager.py Workspace
Components 20
Entrypoints
Command and service front doors into the shared coordination state.
- CLI · Human-facing command entrypoint for local team control.
clawteam/__main__.py - MCP server · External model-client front door for tools and shared actions.
clawteam/mcp/server.py - Board 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 · Resolves local-first configuration and filesystem locations.
clawteam/config.py - File store · Filesystem-backed state store with atomic writes and no external database.
clawteam/store/file.py - Team manager · Owns team lifecycle and shared coordination state.
clawteam/team/manager.py - Tasks · Tracks task definitions, status, and dependencies.
clawteam/team/tasks.py - Mailbox · Handles agent message delivery and inbox behavior.
clawteam/team/mailbox.py - Router · Chooses how work and messages flow between team members.
clawteam/team/router.py - Plans · Stores and evolves team plans and execution structure.
clawteam/team/plan.py - Snapshots · Captures point-in-time team state for recovery and history.
clawteam/team/snapshot.py - Costs · Tracks usage and cost records for team activity.
clawteam/team/costs.py - Events · Internal event propagation and hooks across the runtime.
clawteam/events/bus.py
Execution
Agent spawning, workspaces, and workflow orchestration.
- Spawn · Starts worker agents in a selected backend and session model.
clawteam/spawn/base.py - Workspace · Isolates agent edits in per-agent workspaces and manages conflicts.
clawteam/workspace/manager.py - Transport · Moves inter-agent messages through file inboxes or optional P2P.
clawteam/transport/base.py - Harness · Defines structured multi-agent workflows, roles, phases, and recovery.
clawteam/harness/orchestrator.py
Observability
Read-only operator views over persisted team state.
- Board · Collects and renders live team state for operators.
clawteam/board/renderer.py
Connections 28
- 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.