CONTRIBUTING.md.
How the codebase is laid out
Clawboo is a TypeScript monorepo. pnpm workspaces link the packages and Turborepo runs the build in dependency order.pnpm-workspace.yaml has four globs: packages/*, packages/adapters/*, apps/* and docs.
So
packages/ holds 33 @clawboo/* packages: 27 at the top level and 6 adapters. Every one of them is private: true. The build inlines the libraries the server needs into one bundle, which ships inside the clawboo package. Dependencies flow one way: apps import packages, and a lint rule fails any package that imports an app. Monorepo and build covers the build order and what ships.
The packages group by job:
The package overview says what each package is for, who uses it and how the packages depend on each other, and links the deeper package guides.
Architecture at a glance
Clawboo runs as one local Node process. The CLI starts it, the browser talks to it, and it keeps its state in one SQLite file. Agents run on the runtimes you connect, and every runtime reaches Clawboo’s board and memory through MCP servers.The CLI starts the server, then exits
clawboo is a launcher. It first looks for a dashboard that is already running: the port in CLAWBOO_API_PORT (or CLAWBOO_API_URL), then the port the server wrote to ~/.clawboo/api-port.txt, then ports 18790 to 18809. A port counts only when GET /api/settings answers with Clawboo’s JSON shape, because other services listen in that range. If nothing answers, the CLI forks the bundled server.js as a detached process with ~/.clawboo as its working directory, waits for it, and opens the browser. The code is in apps/cli/src/lifecycle.ts.
The server serves the dashboard and the API on one origin
The Express server serves the built SPA and every/api/* route from the same origin, so the browser needs no backend address. It binds 127.0.0.1 unless HOST says otherwise, and listens on the first free port from 18790 to 18809 (or exactly CLAWBOO_API_PORT). The SPA builds its requests with apiFetch() and apiUrl() from @clawboo/control-client, so the app also works under a path prefix (CLAWBOO_BASE_PATH).
An access token gates /api/* and the Gateway WebSocket: STUDIO_ACCESS_TOKEN when set, otherwise the per-install token in <CLAWBOO_HOME>/access-token (packages/config/src/accessToken.ts). A blank STUDIO_ACCESS_TOKEN turns the gate off, and a non-loopback bind with the gate off refuses to start unless CLAWBOO_ALLOW_INSECURE=1 is set. Security has the full model; the entry point is apps/web/server/index.ts.
Prompts go only to the providers and apps you connect, and Clawboo itself sends no telemetry. The server makes three calls of its own. It fetches the marketplace catalog index from GitHub at its own release tag, or from main in a development build or when the release’s tag has no index (catalogIndex.ts, overridable with CLAWBOO_CATALOG_INDEX_URL), and checks npm for a newer clawboo (updateCheck.ts, off with CLAWBOO_DISABLE_SELF_UPDATE), each cached for 6 hours. When a model picker opens, it also reads OpenRouter’s public model list without a key (openrouterModels.ts, cached for 30 minutes).
SQLite holds the state
One file,clawboo.db in ~/.clawboo (or CLAWBOO_HOME), holds the board, the agent registry, memory, budgets and the event log. Server code reaches it through one shared connection, getDb() in apps/web/server/lib/db.ts. The schema is the CREATE TABLE IF NOT EXISTS DDL in packages/db/src/schemaBootstrap.ts. Opening an older file adds the columns it is missing; there is no migration ladder. See Board internals and the database schema.
Agents run on runtimes
A runtime is the engine an agent runs on. Clawboo Native runs inside the server process and calls the provider SDKs directly. Claude Code (through the Claude Agent SDK) and Codex (codex app-server) run as local processes the server starts, and Hermes agents run in one Hermes gateway the server starts and supervises. OpenClaw agents run inside the OpenClaw Gateway. Each runtime has a RuntimeAdapter that maps its output onto one normalized event stream; see The RuntimeAdapter trait.
MCP servers give every runtime the same tools
Clawboo hosts four MCP servers over the same SQLite data: Tasks (the board), Memory, Tools and TeamChat. Clawboo Native connects to them in-process. Claude Code, Codex and Hermes attach over loopback HTTP at/api/mcp/*; each attach URL carries a token the server checks. Hermes’s gateway keeps one signed URL per agent and server, and the server binds each call to that agent’s run in progress. OpenClaw agents get Tasks, Memory and Tools through the Gateway’s config, and no TeamChat. The same servers ship as stdio bins (clawboo-mcp-tasks and three more) for agents outside Clawboo; those bins open ~/.openclaw/clawboo/clawboo.db unless CLAWBOO_DB_PATH says otherwise. See MCP servers.
The OpenClaw Gateway is reached two ways
The browser opens a WebSocket to/api/gateway/ws, and the server proxies it to the Gateway. The server adds the saved Gateway token and signs the device handshake, so the browser needs no Gateway credential of its own. This connection carries OpenClaw 1:1 chat and the live fleet view, which the browser processes through the pipeline in @clawboo/events.
The server also keeps its own Gateway connection. It runs OpenClaw team-chat turns and Routine fires, syncs OpenClaw agents into SQLite, and records their activity and spend. It also mirrors OpenClaw’s shell-command approval requests, so they still reach you when no dashboard tab is open. See Gateway connection internals.
The event log feeds observability
The server appends coordination events (a task created, a delegation routed, a run started, a cost recorded) to theorchestration_events table. The Observability panel and the live status layer on a team’s graph read from that log. The graph’s layout comes from the team roster and each agent’s routing, not from the log. See Observability.
The two execution paths
Most work reaches a runtime along one of two server paths. They share the board and the runtimes, but not the safety and quality machinery, so check which path your change sits on. How a team works explains the same split for users.
Two smaller paths sit beside these. A Routine fire aimed at one OpenClaw agent goes through a dispatcher on the server’s Gateway connection (
apps/web/server/lib/routines/openclawDispatch.ts), with no worktree and no verification. A 1:1 chat with a Clawboo Native, Claude Code, Codex or Hermes agent runs one conversational turn per message in apps/web/server/lib/agentChat/driveAgentChat.ts, with no board task, in the agent’s team folder (teams/_no-team for an agent on no team).
Claude Code and Codex run with their own sandboxes and approval prompts turned off on every path, 1:1 chat included, and Hermes asks only before the commands its own policy flags. A worktree keeps a task’s file changes apart, but it is not a sandbox, and neither is the task’s or team’s folder that a run without a worktree starts in. What agents can do is the page that explains this; Verification and Governance cover the checks and budget guards per path.
Where to start reading
- Contributing: set up the repo, run the dev stack and pass the local gate.
- Monorepo and build: the workspace, the build order and what ships.
- Architecture invariants: the rules every change keeps.
- The page and the code for the area you are changing:
Dashboard views in code
Dashboard views in code
The main area shows one
ViewMode from apps/web/src/stores/view.ts: an agent page (agent), a team chat in General or a room (groupChat), Boo Zero (booZero), the welcome screen (welcome), or a nav panel (nav). Each nav panel has a NavView id, which is what navigateTo(view) takes. The labels come from apps/web/src/lib/navLabels.ts. Home is opened with openHome(teamId?, goalId?), which also hands it a one-shot homeFocus naming the team (or all) and the goal to show; the team rail and the Board’s goal links use it.Caution surfaces
A few files hold rules whose breakage shows up far from the edit. Read the comment block at the top of each, and the linked page, before you change one.Read it when
Related
CONTRIBUTING.md: the process rules in the repo itself.- How a team works: the same system from a user’s point of view.
- REST API reference: every route the server registers.
- Glossary: the terms these pages use.