Glossary

Core entities

Agent: An AI worker with an identity, role, skills and capabilities. Belongs to exactly one workspace. The primary actor in the system.

Adapter: The runner that executes an agent turn. Two ship: Control Center (built-in) — the in-process harness that talks to model providers — and Claude Code via claude -p. Cursor, Codex, Anthropic, OpenAI and the rest are providers on the built-in adapter, not separate CLIs. See Manage adapters and models.

Workspace: The top-level isolation tenant. Groups agents, repos, spaces, tickets, memory and pipelines. Isolation is structural, not conventional: each workspace has its own SQLite file (<dataDir>/<workspaceId>/workspace.db), so a cross-workspace read does not compile. Every in-app route is prefixed /workspaces/:workspaceId — see the route map.

Forge: A code host — GitHub, GitLab or Bitbucket Cloud. The forge is a property of each repo, read from its origin remote at registration, and it selects that repo’s API adapter and credential. One workspace can hold repos on all three; aggregating surfaces (the inbox, the PR queue) fan out across every forge represented and merge the results, isolating failures so an unreachable forge never empties the others. Forges differ in what they support — see the capability table in Connect a code host.

Repo: A Git repository registered inside one workspace. Workspace-scoped — the same checkout registered in two workspaces is two independent rows with two ids; repo identity across workspaces is by filesystem path, never by id. Registration requires a git work tree whose origin remote points at a supported forge. Each repo carries that forge (github / gitlab / bitbucket), which selects the API adapter and credential used for it.

Isolated repo: A workspace-scoped worktree of a registered repo. Copy-on-write via rift wherever that native ships; git worktree on Windows. Provisioned per space — every conversation in that space shares one checkout — so agents never mutate the source.

Space: A workspace-scoped collaboration container with human and agent participants, a persisted Mode, provisioning status and a SpaceKind (topic / agentPeer / system / pr / slack) that decides how it is sectioned, muted, badged and garbage-collected. It owns the isolated worktrees its conversations share (copy-on-write via rift; git worktree on Windows).

Conversation: One message stream inside a Space, with its own id, history and agent-run context. Conversations in a space are flat equals — there is no primary or “main” stream. Each opens as an editor tab; a space’s unread state aggregates across all of them.

Thread: A Conversation whose anchorMessageId is set: anchored to one message of a sibling conversation in the same Space, with a fresh agent context seeded by that anchor message. One level deep — threads never anchor to threads.

Ticket: The unit-of-work aggregate. Vendor-neutral: local by default, with sync adapters for Linear, GitHub Issues, Jira Cloud and ClickUp — though no in-app surface creates a sync connection. Supports hierarchy, links and delegation. Assignment to an agent records ownership and dispatches nothing; assignment to a team is the exception (TeamRoutingService dispatches the leader).

Pipeline: A DAG-based workflow that chains steps (agent dispatch, scripts, conditionals) together. Defined by templates; executed as runs.

Value objects

AgentRole: Enumerated role (CEO, coder, reviewer, QA, designer, security, devops, PM, general). Determines persona, memory access and hierarchy.

AgentSkills: Case-insensitive set of skill identifiers that inject relevant context into prompts at dispatch time.

Skill source: A GitHub repository registered per workspace as a skill catalog. Untrusted by construction: the repository’s metadata is display-only and every install passes the fail-closed scan gate before any content reaches disk or a prompt. See install and manage skills.

skills-lock.json: The per-workspace manifest of installed skills: for each one its source repository, repo path, the commit it is pinned to and a rolled-up content hash. Installs, updates and uninstalls keep it current; verify_skills checks it against disk.

AgentCapabilities: Four flags (push to repo, GitHub API, ticketing, network egress) resolved per dispatch — agent default → user default, with a per-conversation override. Enforced by absence: a disabled capability means the token or egress is simply never injected.

Mode: chat, plan, review, or orchestrate. Stored per space, so one agent can be in different modes in different spaces; every conversation in a space shares it. Gates the system prompt, the sandbox write rules and the MCP tool allowlist. The composer offers only chat, plan and orchestrate; chat is labelled “Agent”.

SandboxBackend: microvm (an enclosed VM — the one backend with a kernel boundary, applied to interactive terminals), native (Seatbelt on macOS, bubblewrap on Linux and WSL2) or none. Probed once at boot; native is applied to agent dispatch when available, wrapping the Claude Code CLI and the harness bash tool. Windows has no native backend and Linux needs bwrap plus socat, so runs there are unwrapped; --sandbox off opts out deliberately.

Rig: A disposable machine an agent drives in real time — an enclosed browser or Linux desktop, a host-managed Android emulator or iOS Simulator, or an enclosed terminal. Watched live over its own full-resolution lane, with take-over enforced server-side. Scoped to a conversation so the human tab and the agent’s browser_use / computer_use / mobile_use / ios_use calls address one default machine. See Rigs and enclosures.

