moai handoff Handoff Records
moai handoff manages the auto-resume handoff pending record. It saves or clears the paste-ready resume body used to continue work across a session boundary (/clear). When handoff.mode: auto is set, the saved record is auto-injected at the next session start. moai handoff show is the harness-neutral re-print path: it prints the record verbatim no matter which harness runs the session. The storage and consumption plumbing is harness-neutral at the code level (REQ-HN-011) — a Codex-spawned process saving a record and a Claude clear-source session consuming it was reproduced LIVE in isolation. Entering a worktree seeds .codex/hooks.json; whether Codex then loads the project-local hooks depends on project trust, and this was not LIVE-verified for the seeded worktree. The Codex adapter maps the SessionStart systemMessage onto additionalContext, appending when context already exists.
When a single SPEC spans multiple sessions, the next session has to reassemble context from scratch if the previous session’s progress is lost, wasting both tokens and time. So this command uses the orchestrator’s 6-block resume body as the medium to carry the previous SPEC step’s preconditions, verifications, and execution commands into the next session. It is what gives manager agents an unbroken re-entry point when driving long epics back-to-back.
| Command | Description |
|---|---|
moai handoff save | Save the paste-ready resume body as a pending record |
moai handoff clear | Remove the pending record |
moai handoff show | Display the pending record without consuming it (falls back to the latest consumed record) |
Both accept the common flag --project-dir <path> (project root, default: current directory).
moai handoff save --stdin --spec SPEC-AUTH-001 --phase run < resume.txt| Flag | Description |
|---|---|
--body <text> | Resume body (verbatim 6-block paste-ready) |
--stdin | Read the body from stdin instead of --body |
--spec <id> | The SPEC id this handoff resumes |
--phase <plan|run|sync> | Phase |
--session <uuid> | saved_by_session uuid (attribution) |
--lang <lang> | conversation_language snapshot |
--ultrathink | Record the ultrathink directive (for restore guidance) |
--ultracode | Record the ultracode directive (for restore guidance) |
--goal <condition> | Record the /moai goal condition (for restore guidance) |
moai handoff clearRemoves the pending handoff record.
moai handoff show [--json]Displays the pending handoff record’s body verbatim without changing its state. When no pending record exists, it falls back to the latest consumed record. --json emits the source, SPEC id, phase, and body as JSON.
Even if the moai CLI is not on PATH or moai handoff save exits non-zero, the orchestrator’s paste-ready output is preserved unchanged. A save failure never blocks handoff emission, and the manual paste path works fully without the save — the save is merely an additive persistence step, not a gate.