Card Workers and Shipping

Card Workers and Shipping

Run on a card starts a dedicated, interactive Claude Code worker for that card alone. You can watch it, message it and send it feedback. When it finishes, the card ships itself: Nautelle opens the pull request, watches CI, fixes red checks, and merges when you allow it.

Run

1. Open the card and click Run (or Run again after a failed, ended or stopped round).

2. The launch popover offers the Claude profile and the model. The model is preselected in this order:

   1. your remembered choice for this card;
   2. the recommendation;
   3. the project's model.

   One click with the defaults starts the worker.

3. The runner prepares the card's own git worktree and branch, its own tmux session and an interactive Claude Code session.

4. The worker gets Nautelle's fixed, versioned prompt: the card, branch, base and spec, the project's coding rules, the approved design if there is one, and the instruction to work only in this worktree, commit, run the tests and call finish_card when done.

Every card gets a spec file in its first commit. A bug card also gets a GitHub issue. That issue is never queued for the fleet.

Note

Model recommendation. A small Haiku assessment on the runner suggests opus when the work still has to make decisions, sonnet when it carries out a clear decision, and haiku for trivial edits. It is a default, never a constraint, and Run never waits for it.

Card workers are not fleet slots. They have no brief and no fence, and they do not appear in Fleet. The project's Workers at once setting caps how many run together.

Rounds

Each Run or piece of feedback is a round, with its own run record, so cost, history and budgets count it like any other run. The card's Rounds section lists them.

• Feedback… resumes the same Claude session in the same worktree with your notes. Dragging a Finished card back to In progress is feedback too.
• Stop worker stops the round.
• Open terminal lets an admin attach to the worker's terminal. Every attach is audited.

Message a running session

While a round runs, you can write to the agent without taking over its terminal. This works from the card sheet, the card page, the line under the read-only terminal view, Telegram, and fleet slots on the Fleet page.

• Text sent while the agent is busy is queued by Claude Code and read at its next step. The work is never interrupted.
• When the agent shows a question selector, Nautelle shows its options as buttons plus Other…. A click selects that exact option.
• Messages are text only. Control characters are stripped, the length is capped at 4,000 characters, and every message is audited by its hash, never its text.

Operators and admins can send messages; viewers cannot.

How a card ships

sequenceDiagram
  participant W as Worker
  participant R as Runner
  participant A as Nautelle API
  participant G as GitHub
  W->>W: commit (never pushes)
  R->>G: push head, open draft PR
  W->>A: finish_card
  R->>G: PR ready, description by the worker
  A->>R: read checks
  alt red or conflict (at most 3)
    A->>W: ci_fix round
    W->>W: fix, commit, finish_card
  else no checks after 5 min
    A->>R: retrigger once (close + reopen PR)
  else green
    A->>A: card → Finished
    opt auto-merge on
      A->>R: card.merge at the green head
      R->>G: merge, delete branch
    end
  end

Loading

Draft PR

As soon as the worker's first commit exists, the runner pushes it and opens a draft PR into the base. The worker never pushes. When the worker calls finish_card, the PR leaves draft with the worker's own description: the spec link, what changed and why, and the acceptance checklist. A bug's PR says Closes #<n>.

CI is watched

Nautelle reads the PR's checks through the runner. The card face shows a CI dot next to the PR.

• Red checks or a merge conflict start an automatic ci_fix round in the same session, at most 3 per PR. After that the card shows "CI still failing after 3 fixes" and waits for you.
• No checks on a head, in a project whose card PRs have had checks before: after 5 minutes the runner closes and reopens the PR once to retrigger CI. If checks still do not report, the card goes to Finished unmerged with "CI reported no checks".
• Until the worker is done and CI is green, the card stays in In progress with a badge such as "Checks running" or "Fixing CI (2/3)".

Finished, then merged

A card reaches Finished when the worker is done and CI on its head is green, or the repository has no checks.

• Merge finished cards automatically (Settings › Board) merges the PR at the green head and deletes its branch. The card stays in Finished with a Merged badge. The switch is on by default when the base is not the repository's default branch, and off when it is.
• Auto-merge refuses a round that pushed no new commit, so a PR that holds nothing new is not shipped.
• With the switch off, Accept opens the accept dialog:
  • Merge pull request uses the project's merge method and is bound to the head you saw; if the head moved, the merge is refused. Delete the branch on GitHub is checked by default.
  • Accept without merging leaves the PR open, or closes it and deletes its branch.
  • A merge that is refused stays in the dialog with the reason.

After a merge, the card's issue is closed if it is still open.

Feedback after a merge

A merged card keeps its worktree and session. Feedback starts a new round on a fresh branch made from the updated base, with a new draft PR. The card lists all its PRs.

Completed

Only a person moves a card to Completed. That stops the tmux session and removes the worktree and the local branches. Remote branches are already gone after each merge.

Limits and guarantees

• A drag never starts a worker; a drag into In progress asks first.
• Automation never moves a card to Completed.
• The runner accepts typed commands only, never a shell command from the server.
• A Run can be refused by budget, by the Workers at once limit, by a missing runtime profile, or by an unapproved stack design. The reason is always shown.

See also

• How Work Flows · Board and Cards · Design and Stacks · Token Saver · Steward · Context Handoff

Decisions: ADR-0024 · ADR-0029 · ADR-0032 · ADR-0035 · ADR-0043 · ADR-0045 · Spec: #322, #329, #359, #489, #542