🏃 baton-pass-netheremp

A low-token handoff workflow for multi-agent repos. When one AI runs out of context, the next one picks up exactly where it left off — no recap, no drift, no duplicated work.

Built for teams running Claude + Codex (or any two agents) on the same repo. Published to npm, the Claude Code plugin marketplace, and the OpenAI plugin directory.

Attribution. This is a derivative of francisN21/baton-pass, used under the MIT License. Changes in this copy:

• Fixed the Claude Code plugin manifest (.claude-plugin/plugin.json) so it installs (commands / skills were not in the schema-required form).
• Moved the plugin skill to skills/baton-pass/SKILL.md so Claude Code registers it.
• Renamed the plugin and marketplace to baton-pass-netheremp.
• Added cross-agent install (baton-pass install) and a .codex-plugin/ manifest so the one skill works on Claude Code and Codex, CLI and app.

See CHANGELOG.md and the original project for full history.

The Move Set

new-game     ──  bootstrap the workflow in a fresh repo
save-state   ──  pause safely, ownership stays with you
baton-pass   ──  transfer when tokens are low or ownership changes
foresight    ──  receive or resume, verify alignment before acting
dragon-dance ──  record a real workflow lesson (conditional, not automatic)
party-check  ──  see who owns the work right now
hindsight    ──  audit the full baton chain — milestones, verifications, risks, open items

Why This Exists

Context windows end. Agents forget. Handoffs fail silently.

The usual result: the next agent restates everything from scratch, misses a decision that was made two sessions ago, or picks up stale assumptions from docs that haven't been updated since Tuesday.

baton-pass fixes that with one core idea — write only the delta, not the recap.

The Three Rules That Matter Most

1. Default to delta, not recap

Do not restate stable project history unless the receiver genuinely cannot continue without it. A good baton is smaller than a project summary.

2. Commit before you hand off

Never transfer a dirty working tree without naming the uncommitted state explicitly. A dirty tree at handoff means the receiver does not know what is real.

3. Be honest about what was verified

Use these exact terms — nothing more, nothing less:

| Term | Meaning | |---|---| | passed | ran locally, output confirmed clean | | passed outside sandbox | ran locally, not in CI/build environment | | not run — [reason] | skipped, state the reason | | expected to pass, unverified | not run, believed correct |

Never write passed when you mean expected to pass, unverified. That single ambiguity causes more handoff rework than anything else.

How Each Move Works

🎮 new-game

Use once, at repo start.

Bootstraps the minimum shared memory so multi-agent work can begin safely.

Creates:

baton-pass.config.json
baton-pass.state.json
docs/agent-handoff.md
docs/current-state.md
docs/next-task.md
docs/progress.md

💾 save-state

Use when you must stop but ownership isn't changing.

Write the minimum needed for future-you to resume:

• current task
• stopped at
• files touched
• next immediate action
• blocker or risk

🏃 baton-pass

Use when tokens are low or the next agent takes over.

Write only:

• goal
• done
• tasks (if mid-plan — list each task with status: done / in-progress / pending)
• files changed
• worktree (branch + path if using git worktrees)
• verified (honest — use the vocabulary above)
• deviations (mid-session decisions that differ from the original plan)
• environment (prerequisites a fresh agent needs: services running, .env vars, test DBs)
• next task
• risks
• next agent

Commit first. If you cannot commit, name the uncommitted state in the baton.

Why tasks, worktree, deviations, and environment? Session memory is lost on handoff. A fresh agent cannot reconstruct which of 21 tasks are done from git log, doesn't know which worktree you were in, will re-read the plan and redo decisions you already made, and will hit the same "service not running" blocker without environment facts. Write these explicitly.

🔮 foresight

Use when receiving a baton or returning after a pause.

Check before you touch anything:

→ current user goal
→ working tree status
→ latest commit(s)
→ current-state
→ next-task
→ latest progress entry
→ files named in the baton

Then:

aligned     →  continue
misaligned  →  correct docs first, then continue
              if the drift reveals a reusable lesson → run dragon-dance

🐉 dragon-dance

Use only when a real workflow lesson appeared.

Good triggers:

• the baton was stale or incomplete
• a verification claim was misleading
• the receiver had to re-audit too much
• the same workflow mistake could repeat

If nothing was learned — skip it entirely. Dragon dance is not a ceremony. It is a repair.

🎉 party-check

Use when you need to know who owns the work right now.

Reads from baton-pass.state.json and the Turn State block in next-task. Cheap. No full audit needed.

🔍 hindsight

Use when you need a full audit of what actually happened across the chain.

Good triggers:

• a milestone is complete and you want a clean record
• something feels wrong and you need to trace the source
• a new agent is joining and needs the full picture, not just the last baton
• a foresight found severe drift and you need to know how far back it started
• the project is being reviewed, handed to a human, or archived

