Session Handoff (handoff-kit)

A project-agnostic Claude Code and Codex plugin that runs a disciplined end-of-session handoff: it distills the session into the project's durable state, keeps a complete detailed forward plan, de-pollutes the live docs and workspace (removing dead-ends so a fresh session never overfits to stale info), and proposes a commit plan — it never mutates git.

It adapts to any repo by auto-detecting the project's state/plan/memory docs (AGENTS.md, CLAUDE.md, a state or decision record, a plan/README, and project-owned memory files) instead of hardcoding paths.

It also gets smarter with use. On each run it reads (and rewrites) a per-project learned profile at .handoff/profile.md — the exact doc paths, job/cleanup conventions, content policy, and project-specific gates it has discovered. The first run creates it; every later run uses it and refines it (adding what's newly true, removing what's stale). Over time the generic handoff converges into a project-tailored one — automatically, no hand-editing. Commit the profile to share that learning with your team.

Invocation

Claude Code:

/handoff            # full handoff
/handoff <area>     # focus on one area

Codex:

Use $handoff-kit:handoff to prepare a handoff

Add optional focus text after the skill mention, for example: focusing on test status.

In Codex, $handoff-kit:handoff is the reliable cross-surface invocation. The Codex app may also show installed skills in the slash command list, and the Codex CLI provides /skills; selecting the Handoff skill there is equivalent. The plugin itself does not define a Claude-style /handoff slash command for Codex.

If Codex shows both Session Handoff [Plugin] and Session Handoff [Skill], choose Session Handoff [Skill]. The plugin row is the installed package; the skill row is the actual handoff workflow.

It is designed for explicit end-of-session use. Codex metadata disables implicit invocation, and the skill instructions tell the agent to run only when the user explicitly asks for a handoff/closeout.

Install it in Claude Code

/plugin marketplace add HateBunnyPlzzz/handoff-plugin
/plugin install handoff-kit@handoff-tools
/reload-plugins

Then use /handoff in any project.

To make the marketplace discoverable for everyone working in a given repo, add this to that repo's .claude/settings.json:

{
  "extraKnownMarketplaces": {
    "handoff-tools": {
      "source": { "source": "github", "repo": "HateBunnyPlzzz/handoff-plugin" },
      "autoUpdate": true
    }
  }
}

With autoUpdate: true, Claude Code refreshes the marketplace at startup and updates installed plugins when a newer version is available. If an update is applied, Claude Code notifies the user to run /reload-plugins.

Install it in Codex

codex plugin marketplace add HateBunnyPlzzz/handoff-plugin --ref main
codex plugin add handoff-kit@handoff-tools

Start a new Codex thread after installation so the $handoff-kit:handoff skill is loaded.

Update

Claude Code:

/plugin update handoff-kit@handoff-tools
/reload-plugins

For automatic Claude Code update nudges, enable auto-update for the handoff-tools marketplace: open /plugin, go to Marketplaces, select handoff-tools, and choose Enable auto-update. Third-party marketplaces are not auto-updated by default, so each user or team config must opt in.

Codex:

codex plugin marketplace upgrade handoff-tools
codex plugin add handoff-kit@handoff-tools

Codex currently exposes manual marketplace refresh commands, not a public auto-update notification setting for third-party plugin marketplaces. Start a new Codex thread after updating so the refreshed skill is loaded.

Local-first by design

The handoff maintains your project's knowledge in the working-tree files — a fresh Claude Code or Codex session reads those directly (orientation docs are loaded or read on demand; state/plan/memory docs are project files), so no commit is needed for continuity. Git is only for durability/sharing across machines or teammates, and is entirely your call.

What it does NOT do

• Never mutates git — no git add / commit / push / tag / branch operations. It may inspect read-only git state and optionally suggest a commit grouping for you to run, and skips even that if the project doesn't use git.
• Never invents a heavy doc structure — if a project has no state surface, it creates one minimal HANDOFF.md and says so.

Layout

handoff-plugin/
├── .agents/plugins/
│   └── marketplace.json    # Codex marketplace (name=handoff-tools)
├── .claude-plugin/
│   └── marketplace.json    # Claude marketplace (name=handoff-tools)
├── plugins/handoff-kit/
│   ├── .claude-plugin/
│   │   └── plugin.json     # Claude plugin manifest
│   ├── .codex-plugin/
│   │   └── plugin.json     # Codex plugin manifest
│   └── skills/handoff/     # the handoff logic
└── README.md