Enclosure: The stronger VM-backed rig boundary — a kernel boundary, throwaway overlay disk, deny-by-default network gate and credential broker. Android and iOS rigs are disposable but use host-managed networking and do not claim this boundary. Driving any rig uses the enclosureControl guardrail class.

RunCost: Token/cost tally (input tokens, output tokens, estimated cost in cents) for a single agent run.

WakeReason: Why an agent was dispatched. Six values: user message, ticket assignment, recovery re-dispatch after a failure, child ticket completed, scheduled follow-up heartbeat and pipeline step.

Ports

SandboxPort: Manages sandbox lifecycle (probe, launch, events, exec, destroy).

CredentialBrokerPort: Mints scoped, capability-gated credentials for sandbox launch and revokes them on teardown.

GitRepoInspectorPort: Extracts metadata (owner, repo, branch) from a local Git repo path.

EmbeddingPort: Produces unit-norm text embedding vectors for semantic search.

NotificationPort: Shows native desktop notifications respecting category/route gating.

TicketProviderPort: Vendor-agnostic boundary to a ticketing backend (create, get, list, update, transition, assign).

PipelineEnginePort: Starts a pipeline run from a template, decoupling callers from the concrete engine.

Domain services

AgentDispatchService: Launches agent runs: provisions isolated repos, builds prompts, creates run logs, returns live event streams.

TicketWorkflowService: Pure-domain ticket lifecycle engine with an optimistic-concurrency mutation chokepoint and workspace isolation enforcement. Its transition graph binds agents and automation only; user-driven UI changes pass force: true and bypass it. There is no ticket dispatcher for an agent assignee — AgentDispatchService owns dispatch, and assigning a ticket to an agent starts no run. Assigning a ticket to a team is the exception (TeamRoutingService dispatches the leader).

PipelineEngine: Orchestrates run execution: starts runs, schedules steps, persists state, handles routers/joins/continue-on-fail, resumes in-flight runs after restart.

PipelineTriggerDispatcher: Subscribes to domain events and auto-starts matching pipeline runs for enabled triggers.

MemoryAccessPolicy: Resolves and enforces agent role memory permissions on domains.

HarnessCostCalculator: Prices built-in harness token usage into a RunCost from the models.dev catalog. Dispatch persists that tally onto the run log.

BudgetEnforcementService: Computes per-agent monthly spend and a pre-dispatch block (checkInvocationBlock). That block is consulted only by the recovery reconcilers (OrphanRunReaper, StrandedTicketReconciler), never by an ordinary user or agent dispatch.

BudgetGovernanceService: Evaluates per-agent monthly spend after each run — a soft threshold records a warning incident; exhaustion records a hard incident and flips the agent’s lifecycle to paused.

Events

DomainEventBus: In-process broadcast publish/subscribe bus for cross-feature communication. Events are typed; subscribers consume on<T>() streams.

DomainEvent: Base interface. Every event has occurredAt. Key categories: workspace/agent, PR/review, messaging, ticketing, pipeline, meetings/calendar, identity, rigs, observability.

Meetings and calendar

Meeting: A locally recorded, transcribed meeting session. Captures microphone and system audio, transcribes on-device with a selectable ASR model (Parakeet TDT v3 by default; Parakeet TDT v2, Whisper large-v3-turbo and Whisper base.en are alternatives), diarizes speakers and summarizes into notes, action items and decisions. The selected ASR model is force-installed at boot and recording ops light up after one restart. Workspace-scoped; stays on the machine.

MeetingSegment: One transcribed window of audio, speaker-tagged (me/them) with a diarization label and millisecond offsets.

MeetingActionItem / MeetingDecision: Structured outputs extracted by the summary pipeline and stored as discrete rows. Action items can link to a ticket.

CalendarEvent: A synced Google Calendar entry scoped to a workspace and connected account. Distinct from a Meeting: an event is a scheduled commitment; a Meeting is a recorded session. Linked one-to-one via a MeetingCalendarLink.

CalendarAccount: A connected Google account, per workspace and email. OAuth refresh tokens are stored server-side as google_* keys in <dataDir>/secrets.json and never reach a client; the device-code flow completes on the server. An authExpiredAt flag drives the reconnect banner.

Architecture terms

Clean Architecture: Dependency rule: Presentation → Application/Providers → Domain ← Infrastructure. Domain has zero infrastructure imports.

Ports and adapters: Domain defines abstract interfaces (ports); infrastructure provides concrete implementations (adapters). Composition root binds them.

Shared kernel: core/domain/ entities, value objects, ports and services shared across 3+ features.

Feature-first: Code is organized by business domain (agents, pipelines, messaging) rather than by technical layer.

Multiplayer, identity and velocity

Principal: A sealed value unifying humans and agents as the single actor abstraction — UserPrincipal(userId) or AgentPrincipal(agentId). Every message, ticket, review, plan and run log attributes through a Principal.

User: A human identity, stored in global.db and therefore global across workspaces. The principal that creates a workspace becomes its owner — stamped on Workspace.ownerUserId with an owner-role membership row in the same operation. Others join by invite or SSO.

