GitHub - TStansel/handoff · GitHub
/" data-turbo-transient="true" />
Skip to content
Search or jump to...
Search code, repositories, users, issues, pull requests...
-->
Search
Clear
Search syntax tips
Provide feedback
--><br>We read every piece of feedback, and take your input very seriously.
Include my email address so I can be contacted
Cancel
Submit feedback
Saved searches
Use saved searches to filter your results more quickly
-->
Name
Query
To see all available qualifiers, see our documentation.
Cancel
Create saved search
Sign in
/;ref_cta:Sign up;ref_loc:header logged out"}"<br>Sign up
Appearance settings
Resetting focus
You signed in with another tab or window. Reload to refresh your session.<br>You signed out in another tab or window. Reload to refresh your session.<br>You switched accounts on another tab or window. Reload to refresh your session.
Dismiss alert
{{ message }}
TStansel
handoff
Public
Notifications<br>You must be signed in to change notification settings
Fork
Star
main
BranchesTags
Go to file
CodeOpen more actions menu
Folders and files<br>NameNameLast commit message<br>Last commit date<br>Latest commit
History<br>14 Commits<br>14 Commits
.agent-handoff
.agent-handoff
.github/workflows
.github/workflows
assets
assets
packaging/homebrew
packaging/homebrew
scripts
scripts
src
src
tests
tests
.gitignore
.gitignore
Cargo.lock
Cargo.lock
Cargo.toml
Cargo.toml
LICENSE
LICENSE
README.md
README.md
View all files
Repository files navigation
Handoff
Hit a coding-agent limit mid-refactor?
Handoff lets you hand off local coding context between agents like Codex and Claude Code.
handoff codex claude
It reads recent local session context when available, writes a markdown handoff file, and prints the command to start the next agent. Pass --repo when you also want Git branch, commit, working tree, changed files, and snapshot details included.
No server. No dashboard. No hidden state mutation. Just a local handoff file your next agent can read.
Git is optional for the default handoff flow. If the current directory is not inside a Git repository, Handoff writes relative to the current directory. The --repo flag requires a Git repository.
Demo
# You were working in Codex and want to move to Claude Code<br>handoff codex claude
# Handoff writes:<br># .agent-handoff/latest.md<br># Then start Claude:<br>claude "Read .agent-handoff/latest.md and continue from the next recommended step. Before editing, inspect the listed files."
Reverse direction:
handoff claude codex
codex "Read .agent-handoff/latest.md and continue from the next recommended step. Before editing, inspect the listed files."
Install
For local development:
cargo build<br>cargo run -- --help
After installing the binary on your PATH:
handoff --help
From source:
cargo install --path .
Homebrew tap:
brew tap TStansel/handoff<br>brew install handoff
The Homebrew formula installs prebuilt release binaries from GitHub. It does not build from source and does not install Rust through Homebrew.
The formula template lives at packaging/homebrew/handoff.rb. After tagging a release, copy it into the separate homebrew-handoff tap repository under Formula/handoff.rb and update the binary URLs and SHA-256 values for each published target.
The release workflow publishes binaries for:
aarch64-apple-darwin<br>x86_64-apple-darwin<br>x86_64-unknown-linux-gnu
v0.1.2 is the first release with Intel macOS support.
Commands
handoff pull codex<br>handoff pull claude<br>handoff codex claude<br>handoff claude codex<br>handoff inject claude<br>handoff inject codex
Options:
--repo<br>--include-raw<br>--include-diff<br>--inject<br>--history<br>--output<br>--verbose">--dry-run<br>--session id|path><br>--repo<br>--include-raw<br>--include-diff<br>--inject<br>--history<br>--output path><br>--verbose
By default, Handoff writes only the markdown output file. It does not update CLAUDE.md or AGENTS.md, does not create a history archive, and does not write state.json.
Add --inject if you want Handoff to add a marked pointer block to CLAUDE.md or AGENTS.md:
handoff codex claude --inject
Add --history if you want a timestamped archive copy:
handoff codex claude --history
By default, generated packets omit Git repo details. Add --repo to include repo state:
handoff codex claude --repo
Full diffs are also repo state, so --include-diff requires --repo:
handoff codex claude --repo --include-diff
When a cross-agent handoff completes, Handoff checks Homebrew for an available handoff upgrade if brew is on your PATH. It disables Homebrew auto-update for that check and stays silent unless an upgrade is available. Set HANDOFF_NO_UPDATE_CHECK=1 to skip the check.
Use --session when you want a specific session instead of the latest detected one. It accepts either a file path or a session id:
handoff codex claude --session 019e2966-f348-7252-9169-8a7ef9f580fe<br>handoff codex claude --session...