How Cusp fits together
One model behind every feature — definitions become runs, runs live in places and start from triggers, and everything that needs you lands in one inbox.
Sessions, subagents, races, reviews, crew members and scheduled jobs look like different features. In Cusp they are one thing seen from different angles. Once you know the model, every screen in the app reads the same way, and what you learn in one place carries over to the rest.
The building blocks
| Block | What it is | Examples |
|---|---|---|
| Definition | A reusable description of who does what: prompt, tools, skills, model, permissions | An agent .md file, a skill, a crew role, a workflow script, a review level |
| Run | One execution of a definition. Every run is a session: an event log with a status, a cost and a place | Your main session, a subagent, a race lane, a review, a crew member's shift |
| Place | Where a run executes and what it can touch | Your folder, an isolated worktree, a cloud sandbox (coming soon) |
| Trigger | Why a run started | You sent a message, a parent agent spawned it, a schedule fired, someone mentioned @cusp on GitHub |
| Identity | A persistent actor that owns runs over time, with memory and a budget | A crew member, you |
| Channel | How runs and people talk to each other | Messages between agents, the crew team room, pull request comments |
| Artifact | What a run leaves behind | A diff, a branch or pull request, review findings, a plan, a cost receipt |
Most features are a combination of these:
- A subagent is a child run started by its parent, in the same folder (read-only) or its own worktree (when it writes).
- A race is several runs of the same prompt on different models, each in its own worktree. See Race.
- A review is a run, or a small team of runs, that reads a diff and reports findings. See Review.
- A crew member is an identity whose shifts are runs, started by schedules, events and messages.
- A scheduled task is a trigger attached to a definition.
Because they are all runs, they all behave alike: you can open any of them, read its transcript, see what it cost, and continue or fork it.
One gate for side effects
Every run, of every kind, goes through the same permission engine before it edits a file, runs a command or reaches the network. Crew approval policies, CLI flags, the Agent SDK's canUseTool callback and your own rules are all inputs to that one gate. There is no second path that skips it, so a rule you write applies to a subagent, a race lane and a crew member the same way it applies to you.
The sandbox sits behind the gate and limits what a shell command can do once it runs.
Shared services
Cusp is designed around four shared services. Each exists once and every run uses it.
| Service | What it does | Today |
|---|---|---|
| Gate | Decides whether a side effect may happen | Shipped: the permission engine and sandbox |
| Ledger | Records usage and cost for every run, and holds budgets | Partial: per-turn receipts and the usage page work; budgets warn but can't pause a session yet. See Budgets and receipts |
| Supervisor | Schedules runs, shares provider rate limits across all of them, and backs off on errors | Preview: built and tested as a library, not yet running in the daemon |
| Blackboard | Shared state between runs: a task board, file leases, findings | Preview: built and tested as a library, not yet running in the daemon |
The supervisor and blackboard are in preview. Until they're wired into the daemon, sessions schedule independently, provider rate limits are handled per session with retries, and parallel writers are kept apart by worktrees rather than file leases. See Parallel agents for what works today.
Where you meet the model
Two views sit on top of all runs:
- The inbox collects every place a run is waiting for you: a permission prompt, a question, a plan to approve, a failing check, a pull request ready to merge. See Attention inbox.
- Mission control is the live picture of what is running, what is waiting and what each run is touching, with controls to steer, pause or stop. Today that picture is spread across the session sidebar, the Board and the crew office.
A single mission control view of the whole run tree, with pause and re-budget for any branch of it, is coming soon.
How parallel work is meant to go
Cusp's rules for running many agents at once:
- Fan-out is cheap and safe. Read-only helpers share your folder. Anything that writes in parallel gets its own worktree.
- Coordination before collision. Writers announce which files they're editing, so overlaps surface as a message instead of a merge conflict.
- Finished work lands through a queue that rebases, runs your checks and merges one change at a time.
- Results stay small. Child runs report a short summary and links; the parent reads details only when it needs them.
- You can steer any run while it works.
- The scheduler, not the model, decides how many runs execute at once.
Rules 1 and 5 work today, and subagents already report back a result rather than their whole transcript. Rules 2, 3 and 6 depend on the blackboard, merge queue and supervisor, which are in preview. Parallel agents separates the two in detail.
Agents can operate Cusp too
Anything you can do in Cusp, an agent should be able to do from chat, through the same operations and the same gate. Reading state and acting inside the run's own scope are ordinary tools. Anything that creates standing work, spends money, publishes or acts on someone else's behalf becomes an approval in your inbox.
Chat control tools are in preview. The crew family (crew.status, crew.hire, crew.assign and so on) is designed and tested, but not yet offered in chat sessions. See Crew.
Next
- Sessions: the run every feature is built on.
- Permissions: the gate.
- Working with agents: race, inbox, budgets, review and parallel work.