These docs describe Clawboo v0.3.1, the current release.
Agents and runtimes
Boo: Clawboo’s name for an agent: one participant in a team, rendered as a ghost-lobster avatar. Every Boo is backed by a real agent record from an AgentSource; there are no decorative agents. See the agent model. Boo Zero: the universal team leader, runtime-neutral and native by default. It is identified from the registry’sdefaultId (resolveBooZero: an explicit override, then the native Boo Zero, then the OpenClaw default), falling back to the first teamless agent, then the first agent overall. The same Boo Zero leads every team regardless of runtime. Boo Zero is teamless in the database but participates in every team via team-scoped sessions. See the agent model and Boo Zero briefs.
runtime: the engine that actually runs an agent. Clawboo supports five: openclaw, clawboo-native, claude-code, codex, and hermes. Each is wrapped behind one RuntimeAdapter interface so a team can mix runtimes. See runtimes overview.
the 5 runtimes: openclaw (the OpenClaw Gateway), clawboo-native (the in-process harness), claude-code, codex, and hermes. The four non-OpenClaw runtimes are declared in descriptor.ts; OpenClaw is the fifth, handled separately because it is a connected substrate rather than a CLI/SDK Clawboo spawns. See runtimes overview.
native runtime: clawboo-native, Clawboo’s own in-process conversational harness. It talks to provider SDKs directly (Anthropic, OpenAI, OpenRouter, Ollama), runs with no OpenClaw Gateway, and is builtIn (ships inside the server, nothing to install; connect by pasting a provider key). See the native runtime.
RuntimeAdapter: the single TypeScript interface every runtime implements (id, participantKind, capabilities(), health(), start(), events(), abort(), setModel(), writeContext()). Adapters wrap a black-box runtime and normalize its native signals into a RuntimeEvent stream; Clawboo supervises and relays, it does not reimplement runtime loops. See the RuntimeAdapter trait.
RuntimeEvent: the normalized 7-variant lifecycle union every adapter emits: text-delta, tool-call, tool-result, status, cost, done, and error. It is what lets one orchestrator drive heterogeneous runtimes off a single event shape. See the RuntimeAdapter trait.
AgentSource: the registry seam that answers “where does the agent list come from?” Reads are SQLite-backed (so they work even when the upstream is down); writes, file I/O, and sessions go to the upstream and mirror into SQLite. AgentSource is about who exists; RuntimeAdapter is about how agents run; the two must not entangle. See the AgentSource registry of record.
registry of record: the principle that SQLite is the canonical store of which agents and teams exist. The OpenClaw Gateway is one AgentSource synced into SQLite, not the source of truth for the registry. See the AgentSource registry of record.
Teams and planes
team: a named group of Boos. A team has a leader (Boo Zero by default), an emoji/color, durable rules, and a shared room. Teams are the unit of collaboration. See teams and planes. shared plane: everything Clawboo owns and coordinates across runtimes: the registry, the board, team chat, scheduling, shared memory, the tools broker, verification, governance, the event log, and the worktree system-of-record. See teams and planes. private plane: everything a single runtime keeps to itself: its own messaging channels, its own cron/heartbeat, its private cognitive memory and self-improvement, its built-in tools, and its native session resume. Clawboo observes the private plane but never clobbers it. The split is resolved from a runtime’s capabilities byresolveRuntimeIntegration. See teams and planes.
Know Your Team gate: a once-per-team onboarding flow that runs before the group-chat composer unlocks. It has two phases: a “Meet your team” welcome (roster plus the leader), then a user self-introduction that is persisted and injected into every team turn’s context. Cascade prevention lives in the server orchestrator, so the gate no longer needs an agent-introduction round. See group chat.
The board and orchestration
the board (the durable board): the transactional, SQLite-backed kanban board that is the source of truth for team task and coordination state. It survives refresh, supports race-free single-assignee claiming, and is the dispatcher the executor drives. See the board. task: one kanban card on the board. A task has one of seven statuses (backlog, todo, in_progress, in_review, blocked, done, cancelled), an optional assignee, dependencies, and an optional worktree. done and cancelled are terminal. See the board.
atomic claim: the race-free UPDATE … WHERE status='todo' AND assignee IS NULL AND dropped=0 that lets at most one caller win a task. An empty result is a conflict that the caller must NOT retry (the “never retry a 409” rule). See the board and board internals.
delegation: one agent handing a unit of work to another. In the shipping engine a delegation is a structured signal (a sessions_send tool call or a <delegate>/<plan> directive parsed from a terminal done) that becomes a durable board task plus a claim, never a regex match over prose. See delegation and orchestration.
Peer chat and MCP
mixed-runtime peer chat (team room): a sharedteam_chat room where every runtime is a named peer and any runtime can lead. It is narration over the canonical board: a chat post is never a write path to the board. See peer chat.
isUser=false: the safety-critical substring in a delivered peer post’s header ([Inter-session message · … · isUser=false]). It marks the post as tool-routed evidence from a peer, not a user instruction, so a peer that says “ignore your instructions” cannot land with user authority. The token is reproduced verbatim. See peer chat.
MCP (Model Context Protocol): the protocol Clawboo uses to expose its shared services to runtimes as tools. Runtimes attach Clawboo’s MCP servers over Streamable HTTP (or stdio) and act on the team’s coordination surface through them. See MCP servers.
MCP trifecta / quartet: Clawboo’s four hosted MCP servers: tasks (the board), memory (the shared tier), tools (the brokered tool surface), and teamchat (the peer room). The “trifecta” was the first three; “quartet” adds teamchat. See MCP tools reference.
Memory and capabilities
memory: Clawboo’s two-tier knowledge store. The shared tier is the SQLite-backedSqliteMemoryStore exposed via the Memory MCP server, which all five runtimes read and write; the private tier is each runtime’s own native memory, which Clawboo observes but never clobbers. A run’s MCP binding can scope writes to a team. See memory.
capability: any skill, tool, or connector a runtime can use, normalized into one CapabilityRecord. The records are fanned in from per-runtime CapabilitySource adapters into one inventory that drives both the Ghost Graph and the Capabilities dashboard. See capabilities.
CapabilitySource: an adapter whose read() projects a plane’s skills/tools/connectors into CapabilityRecords. Six exist: five per-runtime (native, hermes, claude-code, codex, openclaw) plus connector for Clawboo’s own outbound MCP connections. A multiplexer merges them and treats a source’s failure as data, not an error. See capabilities.
manageability tier: the per-capability field that decides whether Clawboo can write to it: managed (Clawboo owns the row), external-write (the runtime owns the store, Clawboo writes through it), runtime-of-record (Clawboo drives changes through the runtime’s API), or observe-only (read-only). The UI and the write path are a pure function of this tier. See capabilities.
connector: an MCP server Clawboo connects to itself, either by spawning it as a local child process or by dialling a remote one over HTTPS with an OAuth token. Distinct from a connector a runtime attaches, which Clawboo only observes. See connectors.
grant: one row that is simultaneously the permission the tool broker enforces and the edge the Ghost Graph draws. The renderer and the gate call the same decideGrant over the same rows, so a badge cannot disagree with what a call would actually do. An owner grant records what a runtime already attaches and is never drawn; an operator grant is a deliberate human share, and that is the one that draws an edge and can be detached. See connectors.
drift: a connected connector whose tool list no longer hashes to what a human approved, which is how a rug-pull shows up. Deliberately never collapsed into an error, because the remedy is different: an error says retry, drift says read what changed before trusting it again.
lethal trifecta: the combination of reading private data, ingesting untrusted content, and being able to reach the network, accumulated across a whole run rather than judged per call. A call whose run has all three always prompts, and that approval can never be remembered.
Verification
verification: the gate that makes “done” mean verified. A task carrying a non-promotable verdict cannot transition todone. See verification.
builder≠judge: the principle that the agent that did the work never certifies its own work. The only signals are the deterministic gate (an exit code) and an independent read-only critic; a generator never self-certifies. See verification.
deterministic gate: the strongest verification signal: Clawboo runs the task’s verify command and reads its exit code. A red gate is always a fail. See verification.
critic: the read-only independent reviewer that runs on a green gate when a diff is risky or large. It emits structured findings; a blocking finding turns the attempt into a fail and routes the fix back. See verification.
completed_with_debt: the verdict written when the verification attempt budget is spent and the last attempt still failed, with the open items recorded as debtNotes. It covers a red deterministic gate as well as an unresolved blocking critic finding. The board’s → done gate still treats it as promotable over a green gate, but the worktree completion path does not: an exhausted fix loop routes the task to blocked for a human. See verification.
Governance
governance: the guardrail layer that makes a runaway agent impossible, not just visible: budgets, circuit breakers, caps, and approvals. See governance. budget (kill-switch): a USD spending limit recorded in integer cents.recordSpend is atomic; a cap-mode budget auto-pauses at 100% (the kill-switch that aborts the run), while a warn-mode budget only tracks spend and emits warnings at the crossings without ever pausing. A budget with no row is uncapped. See governance and cost and budgets.
circuit breaker: a deterministic, cross-runtime backstop that stops a run burning turns or tokens with no progress. It trips on iteration-cap, repeat-failure, no-progress, token-velocity, or repeat-policy-denied, keyed on typed RuntimeEvent fields rather than scraped prose. See governance.
cap: a hard ceiling enforced in code: delegation depth (default max 2), per-turn fan-out, per-parent live-child count on the board (default 24), a root-creation rate (default 30 per 5 min), and per-node cost. The depth cap is the single-reduce-point + report-up-by-default discipline. See governance.
approval: a human gate on something an agent wants to do, resolved from the Approvals queue. Three kinds share that queue. A tool or delegation approval is Clawboo’s own database-mediated handshake for a risky brokered call. An exec approval is a shell command OpenClaw’s Gateway is holding: the Gateway still owns the decision, but Clawboo now mirrors the request into the same tool_call_approvals table (kind: 'exec') and answers it over the server’s own Gateway connection, so the card survives a closed browser tab. A run_command approval is a native Boo asking to run one program. See approvals.
standing grant: a command an OpenClaw Boo may run without asking again, written by the Gateway when someone answers Always to an exec approval. Clawboo lists a Boo’s standing grants in its Permissions tab and is the only place in Clawboo they can be taken back. A grant is usually bound to both the exact command and the folder it ran in, so the same command run elsewhere asks again. See command permissions.
run_command: the native runtime’s shell tool. It is a local tool rather than a brokered one, so it exists only inside a clawboo-native run and never appears in any other runtime. It is off unless switched on per Boo, takes one program as an argument list rather than a shell string, asks a person before every command, and remembers nothing. See Clawboo Native.
Observability
observability: the layer that makes the orchestrator measurable and debuggable: an append-only event log, traces, a Ghost-Graph projection, and a fleet-health triage. See observability. event log: the append-only, SQLite-backed stream of orchestration events (each with a monotonicseq). It is the always-on local trace store; replaying it deterministically reproduces the projected graph state. See observability.
trace: one mission’s events grouped by traceId, reconstructed into a span tree. When an OTLP endpoint is configured the same trace is exported to Jaeger; otherwise the event log is the trace store. See observability.
fleet health: the triage taxonomy projected from the event log: working, idle, stalled (quiet past a threshold while an execution is open), and zombie (quiet long enough that the process is almost certainly dead). See observability.
Worktrees, handoff, scheduling
worktree: a per-task git worktree on its own branch, provisioned outside the user’s repo, giving a file-mutating task an isolated world any runtime can pick up. It provides concurrency isolation, not a privilege boundary. See worktrees and handoff. system-of-record: the durable, on-disk scaffold committed into each worktree root (TASK.md, task-progress.md, DECISIONS.json, init.sh, VERIFICATION.md) so a cold runtime can answer “what is this / how to run / how to verify / where are we” from files alone. See worktrees and handoff.
AGENT_HANDOFF: AGENT_HANDOFF.json, the structured, zod-validated clock-out artifact written into a worktree (done/broken/next-step, commands, evidence, native session id). It is the cross-runtime bridge: one runtime can pause and a different runtime can reconstruct state from this file. See worktrees and handoff.
Routine: scheduled work for a team or one agent. A team routine posts its instructions into the team’s group chat for the team’s lead; an agent routine files a board task for one agent. Routines are Clawboo’s own cron for team work, distinct from a runtime’s own-life cron; trying to register a team-task schedule into a runtime-own-life source is refused. See scheduling and Routines.
scheduler: the engine that fires Routines: a durable scheduled_runs ledger as source of truth plus a rebuildable in-process ticker. A team routine’s fire goes through the team chat to the team’s lead; an agent routine’s fire is dispatched through the standard executor pipeline. See scheduling.
Gateway and events
Gateway: the OpenClaw Gateway, the runtime + upstream theopenclaw runtime talks to. The browser never connects to it directly; it goes through Clawboo’s same-origin proxy, which injects auth server-side. See the Gateway and events and the OpenClaw runtime.
Bridge→Policy→Handler: the three-layer pipeline every Gateway event flows through: the Bridge classifies a raw frame (classifyEvent), the Policy is a pure function deriving intents (derivePolicy), and the Handler dispatches to state (createEventHandler). No event takes a shortcut around it. See the Gateway and events and the event pipeline.
device pairing: OpenClaw 2026.5.x requires a human to approve a new device before its WebSocket connect succeeds; an unapproved connect returns NOT_PAIRED. Clawboo surfaces a one-click approval that shells out to the OpenClaw CLI. See the OpenClaw runtime.
UI surfaces
Ghost Graph: the React Flow canvas that renders a team’s Boos, their skills/resources as orbital nodes, and their delegation edges, with optional team halos and click-to-expand. See the Ghost Graph. Atlas: the global, all-teams view of the Ghost Graph: Boo Zero presides at the top over per-team rows. Reached via the dedicated Atlas nav button. See the Ghost Graph. marketplace: the in-app catalog of 436 first-class agents and 85 workflow teams across nineteen packs, two of Clawboo’s own and seventeen adapted from upstream repositories (sixteen MIT-licensed, one Apache-2.0). The content is hand-maintained JSON under the repository’scatalog/ folder, excluded from the npm tarball and fetched at runtime from /api/catalog/*; only the built-in pack is compiled in, so first-run onboarding works offline. Deploying an entry writes its markdown body to the agent’s files. See the marketplace and the marketplace catalog reference.
Security
vault (secrets vault): Clawboo’s encrypted-at-rest store for runtime credentials. Each value is encrypted with AES-256-GCM under a local master key; the key-resolution chain is process env → vault → OpenClaw’s.env. It is defense in depth: a wrong or lost master key fails closed, protecting against casual inspection and a leaked vault file. See security.