session-handoff plugin
A Claude Code and Codex handoff plugin: a clean session with decisions and tasks kept, or history moved to the other client.
- 67 ★ on the repository
- Last commit
- MIT
Extended access
Why this level
- Plugin hooks supervise `claude` and `codex` process launches and switch sessions.
- Handoff records and migrated history are stored on disk outside the workspace.
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add plugins/session-handoffDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- Plugin hooks supervise `claude` and `codex` process launches and switch sessions.
- Handoff records and migrated history are stored on disk outside the workspace.
This is third-party code. Review the repository files before installing.
What it does
session-handoff creates a handoff record so a new session starts clean yet remembers decisions and unfinished work. In Claude Code the command is `/session-handoff next task`, in Codex `$session-handoff`. The `handoff_create` tool stores an immutable record outside the workspace and `handoff_setup` prints exact setup commands. A second mode moves the supported portable conversation history to the other client: `/session-handoff migrate codex` in Claude Code or `$session-handoff migrate claude` in Codex. Plugin hooks handle automatic session switching for the `claude` and `codex` CLIs, and telemetry turns on only after an explicit "session-handoff telemetry yes". The author reports pilot measurements: 37 of 37 critical facts recovered in Codex, matching native compaction while starting from a fresh session.
Who it is for. Developers in long Claude Code or Codex sessions who want a clean context without losing decisions.
Good fit when
- A session grew long and the next task needs a clean context.
- Work must continue in Codex after Claude Code or vice versa.
- A verifiable record of decisions and open items outside the workspace is needed.
- Automatic session switching should work for the CLI with no manual setup.
Not a fit when
- Sessions run in a desktop app or IDE; supervision covers only `claude` and `codex` processes.
- You need Windows; the plugin is tested on Linux and macOS validation is pending.
- Short tasks where native context compaction is enough.
Example request
/session-handoff next task: run the full pre-release suite.Limitations
It runs on Linux and macOS (tested on Linux, macOS validation pending) with Python 3.10 or newer. The first session installs automatic switching for the client on its own, after which you restart the terminal. Supervision does not cover desktop apps and IDEs. Benchmarks are small: one paired comparison in Claude Code and ten synthetic combinations in Codex, so read the numbers as a pilot. A handoff record is stored on disk outside the workspace, so clean it separately if it held sensitive decisions. Approve the hook trust request in the client before the first run.
How to disable. Remove the plugin with `/plugin uninstall session-handoff@yuzushi` in Claude Code or the equivalent Codex command, and clean saved handoff records outside the workspace separately.
FAQ
How do I install session-handoff?
In Claude Code: `/plugin marketplace add yuzushi-dev/yuzushi-plugins`, then `/plugin install session-handoff@yuzushi`. In Codex: `codex plugin marketplace add yuzushi-dev/yuzushi-plugins` and `codex plugin add session-handoff@yuzushi`.
How do I migrate history to the other client?
Run `/session-handoff migrate codex` in Claude Code or `$session-handoff migrate claude` in Codex.
Is telemetry collected?
Not by default. It turns on only after an explicit "session-handoff telemetry yes"; setup never enables it.
What if the setup notice never appeared?
Ask the agent to show setup commands: the read-only `handoff_setup` tool returns exact commands with no path lookup.
Is there a Hermes edition?
Yes, a separate Hermes Handoff repository for the native Hermes Agent. This repository covers Claude Code and Codex.
Discussion
No questions or reviews yet.
Related
PluginsA Claude Code plugin writes a handoff document while the session's prompt cache is still warm and costs stay low.
A Claude Code plugin that replaces auto-compact: it writes a handoff brief, clears the session and continues from it
Table Skills: project-handoff
Table Skills (project-handoff)
The project-handoff skill saves goals, decisions and the next step to PROJECT_STATE.md for a fresh Codex or Claude Code session
A CLI that hands session context between coding agents: continue a Claude Code session in Codex, Cursor, OpenCode and others.
A Claude Code template: each session checks the last one's notes against git and GitHub, picks the day task and writes a handoff.
claude-history searches and opens past Claude Code, Codex and Pi conversations in the terminal and gives Claude a history skill
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Repository stars | Main difference |
|---|---|---|---|
| session-handoff (this card) | no | 67 | |
| claude-auto-handoff | no | 125 | replaces auto-compact in Claude Code: writes a brief, clears the session and continues; session-handoff adds migration between Claude Code and Codex |
| auto-handoff | no | 106 | writes a handoff document while the prompt cache is warm; session-handoff stores an immutable record outside the workspace |
README in short
The plugin installs from the yuzushi marketplace or through npm. The repository holds a benchmark folder with judge criteria and fixtures for information preservation.