What it produces:

• baton chain table (who passed to whom, when, and why)
• milestones claimed per agent with honest verification status
• verification gaps (claims made without supporting evidence)
• risks carried forward without resolution
• drift that accumulated across batons
• open items that were never closed
• verdict: clean, gaps found, risks unresolved, or action required

Do not run hindsight after every baton. It is an audit, not a routine step.

Turn State

Every next-task file carries a Turn State block at the very top. It's the first thing you read. It tells you who owns the work before you open anything else.

## Turn State
- State:       handed-off
- Last Move:   baton-pass
- Last Agent:  codex
- Next Agent:  claude
- Updated At:  2026-04-17

baton-pass.state.json mirrors this for programmatic use. When you update one, update both. If they disagree, next-task wins.

Recommended state values:

| State | Meaning | |---|---| | active | someone is working right now | | paused | stopped safely, same agent will resume | | handed-off | transferred, waiting for receiver to claim | | claimed | receiver ran foresight and is continuing | | blocked | cannot proceed — reason is in next-task |

baton-pass status

A mechanical readout from the terminal — no agent needed. Reads baton-pass.state.json, cross-checks it against the next-task Turn State, and shows the recent chain from progress:

$ baton-pass status

Baton Pass — status
────────────────────────────────────────
  state:       handed-off
  last move:   baton-pass
  last agent:  codex
  next agent:  claude
  updated:     2026-09-04
  summary:     CSP + trusted-origin done; deploy next.

Recent chain (progress log)
────────────────────────────────────────
  Session 002    2026-09-04  codex -> claude
                 Add trusted-origin protection and CSP before deploy

baton-pass status --json emits the same data as JSON for scripts and other agents. (The party-check move is the agent-driven version that interprets this.)

Recommended Flows

See examples/multi-agent-chain.md for a full narrated Claude → Codex → Claude chain showing every move in context.

Normal pause/resume:

save-state  →  foresight  →  continue

Low-token transfer:

baton-pass  →  foresight  →  continue

Drift found on receive:

foresight  →  correct docs  →  dragon-dance (if lesson)  →  continue

Ownership check:

party-check

Full chain audit:

hindsight  →  dragon-dance (if gaps or unresolved risks found)

Anti-Patterns

✗  using baton-pass for every tiny checkpoint
✗  running dragon-dance when nothing was learned
✗  running hindsight after every baton — it is an audit, not a routine step
✗  rewriting all memory files for trivial work
✗  turning foresight into a full repo audit every time
✗  writing "passed" when you mean "expected to pass, unverified"
✗  handing off with a dirty tree without naming the uncommitted state
✗  omitting task status when mid-way through a numbered plan
✗  omitting the worktree path when work is inside a git worktree
✗  omitting environment prerequisites that a fresh agent would not know

Install

One command — works on Claude and Codex, CLI and app:

npx github:netheremp/baton-pass-netheremp install

npx runs the tool straight from GitHub: no clone, nothing installed permanently. It copies the baton-pass skill into ~/.claude and every ~/.codex* home and reports what it wrote (existing files are skipped; pass --force to overwrite).

| Surface | What lands | How to invoke | |---|---|---| | Claude Code (CLI + IDE) | skill + /move commands under ~/.claude | skill auto-loads; /new-game … /hindsight | | Codex CLI (every home) | skill under $CODEX_HOME/skills | skill auto-loads; $baton-pass | | Codex desktop app | skill + ~/.codex/prompts/*.md | skill auto-loads; /prompts:baton-pass |

The Codex CLI (0.152–0.153) has no file-prompt loader, so $baton-pass (or letting the skill auto-trigger) is its entry point. The /prompts: menu is a Codex desktop-app feature.

From a clone

git clone https://github.com/netheremp/baton-pass-netheremp
sh baton-pass-netheremp/scripts/install.sh        # Windows: pwsh baton-pass-netheremp/scripts/install.ps1

Flags (pass through either the npx or the script form):

--link                symlink the skill dir instead of copying — `git pull` then updates every surface
--claude | --codex    restrict to one platform (default: both, auto-detected)
--claude-home <dir>   use an explicit Claude home (repeatable)
--codex-home <dir>    use an explicit Codex home (repeatable; $CODEX_HOME is picked up)
--skill-only          skip the slash commands / app prompts, install the skill only
--force               overwrite existing files

Claude Code plugin (per repo)

/plugin marketplace add netheremp/baton-pass-netheremp
/plugin install baton-pass-netheremp@baton-pass-netheremp

From a terminal, or from a local clone:

claude plugin marketplace add https://github.com/netheremp/baton-pass-netheremp
claude plugin marketplace add /path/to/baton-pass-netheremp        # local clone
claude plugin install baton-pass-netheremp@baton-pass-netheremp

Codex plugin / OpenAI marketplace

.codex-plugin/plugin.json makes the workflow installable through Codex /plugins and ready to submit to the OpenAI universal plugin directory (shared by ChatGPT and Codex). For local testing, add this repo as a local marketplace and install from it.

Install Project Files

Use this path when you want to add the shared handoff files and .claude/commands/ into a repo.

npx github:netheremp/baton-pass-netheremp init     # or, from a clone: node ./bin/baton-pass.js init

This installs the shared memory files, Claude Code slash commands, and a .gitignore block for Baton Pass local files into your project.

By default it keeps Baton Pass state local-only so GitHub does not fill up with routine handoff churn. Use --track-state when a team wants the handoff state committed and shared through git.

What gets installed

Shared memory files (created in your repo):

baton-pass.config.json
baton-pass.state.json
docs/agent-handoff.md
docs/current-state.md
docs/next-task.md
docs/progress.md

Claude Code slash commands (in .claude/commands/):

/new-game
/save-state
/baton-pass
/foresight
/dragon-dance
/party-check
/hindsight

Local files ignored by .gitignore:

# Baton Pass local files
.claude/settings.local.json
.npm-cache/
.tmp-*/

