How Nib 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 Nib 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 @nib 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. Nib 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
Nib 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 | Shipped: per-turn receipts, the usage page, and budgets that pause a session at a hard cap. See Budgets and receipts |
| Supervisor | Schedules runs, shares provider rate limits across all of them, and backs off on errors | Shipped: runs in the daemon. See Parallel agents |
| Blackboard | Shared state between runs: a task board, file leases, findings | Shipped: runs in the daemon. See Parallel agents |
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, stop or re-budget any branch of the run tree. Open it from the command menu; see Parallel agents.
How parallel work is meant to go
Nib'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 Nib too
Anything you can do in Nib, 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. Creating standing work or acting in another session's scope follows the session's permission mode, like any other call: default asks you, auto's classifier decides, bypass runs it. Spending money, installing, publishing and acting with more authority than the agent has stay yours to approve: outside bypass they become an approval card in your Inbox that no agent, hook or classifier can answer, because a publish or an install reaches other people, and spending or escalating moves money or rights beyond the session.
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 Nib Crew.
Next
- Sessions: the run every feature is built on.
- Permissions: the gate.
- Working with agents: race, inbox, budgets, review and parallel work.