Agents and sessions

Start a ticket and the Cockpit runs a real agent for it in an embedded terminal. It is the same agent you would run in your own terminal: it works with your project's own permission settings, and it asks you in this terminal when it needs approval. Canon never turns on a permission bypass.

You can pick the agent for each session: Claude Code, Pi or Copilot CLI. Claude Code on one ticket and Pi on another is fine; give each ticket its own worktree so two sessions do not edit the same files; see Working in worktrees.

Start a session

Press ▶ Start on an open ticket, or ▶ Resume on one in progress, choose the agent and press ▶ Start sprint. The first time Claude Code opens in a folder it asks whether you trust it; see Quick start. The steps from there are in Sprint and gates.

Leave and come back

Closing the tab does not stop the agent. It keeps running, and the board shows its state on the ticket's card and in the Agents list on the left, grouped by project. The card's button changes to Open ▸.

The board of a project in the Cockpit. The ticket card in the In Progress lane has a yellow Working strip and an Open button, and the Agents list on the left shows the same session as working.
A running session: its state and an Open button.

Open the ticket again. Its terminal still says to press ▶ Start sprint, but the session is still running: it shows in the Agents list. Press ▶ Start sprint to rejoin it: the recent output is replayed, and you can carry on typing.

A ticket tab reopened while its agent is still running. The terminal says press Start sprint, the Start sprint button is enabled, and the Agents list shows the session as done, with reaps in 28m.
Reopening the ticket: Start sprint rejoins the running agent.

What the colours mean

Each session has one state:

The board with a ticket card in the Open column that has a pink border and a strip reading Needs you, with a pink Answer button. The Agents list at the left shows the same session as needs you, and the tab chip has a pink dot.
A session that needs you: a pink strip and an Answer button.

The same state shows in the Agents list, the tab dot, the Projects cards and the ticket's header. A session that is not waiting on you is ended automatically after a quiet spell: 5 minutes in a worktree, 30 minutes in the project's own folder. Any activity resets the timer, and the card counts it down ("reaps in 28m"). To reap a session is to end it; Admin explains the countdown.

Turn on Desktop notifications on the Admin page (off by default) to be told when a session starts waiting while the Cockpit is out of view. Your browser asks for permission only when you switch it on.

End a session

Press End Session in the ticket header. Canon asks how:

A dialog titled A sprint session is still running, explaining Save & End and End without saving, with three buttons: Save & End, End without saving and Cancel.
End Session offers Save & End.

Here is how Save & End works. Canon asks the agent, in the terminal, to save its state: append a short status to HANDOFF.md if anything changed, then print the exact line COCKPIT_STATE_SAVED and stop.

Canon ends the session at the first of three things:

If you type while it is saving, canon stops waiting and leaves the session running.

The terminal during Save & End. A highlighted prompt asks the agent to save its current state to HANDOFF.md and print the exact line COCKPIT_STATE_SAVED. Below it the agent has run a command and printed COCKPIT_STATE_SAVED. The ticket's Changes list now includes HANDOFF.md.
Save & End: the agent saves, then prints COCKPIT_STATE_SAVED.

Resume later

The ticket stays in progress, now with a ▶ Resume button. Its Status panel shows the saved state, so you can see where you stopped before you start anything. That state comes from HANDOFF.md; see Session continuity.

Press ▶ Start sprint to continue. Canon resumes the earlier conversation when it can; when it cannot, the agent runs sprint continue <id>, which reads the ticket's documents and carries on from the first unchecked item.

A ticket tab after ending a session. The Status panel shows the saved state: the sprint started, the plan, acceptance and research drafted and awaiting approval with no code yet, and the open question about defaults. The terminal says press Start sprint, and the Start sprint button is enabled.
Resuming: the saved state is in the Status panel.

If the Cockpit's background process stops while sessions are running, a banner offers to Resume or Dismiss each interrupted session when it starts again. Nothing restarts by itself.

Scratch sessions

Scratch on a project card starts the plain agent with no ticket, no sprint and no gates.

A Scratch session's panel: SCRATCH, no ticket, no gates. Starts in the main checkout, or its own scratch worktree when that is busy. End keeps any uncommitted changes in place. A Promote to ticket button.
A Scratch session's panel, with Promote to ticket.

A project can run several at once. The first uses the main folder. While a session is running there, a ticket's or another Scratch, the next gets its own worktree, which is removed when the session ends if nothing was done in it. A folder without git has no worktrees, so its Scratch sessions share the folder, and the board warns that they can overwrite each other.

When a scratch session turns into real work:

  1. Press Promote to ticket. The agent must be running. Canon asks it to write a short summary of the session, not the transcript, as a new ticket with tkt create, under the headings Problem, Findings, Changes so far and Open questions, and then to report the ticket's id. The tkt create command goes through your agent's usual approval.
  2. The panel then offers Continue as the new ticket, which ends the scratch session and lets the ticket's Cockpit resume the conversation, or Not now, which leaves the scratch session running. The ticket is already created either way.
The Scratch panel after promoting: SCRATCH, no ticket, no gates, a Promote to ticket button, and below it the message that a ticket was created and asking whether to continue this conversation as that ticket, with Continue as and Not now buttons.
After the agent creates the ticket: Continue as it, or Not now.

The whole window at that moment:

The whole Cockpit window after promoting a Scratch session in the ToDo project: the Scratch panel at the left with the Continue as message, and the terminal showing the request canon typed, the agent's tkt create command, and the line CANON_TICKET with the new ticket id.
The whole window after promoting. The terminal shows the request, the tkt create and the id; the panel offers Continue as. Click the picture to enlarge it.

Ending a scratch session asks what to do: Save as ticket, then end (the same hand-off, then the end), Just end, or Cancel. If the session changed files, the dialog lists them and Just end becomes Keep changes, end, which leaves them in place, noted in HANDOFF.md. When the checkout was clean at the start, Discard changes, end is offered too.