# Baton Pass local state
baton-pass.config.json
baton-pass.state.json
docs/

If you run init with --track-state, the local state section is omitted so the shared memory files can be committed.

Each command tells Claude exactly what to do for that move — no copy-pasting instructions.

Options

node ./bin/baton-pass.js install                # user-level: skill for Claude + Codex, CLI + app
node ./bin/baton-pass.js init [target-dir]      # repo: memory files + Claude commands
node ./bin/baton-pass.js init --track-state     # leave state files trackable in git
node ./bin/baton-pass.js status [dir] [--json]  # show Turn State + recent baton chain
node ./bin/baton-pass.js commands [target-dir]  # install only slash commands
node ./bin/baton-pass.js init --force           # overwrite existing files
node ./bin/baton-pass.js help

After init

1. Adjust baton-pass.config.json if your repo uses different file paths.
2. Fill in docs/current-state.md and docs/next-task.md.
3. Review the Baton Pass block in .gitignore; remove the local state lines only if you want git-tracked handoff history.
4. Add repo-specific rules to docs/agent-handoff.md. Keep the portable skill generic — project rules stay local.

Manual install (no CLI)

# Bash
./scripts/new-game.sh

# PowerShell
./scripts/new-game.ps1

Or follow the step-by-step path in INIT.md.

Repository Layout

baton-pass-netheremp/
├── package.json
├── README.md
├── INIT.md
├── LICENSE
├── PRIVACY.md
├── CONTRIBUTING.md
├── CHANGELOG.md
├── .github/workflows/    ← CI (manifests + tests) and tag → npm publish
├── .claude-plugin/
│   ├── plugin.json        ← Claude Code plugin manifest
│   └── marketplace.json   ← single-plugin marketplace pointing at this repo
├── .codex-plugin/
│   ├── plugin.json        ← Codex / OpenAI plugin manifest (points at skills/)
│   └── assets/ · assets/  ← plugin icon + logo
├── bin/
│   └── baton-pass.js      ← install (user-level) + init / status / commands (per-repo)
├── test/
│   └── cli.test.js        ← node --test smoke suite
├── skills/
│   └── baton-pass/
│       └── SKILL.md        ← the skill — single source of truth for Claude + Codex
├── scripts/
│   ├── check-manifests.js ← repo consistency check (run in CI)
│   ├── install.sh         ← wrapper for `baton-pass install`
│   ├── install.ps1
│   ├── new-game.ps1
│   ├── new-game.sh
│   ├── init-baton-pass.ps1
│   └── init-baton-pass.sh
├── commands/
│   ├── new-game.md
│   ├── save-state.md
│   ├── baton-pass.md
│   ├── foresight.md
│   ├── dragon-dance.md
│   ├── party-check.md
│   └── hindsight.md
├── examples/
│   ├── example-baton-pass.md    ← one completed baton
│   └── multi-agent-chain.md     ← a full Claude → Codex → Claude chain, narrated
└── templates/
    ├── agent-handoff.template.md
    ├── baton-pass.config.template.json
    ├── baton-pass.state.template.json
    ├── baton-pass.template.md
    ├── current-state.template.md
    ├── next-task.template.md
    ├── progress-log.template.md
    ├── progress-session.template.md
    ├── save-state.template.md
    ├── foresight.template.md
    ├── dragon-dance.template.md
    ├── party-check.template.md
    └── hindsight.template.md

License

MIT — original work © francisN21, modifications © netheremp. Use it, adapt it, share it.

Privacy

No data collection, no network, no accounts — see PRIVACY.md.