WorkspaceMember / WorkspaceRole: A membership row binding a User to a Workspace at a role (owner / admin / member / viewer / guest). Membership — not a pairing key — is the access boundary. Per-repo grants keep membership from out-privileging the forge.

ParticipantPresence: Ephemeral awareness for a Principal (status, locus, cursor, typing, an agent’s live status and running cost). Never persisted; server-hubbed; repo-grant filtered before fan-out.

Follow-mode: Click an avatar to ride its viewport until you act, then detach. Works for humans and for agents (“watch an agent work”).

Autonomy dial: A per-space per-agent control — propose-only / act-with-approval / act-freely — implemented as a named profile over the action-guardrail store.

ActionClass: A closed set of 13 effect classes (fileDelete, gitPush, prCreate, networkEgress, processSpawn, enclosureControl, …). Every mutating tool declares its classes; the guardrail engine resolves allow / prompt / deny per scope (space > agent > workspace > mode preset > built-in default).

WriteLedger / idempotency key: Every mutation carries a client-generated idempotency key (UUIDv7, per logical action). The workspace-scoped ledger dedupes before the handler runs; a replay returns the byte-identical original result. Makes reconnect and multi-client safe by construction.

Needs me inbox: A cross-pillar queue with a strict rule — an item appears only if it blocks something (an agent, a merge, a sync) or explicitly requests the operator.

Plan Studio: The interactive planning surface — editable typed-DAG plans with per-step cost, time and risk, and partial approval.

Review compute: Server-side PR review compute (graph-derived cohorts, typed diagrams, visual diffs, API contract diffs, multi-axis gates) served over review_studio.* and folded into the Review tab.

Review space: A PR’s single backing space (mode review, kind pr), created idempotently and linked to the PR by a ReviewSpaceAssociation. Every reviewer files findings in it, which is what makes them comparable; its isolated worktree has the PR checked out at its head.

Review node: The structured unit of an AI review finding: kind (bug, suggestion, recommendation, question, ticket), priority P0–P3, a category/severity/effort triage triple, a file-and-line anchor, optional suggested fix and a confidence score. Filed with add_review_node; the verdict is computed from nodes, not prose.

Consensus-ready: The review node status reached only when a peer reviewer confirms a finding — an agent cannot confirm its own. The Review tab’s Publish to GitHub button sends every remaining open finding (selection: all_open); the MCP tool publish_review_to_github still defaults to peer-confirmed findings only.

Review level: Workspace policy (light, balanced, thorough) dialing which reviewers fan out (engineer only; +qa+architect; +security+perf) and where sub-threshold findings render. Never deletes a finding.

Review axis: One of five per-review scoring lanes: correctness, security and testGap drawn from reviewer findings; visual and apiContract deterministic. Gated axes fold into the verdict and can only make it more severe — a partial or unavailable gate holds the verdict rather than passing it.

Review verdict: ship, hold or block. Any P0 finding with confidence ≥ 0.7 blocks; any other P0 or any P1 holds; otherwise ship. A gated failing axis forces block and cannot be out-voted by findings.

Fleet and evals

cc_worker: A headless pure-Dart fleet executor binary. Pairs with a cc_server, declares its host capabilities, pulls leased jobs, executes them and streams process events back. Holds no durable state — one authoritative server, N dumb limbs.

JobSpec: The typed spec for everything executable (agent run, pipeline step, code-index, golden-render, benchmark, eval batch).

Eval suite: A workspace-scoped evaluation definition (prompt, target agent and mode, graders). Five starters seed on workspace creation; Observability → Quality lists them.

Deployment and clients

Thin-client architecture: No client opens the database; a headless cc_server process owns the data and serves it over WebSocket RPC. Every client (desktop, web, phone) is a renderer over that one RPC connection.

cc_server: The headless server binary (pure-Dart, no Flutter engine). Owns the Drift/SQLite database, serves repo-RPC over WebSocket and runs the background services (pipelines, MCP, reconcilers).

ServerConnectionMode: How the desktop reaches its server — local (spawn a cc_server on this machine, the default) or remote (dial one elsewhere). The web client is always remote.

RemoteRpcClient: The transport-agnostic JSON-RPC client every thin client uses to talk to its server — over WSS, loopback, or the brokered relay.

Per-call workspace scoping: The server is stateless — there is no per-session workspace binding, so multiple clients on one server never share a “current workspace”. Every workspace-scoped repo/call and sub/subscribe must carry workspace_id in its args; a missing or unregistered id is refused before any database opens. Access is then gated by workspace membership and role, not by the session.

cc_remote: The phone thin client — a Flutter web PWA that remote-controls the fleet over the brokered relay with a default-deny tool policy.

cc_signaling_server: A stateless WebSocket relay broker hosting invite-gated rooms — a dumb relay that forwards only end-to-end-sealed frames, holds no app data and never sees the pairing PSK.

See also

• Route map
• Architecture
• Workspaces
• Domain events