Commands your agent runs
These are the commands your coding agent types while it works on a session. You rarely type them yourself: the app does the same things with buttons, and the agent learns them from the session protocol at the top of its context file. They are listed here so you can read what your agent did, or script it.
Every command takes a session by its id or its short reference (INV-12). Run any of them with --help for its options. How an agent uses them, step by step, is on Agents and harnesses.
Start and follow a session
| Command | What it does |
|---|---|
session next <id> | What the session needs now, and the exact command that does it. The agent's first and most frequent call. |
session status <id> <status> | Moves the session along its lifecycle: planning, planned, in-progress, executed. Refused when a step is out of order, or in-progress before a person approved. |
session harness <id> <name> | Declares the agent's harness, shown beside the status. Most verbs also take --harness. |
session list / session show <id> | Every session of the project; one session's header, and optionally its body. |
session path <id> | The absolute path of the session file. |
invariant session next INV-12
invariant session status INV-12 planning --harness claude
Write the plan and wait for a decision
| Command | What it does |
|---|---|
session write <id> --section Plan --file - | Replaces the session's body, or one ## section of it, from a file or stdin. |
session human-plan <id> | Writes the one-screen summary you read first (--template prints its template). |
session title <id> <title> | Renames the session. session status … planned --title "…" does both at once. |
session await <id> --approval | Waits once for your decision on the plan. --background lets Claude Code wait without holding the conversation. |
session reply <id> | Answers the note you sent the plan back with. |
session approve <id> | A person's verb: approves a plan from a terminal, after you type its reference back. It refuses an agent. |
invariant session write INV-12 --section Plan --file plan.md
invariant session status INV-12 planned --title "Add the export button"
invariant session await INV-12 --approval
Interviews and check-ins
| Command | What it does |
|---|---|
session ask <id> | Posts a round of questions, then waits for your answers. |
session agree <id> | Proposes the agreement that closes an interview, then waits for your decision. |
session check-in <id> | During a step-by-step or test-first build, posts a check-in and waits for your answer. |
session await <id> | Waits again: --round <n>, --agreement, --check-in. Exit code 6 means it is still waiting; run the command it printed. |
session interview <id> | Prints the interview so far: checklist, rounds, answers and agreement. |
Build and report
| Command | What it does |
|---|---|
session step list <id> / session step complete <id> <n> | The plan's steps; ticks one off as it lands. |
session summary <id> --file - | Writes the report you read on the session page. Required before executed. |
session contribute <id> --file - | Records what the session taught, for the project brain. --nothing-learned "<why>" says there was nothing. |
session attach <id> <files…> | Attaches images, PDFs or text files where the agent reads them. |
session diagram | Prints the brief for an Excalidraw diagram, a template, or checks diagrams. |
invariant session step complete INV-12 3
invariant session summary INV-12 --file summary.md
invariant session status INV-12 executed
Work with a team
These only apply to a project in an organisation.
| Command | What it does |
|---|---|
session comments <id> | The resolved conversations the agent has not acted on yet; session comments ack <id> <conversation> acknowledges one. |
session handoff <id> --to <member> | Assigns the session to a member and releases this machine's edit lock. |
session release <id> | Releases the edit lock without assigning anyone. |
session explore <id> <paths…> | Feeds the session's Radar: the files and folders the agent explored. --touched <paths…> or --nothing-touched says what the work changed, required before executed; --conflict <ref> "<why>" flags work running opposite to another active session. It never blocks a session. |
Plan more work
| Command | What it does |
|---|---|
plan "<task>" | Creates a new session from a task. --interactive interviews you first; --parallel gives it its own worktree and branch. |
iterate <id> "<task>" | Creates a follow-up session that continues an existing one. |
session parallel <id> | Moves a session into its own Git worktree and branch. |
session link <id> --parent <id> | Says which session this one continues. |
invariant plan "Add a CSV export to the orders page"
invariant iterate INV-12 "Also export the filters"
Reviews
| Command | What it does |
|---|---|
review open --session <id> | Composes a review session for the current branch, tied to the session whose work it reviews. --standalone reviews a branch alone; --fleet runs the project's reviewer gates. |
review --worktree <name> | Composes a review of another local worktree's branch, on its own, in that worktree's folder. Refused while a session is being built there. |
review again <review> | Starts the next round of a review. |
review list / review show <review> | Every review of the project; one review's comments. |
review plan-changes <review> | Turns a triaged review into its session's plan. |
review next, review brief, review submit, review await | For a fleet review: the gates still pending, one gate's brief, a gate's report, and the wait until every gate reported. |
review board <review> / review verify | The sealed board of a review, and its check. |
review waive <review-session> | A person's verb: waives one gate, with a reason. |
review publish <review> | Publishes a triaged review to GitLab as draft merge-request comments. |
Project brain
| Command | What it does |
|---|---|
brain context | What the brain knows about a session, an area (--area) or a search (--query). Agents run it before they investigate. |
brain doc list / brain doc read <id> | The maintained documents; one of them. |
brain doc template --kind document|prd|adr / brain doc write <id> | The template to follow, and the validated write of a document. |
brain areas | The index of areas, with their pages, decisions and sessions. |
brain consolidate | Opens an update that turns waiting session notes and the team's feedback into pages. |
brain brief, brain feedback, brain apply | During an update: its detail, what it did with each piece of feedback, and applying it. |
brain init, brain prepare, brain fetch, brain publish | Turns the brain on, prepares the branch draft, downloads the published brain, and publishes it to the organisation. |
Housekeeping
| Command | What it does |
|---|---|
validate | Checks every session (--reviews, --events for more) against the session format. |
session events <id> | What the project's log records about a session. |
session reconcile / session migrate | Infers transitions nobody reported; rewrites legacy or malformed headers. |
session archive <ids…> | Moves sessions to .invariant/sessions/.archive/. Nothing is deleted. |
session protocol | Prints the session protocol, for a context file Invariant does not manage. |