# Codex Handoff & Resume Commands (setup prompt)

Paste everything in the block below into Codex. It builds two custom prompts:
`/handoff` (save session state) and `/resume` (pick it back up), plus an AGENTS.md
note so the behavior also triggers on plain language. Works in any project, with no
external tool, vault, or database required.

In Codex, a reusable command is a markdown file in `~/.codex/prompts/` whose filename
becomes the slash command (`handoff.md` → `/handoff`).

---

```
Create two custom prompts for me so I have a "handoff" and "resume" pair in Codex.
They work together. Handoff saves the state of a working session to a file, resume
reads it back and gets us going again. Build them portable and self-contained, with
no dependency on any external tool, vault, database, or service.

In Codex, a reusable command is a markdown file in ~/.codex/prompts/ whose filename
becomes a slash command. Create these two files exactly:

  ~/.codex/prompts/handoff.md
  ~/.codex/prompts/resume.md

Each file's body is the instruction Codex runs when I type /handoff or /resume.
Also append a short "Session handoff" section to the project's AGENTS.md (create
AGENTS.md in the repo root if it doesn't exist) so the same behavior fires when I say
it in plain words, not just via the slash command.

=== FILE 1: ~/.codex/prompts/handoff.md ===

When this runs, do the following:
1. Write a single handoff file to .handoff/latest.md in the repo root (create the
   .handoff/ folder if missing). Also write a timestamped copy to
   .handoff/archive/<YYYY-MM-DD-HHMM>.md so history is preserved. Get the timestamp
   from the system clock with a shell command. Do not guess it.
2. The file must capture everything a fresh session needs to continue with zero
   re-explaining. Use this structure:

   # Handoff <project name> <date/time>
   ## What we were doing
   One short paragraph: the goal of this session.
   ## State right now
   What's done, what's in progress, what's verified vs unverified.
   ## Files touched
   Bullet list of files changed/created this session, each with a one-line note.
   ## Next steps
   Ordered list. The first item is the single most important next action.
   ## Open questions / blockers
   Anything waiting on a decision or an external thing.
   ## How to verify / run
   Exact commands to build, test, or run the project, if relevant.
   ## Notes
   Anything else that mattered but doesn't fit above.

3. Keep it tight and factual, with no filler. Only write what's true and verified. If
   something wasn't tested, say so explicitly.
4. After writing, print the file path and a 3-line summary of what was saved.

=== FILE 2: ~/.codex/prompts/resume.md ===

When this runs, do the following:
1. Read .handoff/latest.md. If it doesn't exist, say so plainly and offer to start
   fresh. Don't guess.
2. If I passed a topic argument and there are multiple archived handoffs, scan
   .handoff/archive/ for the most relevant one and use that instead.
3. Synthesize the handoff into a short orientation brief (max ~10 lines): what we
   were doing, the current state, and the single next action, ending with
   "Ready when you are."
4. Do NOT start doing work automatically. Just orient and wait for my go-ahead,
   unless I clearly told you to continue immediately.

=== AGENTS.md section to append ===

Add a section titled "## Session handoff" that says: when the user says "handoff",
"wrap", "save the session", or "end session", follow the /handoff procedure (write
.handoff/latest.md + a timestamped archive copy). When the user says "resume",
"pick up where we left off", or "where were we", follow the /resume procedure (read
.handoff/latest.md and give a short orientation brief, then wait).

=== Both ===

- Keep the prompts plain and universal so they work in any repo or project type.
- After creating everything, list the two prompt file paths, confirm AGENTS.md was
  updated, and tell me to type /handoff or /resume to use them.
```

---

## Notes

- Commands live in `~/.codex/prompts/handoff.md` and `~/.codex/prompts/resume.md`.
  The filename is the command.
- `AGENTS.md` is the natural-language layer. Codex reads it automatically, so "wrap"
  or "where were we" works even without the slash command.
- The handoff file format is identical to the Claude Code version. A
  `.handoff/latest.md` written by Codex can be read by Claude and vice versa.