Skip to main content

moai handoff Handoff Records

UPDATED 2026-09-28 3 min read EDIT ON GITHUB ↗

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.

Subcommands

CommandDescription
moai handoff saveSave the paste-ready resume body as a pending record
moai handoff clearRemove the pending record
moai handoff showDisplay 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

bash
moai handoff save --stdin --spec SPEC-AUTH-001 --phase run < resume.txt
FlagDescription
--body <text>Resume body (verbatim 6-block paste-ready)
--stdinRead 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
--ultrathinkRecord the ultrathink directive (for restore guidance)
--ultracodeRecord the ultracode directive (for restore guidance)
--goal <condition>Record the /moai goal condition (for restore guidance)

moai handoff clear

bash
moai handoff clear

Removes the pending handoff record.

moai handoff show

bash
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.

Fail-open guarantee

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.