Glossary
Core entities
Section titled “Core entities”Agent: An AI worker with an identity, role, skills, and capabilities. Belongs to exactly one workspace. The primary actor in the system.
Workspace: The top-level isolation tenant. Groups agents, repos, channels, tickets, memory, and pipelines. All workspace-scoped data is hard-isolated.
Repo: A Git repository registered in the system. Global across workspaces but linkable to multiple workspaces for worktree provisioning.
Isolated repo: A workspace-scoped copy-on-write worktree of a registered repo. Provisioned per channel so agents never mutate the source checkout.
Channel: A messaging container. Either a channel (two participants) or a group. Workspace-scoped. Carries a mode.
Ticket: The unit-of-work aggregate. Vendor-agnostic (local or synced with Linear). Supports hierarchy, links, and delegation.
Pipeline: A DAG-based workflow that chains steps (agent dispatch, scripts, conditionals) together. Defined by templates; executed as runs.
Value objects
Section titled “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.
AgentCapabilities: Per-channel flags (push to repo, GitHub API, ticketing, network egress) gated by the credential broker.
Mode: chat, plan, or review. Gates the system prompt, sandbox writes, and MCP tool allowlist.
SandboxBackend: native (OS-native Seatbelt/bubblewrap) or none (no isolation).
RunCost: Token/cost tally (input tokens, output tokens, estimated cost in cents) for a single agent run.
WakeReason: Why an agent was dispatched: user message, ticket assignment, pipeline step, or review dispatch.
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
Section titled “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 optimistic-concurrency mutation chokepoint and workspace isolation enforcement.
TicketDispatcher: Sole owner of assigned-ticket to agent dispatch: on TicketAssigned, checks readiness, ensures channel, transitions status, dispatches once.
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.
CostTracker: Computes per-run token cost and persists it onto the run log.
BudgetEnforcementService: Enforces per-scope monthly spend budgets, blocking dispatch when exhausted.
Events
Section titled “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, observability, analytics.
Meetings and calendar
Section titled “Meetings and calendar”Meeting: A locally recorded, transcribed meeting session. Captures microphone and system audio, transcribes on-device with Whisper, diarizes speakers, and summarizes into notes, action items, and decisions. 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 tokens live in the platform keychain; an authExpiredAt flag drives the reconnect banner.
Architecture terms
Section titled “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
Section titled “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. Global across workspaces (like repos). The first user becomes the workspace admin; others join by invite or OIDC.
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-channel 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 ~12 effect classes (fileDelete, gitPush, prCreate, networkEgress, processSpawn, …). Every mutating tool declares its classes; the guardrail engine resolves allow / prompt / deny per scope (channel > agent > workspace > mode preset > 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 / Review Studio: The interactive planning surface (editable typed-DAG plans with per-step cost/time/risk and partial approval) and the semantic multi-modal PR review surface (graph-derived cohorts, typed diagrams, in-app visual diffs, API contract diffs, multi-axis gates).
Fleet, evals, and replay
Section titled “Fleet, evals, and replay”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 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).
SessionRecording: An event stream plus HTTP/LLM cassettes and tool I/O captured for one run, paired with an AgentConfigHash. Powers deterministic replay (cassettes stubbed, executes nothing) distinct from live re-execution (real model, sandboxed).
Golden session: A blessed SessionRecording pinned per agent or playbook. A prompt or model edit that regresses a golden is blocked with evidence.
Deployment and clients
Section titled “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 a WebRTC data channel.
RPC workspace binding: Every server session is bound to one workspace, the sole source of workspace_id for its calls. A client bound to workspace A cannot reach workspace B.
cc_remote: The phone thin client — a Flutter web PWA that remote-controls the fleet over a WebRTC data channel with a default-deny tool policy.
cc_signaling_server: A stateless WebSocket signaling broker for WebRTC pairing — a dumb relay that never interprets SDP/ICE, holds no app data, and never sees the pairing PSK.