Kanban Mode

Info

For the full overview of Kanban Mode and the Origin-Trail Chain design direction, see Kanban Mode. This page covers the multi-session (lead + companion) operating procedure.

Kanban Mode lets one lead session drive a plan -> run -> verify -> sync chain while four companion sessions join the same run to parallelize the work. Every session in the run — lead or companion — gets the raised Stop-hook block cap so a mid-session goal keeps running past the default consecutive-block ceiling.

The lead seeds the chain; companions do not. Each companion carries a kanban-membership flag (-k) plus a role label (--name <role>-<run-id>) so the dispatcher classifies it correctly and the SessionStart hook announces its membership.

moai cc -k                     # lead on Claude backend
moai cc -k SPEC-AUTH-001       # lead tied to a SPEC
moai glm -k                    # lead on GLM backend

The lead session:

Sets MOAI_KANBAN + MOAI_KANBAN_ID (chain seed). Prints the run id and four companion launch lines at SessionStart. Does NOT set MOAI_KANBAN_LABEL (that is the companion signal).

moai cc -k --name plan-abc123    # plan companion
moai cc -k --name run-abc123     # run companion
moai cc -k --name review-abc123  # review companion
moai cc -k --name sync-abc123    # sync companion
moai glm -k --name run-abc123    # same, on the GLM backend

The <run-id> is the identifier the lead announced at startup; the four roles are plan, run, review, sync.

The companion session:

Sets MOAI_KANBAN_LABEL (membership + role label). Gets the same raised Stop-hook block cap as the lead. Does NOT set MOAI_KANBAN — it does not seed a chain.

moai cc --name mysession         # no -k, no kanban membership
moai cc --name run-abc123        # companion-shape --name but no -k → no-op

Without -k, the launcher is a no-op regardless of --name shape. The --name flag passes through to Claude untouched.

Terminal 1 (lead)          Terminal 2-5 (companions)
─────────────────          ────────────────────────
moai cc -k                 moai cc -k --name plan-<run-id>
                           moai cc -k --name run-<run-id>
                           moai cc -k --name review-<run-id>
                           moai cc -k --name sync-<run-id>

Bootstrap is manual: a session cannot launch another session. The lead SessionStart notice prints the exact four commands to copy, one per new terminal. Substitute moai glm for moai cc on any companion to run it on the GLM backend.

Inter-session communication uses Claude Code’s cross-session messaging (ListAgents / SendMessage). The crossSessionInbound settings field controls whether an inbound message is accepted, held, or refused.

Kanban Mode auto-accepts inbound messages: the launcher writes a transient settings file carrying {"crossSessionInbound": "accept"} and passes it to the backend via --settings. The file is session-private (cleaned up on exit) and does not mutate your persistent settings.

If you pass --settings <file> on the command line, the launcher does NOT inject its own settings file. Verify your file carries:

{
  "crossSessionInbound": "accept"
}

The lead SessionStart notice prints an advisory reminding you to check when the launcher did not inject.

The lead notice announces the run id, the four companion launch lines, the leader socket path, and the inbound-automation status. A companion notice is a single role-less line acknowledging the join. Neither notice prompts; both are informational stdout only.