{"_id":"@codeprakhar25/agent-baton","_rev":"6-e0987c5ce1aef2ad35a88af8b1b15d6d","name":"@codeprakhar25/agent-baton","dist-tags":{"latest":"0.3.3"},"versions":{"0.1.0":{"name":"@codeprakhar25/agent-baton","version":"0.1.0","license":"MIT","_id":"@codeprakhar25/agent-baton@0.1.0","maintainers":[{"name":"codeprakhar25","email":"prakharkhatri123@gmail.com"}],"bin":{"baton":"dist/cli.js"},"dist":{"shasum":"4de13035da37e4c1730439e40794ab3f976b3d3c","tarball":"https://registry.npmjs.org/@codeprakhar25/agent-baton/-/agent-baton-0.1.0.tgz","fileCount":4,"integrity":"sha512-RLSo5ll9mPLHHHKGww1hlPUmz2u0jzO14yYPXbdDffxBjsLQKXmIOTs+dCDE01Guo/VzVCXm+eKlGikwu5IjTA==","signatures":[{"sig":"MEUCIFIejLkI1ophbnH/laD+l2Rz+8Vl9VSvVubr3ovOD1JLAiEA6bRY+d/CYwp3LCZ2h3SEgyYdj2wStL0Nhv8ku/0Bxgs=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":321102},"engines":{"node":">=18"},"gitHead":"7d09338ae51a07857d0748eaa2deed9a0ae0602b","scripts":{"dev":"tsup --watch","lint":"tsc --noEmit","build":"tsup","prepublishOnly":"npm run lint && npm run build"},"_npmUser":{"name":"codeprakhar25","email":"prakharkhatri123@gmail.com"},"_npmVersion":"10.9.0","description":"Cross-agent handoff tool: transfer work between Cursor, Claude Code, and Codex when limits are hit","directories":{},"_nodeVersion":"22.12.0","dependencies":{"chalk":"^4.1.2","commander":"^12.1.0","@inquirer/prompts":"^5.5.0"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.3.0","typescript":"^5.6.0","@types/node":"^22.0.0"},"_npmOperationalInternal":{"tmp":"tmp/agent-baton_0.1.0_1778745918329_0.8627251577734423","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"@codeprakhar25/agent-baton","version":"0.2.0","license":"MIT","_id":"@codeprakhar25/agent-baton@0.2.0","maintainers":[{"name":"codeprakhar25","email":"prakharkhatri123@gmail.com"}],"bin":{"baton":"dist/cli.js"},"dist":{"shasum":"7abcd0d96d17726ca1061a4b7053efb08956f477","tarball":"https://registry.npmjs.org/@codeprakhar25/agent-baton/-/agent-baton-0.2.0.tgz","fileCount":4,"integrity":"sha512-APwv7CQEo2Fl6MjYajlAkJr1fvLAVOnjNXbsYc6/EcJwkMKXpY3DA7Oq5WTUX/6m9NXADQVQJ67WkMWfC3eSVg==","signatures":[{"sig":"MEYCIQDvNDZCRAJr0dZ/ZQPkgNqrv857DFdUz1dNxfVCEFqaagIhAMQHddJLqzTyG8Dj+O09UGwU6HffL0yAjJkfFZzztKKB","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":334939},"engines":{"node":">=18"},"gitHead":"791b353f57de7d7b49d825f328a3439bf7b2d05a","scripts":{"dev":"tsup --watch","lint":"tsc --noEmit","build":"tsup","prepublishOnly":"npm run lint && npm run build"},"_npmUser":{"name":"codeprakhar25","email":"prakharkhatri123@gmail.com"},"_npmVersion":"11.14.1","description":"Cross-agent handoff tool: transfer work between Cursor, Claude Code, and Codex when limits are hit","directories":{},"_nodeVersion":"22.12.0","dependencies":{"chalk":"^4.1.2","commander":"^12.1.0","@inquirer/prompts":"^5.5.0"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.3.0","typescript":"^5.6.0","@types/node":"^22.0.0"},"_npmOperationalInternal":{"tmp":"tmp/agent-baton_0.2.0_1778821351516_0.3267450624708126","host":"s3://npm-registry-packages-npm-production"}},"0.3.0":{"name":"@codeprakhar25/agent-baton","version":"0.3.0","license":"MIT","_id":"@codeprakhar25/agent-baton@0.3.0","maintainers":[{"name":"codeprakhar25","email":"prakharkhatri123@gmail.com"}],"bin":{"baton":"dist/cli.js"},"dist":{"shasum":"12ed39a7c9427a06828b351146e458e86955d884","tarball":"https://registry.npmjs.org/@codeprakhar25/agent-baton/-/agent-baton-0.3.0.tgz","fileCount":4,"integrity":"sha512-30J4HhO3sqAkSWGjRKZE7mY6lOxFTFBJ9RrX5DnlYQNFK+gU817Uef0T7iYV2EPMxcHaKzp6GaTmtb+Zvs5OSw==","signatures":[{"sig":"MEYCIQD7YPXIag8AGlK0ZWYMXqFrOzlcA03SBVkGrsYw9zaHDQIhAKJXSHpF2ya70Cpg1rGSckTCDPupWqTmA+PIKSE1lFOI","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":342549},"engines":{"node":">=18"},"gitHead":"b74b42c13582cb77c40b1a658cbf6086a700a92b","scripts":{"dev":"tsup --watch","lint":"tsc --noEmit","build":"tsup","prepublishOnly":"npm run lint && npm run build"},"_npmUser":{"name":"codeprakhar25","email":"prakharkhatri123@gmail.com"},"_npmVersion":"11.14.1","description":"Cross-agent handoff tool: transfer work between Cursor, Claude Code, and Codex when limits are hit","directories":{},"_nodeVersion":"22.12.0","dependencies":{"chalk":"^4.1.2","commander":"^12.1.0","@inquirer/prompts":"^5.5.0"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.3.0","typescript":"^5.6.0","@types/node":"^22.0.0"},"_npmOperationalInternal":{"tmp":"tmp/agent-baton_0.3.0_1778850578713_0.8663260129489352","host":"s3://npm-registry-packages-npm-production"}},"0.3.1":{"name":"@codeprakhar25/agent-baton","version":"0.3.1","license":"MIT","_id":"@codeprakhar25/agent-baton@0.3.1","maintainers":[{"name":"codeprakhar25","email":"prakharkhatri123@gmail.com"}],"bin":{"baton":"dist/cli.js"},"dist":{"shasum":"73951b9c6be8861d991eb2221fe0c4148ad03289","tarball":"https://registry.npmjs.org/@codeprakhar25/agent-baton/-/agent-baton-0.3.1.tgz","fileCount":4,"integrity":"sha512-QGKPQLXLgBJ+15RRwtfQjHtstYhomTWNGL6dOiPDBFmcaJz+evOeZHZJzwexBYWwpgCFJAkuon4csxQaXnkTDA==","signatures":[{"sig":"MEYCIQChuDNVud49RQ7GGxql2xTHdm9D3I37HVVGV0/epfdd/AIhAKXHi8zSetczDi7eOrRlme5uL7721f0atIi2Aefwt+VS","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":344306},"engines":{"node":">=18"},"gitHead":"253b96936aeebe3e7a7c356565a7f62d1778cdc0","scripts":{"dev":"tsup --watch","lint":"tsc --noEmit","build":"tsup","prepublishOnly":"npm run lint && npm run build"},"_npmUser":{"name":"codeprakhar25","email":"prakharkhatri123@gmail.com"},"_npmVersion":"11.14.1","description":"Cross-agent handoff tool: transfer work between Cursor, Claude Code, and Codex when limits are hit","directories":{},"_nodeVersion":"22.12.0","dependencies":{"chalk":"^4.1.2","commander":"^12.1.0","@inquirer/prompts":"^5.5.0"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.3.0","typescript":"^5.6.0","@types/node":"^22.0.0"},"_npmOperationalInternal":{"tmp":"tmp/agent-baton_0.3.1_1779118704635_0.08148980084037594","host":"s3://npm-registry-packages-npm-production"}},"0.3.2":{"name":"@codeprakhar25/agent-baton","version":"0.3.2","license":"MIT","_id":"@codeprakhar25/agent-baton@0.3.2","maintainers":[{"name":"codeprakhar25","email":"prakharkhatri123@gmail.com"}],"bin":{"baton":"dist/cli.js"},"dist":{"shasum":"afe3f44b98ec995d0137267b13c2c449dd7e9236","tarball":"https://registry.npmjs.org/@codeprakhar25/agent-baton/-/agent-baton-0.3.2.tgz","fileCount":4,"integrity":"sha512-yZM3iwjmK8ZN2t5wmG645uLwlfnDyNWemztI2W/szuHvrWYwHk35zrp09bYIdUkSw7lw1OXtaP4BZNSnQ/3CzA==","signatures":[{"sig":"MEYCIQCSYYruM6TENwvQqYipOHCxMGyqbFYEz0lsemtpYLAB4QIhAP4mE76q3qgeK/jrywivmptM4MRDEssLZUhY8Z2Jugh8","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":333248},"engines":{"node":">=18"},"gitHead":"847fca9aebcc541d283753fefdd71fa7bd645580","scripts":{"dev":"tsup --watch","lint":"tsc --noEmit","build":"tsup","prepublishOnly":"npm run lint && npm run build"},"_npmUser":{"name":"codeprakhar25","email":"prakharkhatri123@gmail.com"},"_npmVersion":"10.8.2","description":"Cross-agent handoff tool: transfer work between Cursor, Claude Code, and Codex when limits are hit","directories":{},"_nodeVersion":"18.20.8","dependencies":{"chalk":"^4.1.2","commander":"^12.1.0","@inquirer/prompts":"^5.5.0"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.3.0","typescript":"^5.6.0","@types/node":"^22.0.0"},"_npmOperationalInternal":{"tmp":"tmp/agent-baton_0.3.2_1779264009915_0.08173847844992088","host":"s3://npm-registry-packages-npm-production"}},"0.3.3":{"name":"@codeprakhar25/agent-baton","version":"0.3.3","description":"Cross-agent handoff tool: transfer work between Cursor, Claude Code, and Codex when limits are hit","bin":{"baton":"dist/cli.js"},"scripts":{"build":"tsup","dev":"tsup --watch","lint":"tsc --noEmit","prepublishOnly":"npm run lint && npm run build"},"dependencies":{"@inquirer/prompts":"^5.5.0","chalk":"^4.1.2","commander":"^12.1.0"},"devDependencies":{"@types/node":"^22.0.0","tsup":"^8.3.0","typescript":"^5.6.0"},"engines":{"node":">=18"},"license":"MIT","gitHead":"d21e22d29e1bd3b22108be80e2bd57e398efb38b","_id":"@codeprakhar25/agent-baton@0.3.3","_nodeVersion":"22.12.0","_npmVersion":"11.14.1","dist":{"integrity":"sha512-YrnbpNJ394LsK0pRX1XB5lvoDmP+CbRaxMlRnMDzn0VlyPQJdrhV+vLciKDT2EciovBnnMKadlx0qwLTAR6ouQ==","shasum":"010ecbdd3d43006bd5d7f5c6e858855b67b615be","tarball":"https://registry.npmjs.org/@codeprakhar25/agent-baton/-/agent-baton-0.3.3.tgz","fileCount":4,"unpackedSize":332988,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQD9v+g0819OQskxOvdr5DrCDSsDbo1pjhrxM57ApCTPkgIgHypRrzhBarHNqIgTrCqzx9dDcYz4TIpUrDc0RuwLN2I="}]},"_npmUser":{"name":"codeprakhar25","email":"prakharkhatri123@gmail.com"},"directories":{},"maintainers":[{"name":"codeprakhar25","email":"prakharkhatri123@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/agent-baton_0.3.3_1780040130869_0.6051484641508693"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-14T08:05:18.209Z","modified":"2026-05-29T07:35:31.109Z","0.1.0":"2026-05-14T08:05:18.473Z","0.2.0":"2026-05-15T05:02:31.666Z","0.3.0":"2026-05-15T13:09:38.875Z","0.3.1":"2026-05-18T15:38:24.781Z","0.3.2":"2026-05-20T08:00:10.086Z","0.3.3":"2026-05-29T07:35:30.997Z"},"license":"MIT","description":"Cross-agent handoff tool: transfer work between Cursor, Claude Code, and Codex when limits are hit","maintainers":[{"name":"codeprakhar25","email":"prakharkhatri123@gmail.com"}],"readme":"\n\n# agent-baton\n\n**Don't lose your work when an AI coding agent hits its quota.**\n\n`baton` monitors usage for Claude Code and Codex, warns you before the threshold, and writes a rich Markdown handoff — with git evidence — so the next agent picks up exactly where you left off.\n\n[](https://www.npmjs.com/package/@codeprakhar25/agent-baton)\n[](https://www.npmjs.com/package/@codeprakhar25/agent-baton)\n[](LICENSE)\n[](package.json)\n[](https://github.com/codeprakhar25/agent-baton)\n[](https://github.com/codeprakhar25/agent-baton)\n[](https://github.com/codeprakhar25/agent-baton)\n[](https://github.com/codeprakhar25/agent-baton/pulls)\n\n[](https://asciinema.org/a/Nob8XwkccZdEc5Gl)\n\n
\n\n---\n\n## The problem\n\nYou're deep in a task — three files modified, a bug half-fixed. Claude or Codex hits its hourly usage limit. You either:\n\n- Lose context and start explaining from scratch in a new session.\n- Manually copy-paste diffs and notes into the next agent.\n\nBaton fixes that. It intercepts at the threshold, gives you a choice, and writes a structured handoff that the next agent can read cold.\n\n---\n\n## Table of Contents\n\n- [Install](#install)\n- [Quick Start](#quick-start)\n- [How It Works](#how-it-works)\n- [Supported Agents](#supported-agents)\n- [Commands](#commands)\n- [Configuration](#configuration)\n- [Troubleshooting](#troubleshooting)\n- [Current Limits](#current-limits)\n\n---\n\n## Install\n\n```bash\nnpm install -g @codeprakhar25/agent-baton\n```\n\n**Requirements:** Node.js 18+\n\n---\n\n## Quick Start\n\n```bash\n# 1. Initialize once per project\ncd ~/your-project\nbaton init\n\n# 2. Work normally — baton hooks into Claude automatically\n# For Codex, use the baton wrapper\nbaton codex \"continue the auth refactor\"\n\n# 3. When baton warns you, choose: continue or hand off\n# Then pick up in the next agent\nbaton pickup --to codex\n```\n\nEvery handoff is written to `~/.local/state/agent-baton/projects//handoffs/` and never touches your repo.\n\n---\n\n## How It Works\n\nBaton has two integration paths:\n\n**Claude Code** — `baton init` installs global hooks into `~/.claude/settings.json`. On `SessionStart`, `UserPromptSubmit`, and `PreToolUse`, `baton guard` reads cached usage with a three-tier TTL:\n\n| Usage range | Cache TTL |\n|-------------|-----------|\n| Below 50% | 15 min |\n| 50% → warning band | 5 min |\n| Warning band → limit | none (always fresh) |\n\nWithin a Claude session, Baton asks at most once in the warning band and once at the hard threshold. If you choose to continue in Claude, later prompt-submit and tool hooks stay quiet until the next Claude session resets the notification state.\n\n**Codex** — `baton codex` wraps the `codex` binary. Usage is checked before launch. If you're over the threshold, Baton asks whether to continue, write a handoff, or run `baton pickup`.\n\n```\nbaton guard / baton codex\n │\n ▼\n fetch usage (cached)\n │\n over threshold?\n ┌────┴────┐\n no yes\n │ │\n allow ask user\n work │ │\n continue handoff\n │\n agent writes Markdown\n + Baton appends git evidence\n │\n write HANDOFF-latest.md\n │\n baton pickup --to \n```\n\n### Handoff format\n\nEach handoff is a Markdown file with:\n\n- Agent-authored task summary, progress, decisions, remaining work, and next step\n- Baton metadata and source handoff path\n- Git branch, status, diff stat, and last commits\n- Full uncommitted diff appended as evidence (truncated at `handoff_extraction.max_diff_chars`)\n- Instructions for the next agent\n\nGit state is the durable source of truth — if transcript extraction is incomplete, the diff tells the full story.\n\n```\n~/.local/state/agent-baton/projects/-/\n handoffs/\n HANDOFF-latest.md ← always the most recent\n HANDOFF-.md ← timestamped copy\n usage-cache.json\n pending-transfer.json\n```\n\n---\n\n## Supported Agents\n\n| Agent | Integration | Detection |\n|-------|-------------|-----------|\n| **Claude Code** | `SessionStart`, `UserPromptSubmit`, `PreToolUse` hooks | OAuth token → Claude usage API |\n| **Codex** | `baton codex` wrapper | `~/.codex/sessions/**/rollout-*.jsonl` `token_count.rate_limits` events |\n| **Cursor** | Transcript fallback | Hard-limit error text in transcripts |\n| **Gemini CLI** | Transcript fallback | Hard-limit error text in transcripts |\n\nClaude and Codex have proactive detection — Baton knows you're near the limit before it's hit. Cursor and Gemini rely on hard-limit text appearing in transcripts.\n\n---\n\n## Commands\n\n| Command | Description |\n|---------|-------------|\n| `baton init` | Install global config and Claude hooks for the current project |\n| `baton usage --from ` | Print current usage-limit status |\n| `baton guard --from claude --hook` | Claude hook driver (called automatically) |\n| `baton codex [-- ] [prompt]` | Launch Codex with usage preflight |\n| `baton handoff --from ` | Manually capture task state and write a handoff |\n| `baton handoff --from --file ` | Register a Markdown handoff written by the agent |\n| `baton pickup [--to ]` | Launch next agent with the handoff |\n\n```bash\n# Check usage\nbaton usage --from claude\nbaton usage --from claude --json # machine-readable\nbaton usage --from claude --refresh # skip cache\n\n# Codex wrapper\nbaton codex # bare launch with preflight\nbaton codex \"finish the login flow\" # with initial prompt\nbaton codex -- --model o4-mini # pass codex flags\n\n# Handoff\nbaton handoff --from codex\nbaton handoff --from claude --reason rate-limit\nbaton handoff --from claude --reason rate-limit --file /tmp/baton-handoff.md\nbaton handoff --from claude --launch # write + immediately run pickup\n\n# Pickup\nbaton pickup # choose agent interactively\nbaton pickup --to claude\nbaton pickup --to codex\n```\n\n---\n\n## Configuration\n\nGlobal config lives at `~/.config/agent-baton/config.json`. Per-project overrides (never committed) at `.baton/config.json`. `baton init` adds `.baton/` to `.gitignore` automatically.\n\n```json\n{\n \"agents\": {\n \"cursor\": { \"enabled\": true, \"priority\": 1 },\n \"claude\": { \"enabled\": true, \"priority\": 2 },\n \"codex\": { \"enabled\": true, \"priority\": 3 },\n \"gemini\": { \"enabled\": true, \"priority\": 4 }\n },\n \"limits\": {\n \"mode\": \"ask\",\n \"handoff_percent\": 95,\n \"warning_buffer_percent\": 5,\n \"auto_handoff_on_hard_limit\": true,\n \"windows\": {\n \"claude\": {\n \"five_hour\": { \"enabled\": true, \"handoff_percent\": 95 },\n \"weekly\": { \"enabled\": true, \"handoff_percent\": 98 },\n \"extra\": { \"enabled\": true, \"handoff_percent\": 95 }\n },\n \"codex\": {\n \"five_hour\": { \"enabled\": true, \"handoff_percent\": 95 },\n \"weekly\": { \"enabled\": true, \"handoff_percent\": 95 },\n \"unknown\": { \"enabled\": true, \"handoff_percent\": 95 }\n }\n }\n },\n \"usage_cache\": {\n \"safe_ttl_ms\": 900000,\n \"approach_percent\": 50,\n \"approach_ttl_ms\": 300000,\n \"near_limit_ttl_ms\": 0,\n \"near_limit_percent\": 75,\n \"pretool_ttl_ms\": 60000,\n \"notify_cooldown_ms\": 900000\n },\n \"usage_sources\": {\n \"claude\": {\n \"oauth_credentials_path\": \"~/.claude/.credentials.json\"\n }\n },\n \"handoff_extraction\": {\n \"max_transcript_lines\": 100,\n \"include_git_diff\": true,\n \"max_diff_chars\": 8000,\n \"scan_secrets\": true\n }\n}\n```\n\n**Key options:**\n\n| Key | Default | Description |\n|-----|---------|-------------|\n| `limits.mode` | `\"ask\"` | `ask` — prompt before acting; `auto_handoff` — write immediately; `warn_only` — log only |\n| `limits.handoff_percent` | `95` | Hard threshold |\n| `limits.warning_buffer_percent` | `5` | Warning band starts this many points below `handoff_percent` (default: warns at 90%) |\n| `limits.auto_handoff_on_hard_limit` | `true` | Auto-write handoff when hard-limit text appears |\n| `usage_cache.safe_ttl_ms` | `900000` | Cache TTL below `approach_percent` (15 min) |\n| `usage_cache.approach_percent` | `50` | Usage % where 5-min approach TTL kicks in |\n| `usage_cache.approach_ttl_ms` | `300000` | Cache TTL from `approach_percent` to warning band (5 min) |\n| `usage_cache.near_limit_ttl_ms` | `0` | Cache TTL inside warning band; `0` = always fresh |\n| `usage_cache.pretool_ttl_ms` | `60000` | Min interval between fresh API fetches on `PreToolUse` |\n| `usage_cache.notify_cooldown_ms` | `900000` | Legacy setting; Claude prompts are now limited by per-session notification state |\n| `handoff_extraction.max_diff_chars` | `8000` | Per-file diff truncation cap |\n\nEnvironment overrides: `AGENT_BATON_CONFIG_HOME`, `AGENT_BATON_STATE_HOME`, `XDG_CONFIG_HOME`, `XDG_STATE_HOME`.\n\n---\n\n## Troubleshooting\n\n**No Codex usage found**\nStart or continue a Codex session so it emits `token_count.rate_limits` events into its rollout JSONL. Baton reads from `~/.codex/sessions/**/rollout-*.jsonl`.\n\n**Claude usage unavailable**\nEnsure Claude Code is OAuth-authenticated and `~/.claude/.credentials.json` exists. Run `baton usage --from claude --refresh` to force a fresh fetch.\n\n**Pickup says agent missing**\nThe target CLI is not on `PATH`. Install it or check your shell config.\n\n**Hooks not firing**\nRe-run `baton init`. Check that `~/.claude/settings.json` contains Baton guard hooks under `hooks`. Codex hooks live in `~/.codex/hooks.json`.\n\n---\n\n## Current Limits\n\n- Context-window fullness is not monitored — Baton only handles usage-limit signals.\n- Cursor and Gemini CLI have partial support — proactive detection requires hard-limit text to appear in transcripts.\n- There is no automatic agent exit. Baton warns, writes the handoff, then you exit the current agent and run `baton pickup` manually.\n\n---\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n","readmeFilename":"README.md"}