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