{"_id":"@atakanturgut/agent-handoff","name":"@atakanturgut/agent-handoff","dist-tags":{"beta":"0.1.0-beta.0","latest":"0.1.0-beta.0"},"versions":{"0.1.0-beta.0":{"name":"@atakanturgut/agent-handoff","version":"0.1.0-beta.0","description":"Universal handoff protocol and adapter tooling for AI coding agents.","type":"module","bin":{"agent-handoff":"dist/src/cli.js"},"scripts":{"build":"tsc","test":"node --test --import tsx test/*.test.ts","prepare":"npm run build","prepack":"npm run build"},"keywords":["ai","agents","handoff","claude","codex","gemini"],"license":"MIT","engines":{"node":">=20"},"devDependencies":{"@types/node":"^20.14.12","tsx":"^4.16.2","typescript":"^5.5.4"},"repository":{"type":"git","url":"git+https://github.com/atakanturg/agent-handoff.git"},"homepage":"https://github.com/atakanturg/agent-handoff","bugs":{"url":"https://github.com/atakanturg/agent-handoff/issues"},"publishConfig":{"access":"public","tag":"beta"},"_id":"@atakanturgut/agent-handoff@0.1.0-beta.0","gitHead":"1c48138605dfec3167c5e6f332a97531741e46d8","_nodeVersion":"22.22.3","_npmVersion":"10.9.8","dist":{"integrity":"sha512-JmZ/6nSho2QWyynYkvMDZbSRmvHbcBDAwKHJ2pB39OYEswSIe1pkvhecn+Aazk9LIUmSr4tCFJ1tzWIKwu9/TA==","shasum":"ecceefc80553e913f3a4914f7d65c32e76dcf6e7","tarball":"https://registry.npmjs.org/@atakanturgut/agent-handoff/-/agent-handoff-0.1.0-beta.0.tgz","fileCount":89,"unpackedSize":80501,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDYy2Lj/Ng3uDfEw9DG/vQfUI4QRkBhaqvCukzXW1ECawIgLNezPs/MADTP4nDXXrmt2y+wTNH+CcWYcig3MUAUnqI="}]},"_npmUser":{"name":"atakanturgut","email":"atakan.turg@gmail.com"},"directories":{},"maintainers":[{"name":"atakanturgut","email":"atakan.turg@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/agent-handoff_0.1.0-beta.0_1782746916944_0.6591887269280068"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-29T15:28:36.647Z","0.1.0-beta.0":"2026-06-29T15:28:37.093Z","modified":"2026-06-29T15:28:37.309Z"},"maintainers":[{"name":"atakanturgut","email":"atakan.turg@gmail.com"}],"description":"Universal handoff protocol and adapter tooling for AI coding agents.","homepage":"https://github.com/atakanturg/agent-handoff","keywords":["ai","agents","handoff","claude","codex","gemini"],"repository":{"type":"git","url":"git+https://github.com/atakanturg/agent-handoff.git"},"bugs":{"url":"https://github.com/atakanturg/agent-handoff/issues"},"license":"MIT","readme":"# agent-handoff\n\n`agent-handoff` is an open-source that automatically makes it so that when a coding agent is near their quote they create a handoff.md allowing you to seamlessly move between tools (like claude code, codex, antigravity, etc.)\n\nIt is built as a universal handoff protocol plus agent-specific adapters. The protocol is `handoff.md`, `.handoff-needed`, and `.agent-handoff/state.json`. Only context-usage detection is agent-specific.\n\nRelease: `0.1.0-beta.0`. Ready for dogfooding and feedback, not yet production-hardened across every agent and platform.\n\n## What Problem This Solves\n\nAI coding agents can run out of useful context mid-task. A clean handoff lets the current agent stop, write down exact repo state and next steps, and let Codex, Claude Code, Gemini CLI, Cursor agents, Aider, or a generic agent resume safely.\n\n## Protocol vs Adapters\n\n- Universal protocol: `handoff.md`, `.handoff-needed`, `.agent-handoff/state.json`, and `agent-handoff validate`.\n- Claude Code adapter: v1 trigger adapter using status-line and hook surfaces.\n- Codex adapter: v1 consumer prompt for resuming from `handoff.md`.\n- Gemini adapter: v1 consumer prompt for resuming from `handoff.md`.\n- Generic/manual adapter: `agent-handoff mark` works anywhere.\n\nV1 uses Claude Code status-line integration because it is an explicit supported surface for current context data. It does not use hidden Claude CLI behavior, `/usage` polling, transcript JSONL scraping, a daemon, or paid API calls.\n\n## Install\n\n```bash\nnpm install -g .\n```\n\nAfter publishing:\n\n```bash\nnpm install -g @atakanturgut/agent-handoff\n```\n\nThe npm package is scoped because the unscoped `agent-handoff` name is already taken. The installed CLI command is still `agent-handoff`.\n\n## Claude Code Setup\n\n```bash\nagent-handoff install claude-code --threshold 90 --mode warn --yes\n```\n\nThis writes `~/.claude/agent-handoff/statusline-handoff-watch.sh`, `~/.claude/agent-handoff/handoff-required-hook.sh`, and `~/.claude/commands/handoff.md`.\n\nIt updates `~/.claude/settings.json`, creates a timestamped backup first, preserves unrelated settings, and refuses to replace an existing non-agent-handoff `statusLine` unless `--force` is passed.\n\nModes:\n\n- `marker`: create marker/state and allow continuation.\n- `warn`: warn when `.handoff-needed` exists.\n- `block`: block with instructions until the agent writes `handoff.md`.\n\n## Project Setup\n\n```bash\nagent-handoff init-project --yes\n```\n\nThis creates or updates `CLAUDE.md` with one delimited block. Repeated runs update the block instead of duplicating it.\n\n## Manual Usage For Any Agent\n\n```bash\nagent-handoff mark\n```\n\nThis creates `.handoff-needed` and `.agent-handoff/state.json`. Any agent instructed by the project prompt can see the marker, stop normal work, write `handoff.md`, remove the marker, and tell the user the handoff is ready.\n\n## Codex Continuation\n\n```bash\nagent-handoff print-prompt codex\n```\n\nPaste the printed prompt into Codex. It tells Codex to read `handoff.md`, inspect the real repo state first, verify assumptions, and continue from the listed next steps.\n\n## Gemini Continuation\n\n```bash\nagent-handoff print-prompt gemini\n```\n\nPaste the printed prompt into Gemini CLI or another Gemini-based coding agent.\n\n## Validation\n\n```bash\nagent-handoff validate handoff.md\n```\n\nValidation fails when required sections are missing. It warns when files, commands, next steps, next-agent prompt, blockers, Do Not Do, or verification evidence are weak or missing.\n\n## Status\n\n```bash\nagent-handoff status\n```\n\nShows installed adapters, marker state, Claude threshold/mode where detectable, and whether `handoff.md` exists.\n\n## Uninstall\n\n```bash\nagent-handoff uninstall claude-code --yes\n```\n\nUninstall removes only files and settings owned by `agent-handoff`. It backs up settings before mutation and preserves unrelated Claude settings.\n\n## Limitations\n\n- V1 automatic context triggers are adapter-specific.\n- Claude Code is the only v1 trigger adapter.\n- Codex and Gemini are consumer adapters in v1.\n- No GUI.\n- No cloud service.\n- No automatic semantic summarization.\n- No hidden Claude CLI or `/usage` polling.\n- No transcript scraping.\n\n## Non-Goals For V1\n\n- Hidden Claude CLI.\n- `/usage` polling.\n- Parsing Claude transcript JSONL.\n- Automatic summary via paid LLM call.\n- Supporting every agent's context telemetry.\n- GUI.\n- Cloud service.\n","readmeFilename":"README.md","_rev":"1-e0a06e63137da710985418a94634b493"}