tapout

Your coding agent tapped out? Tag in the next one.

Hit your Claude Code limit mid-task — tap codex and it picks up exactly where you left off. Same task, same plan, same progress. No re-explaining.

Install

pip install tapout

Installs two equivalent console commands, tap and tapout. Python 3.10+.

How it works

1. tap out — prints a summarization prompt (also copied to your clipboard). Paste it into your current agent; it replies with a task-state JSON block.
2. tap out --from <file> — ingests that reply and writes two artifacts: HANDOFF.md (human/agent readable) and .tapout/task-state.json (schema, git-friendly).
3. tap <agent> — opens the target agent in the repo, seeded with the handoff. Works for claude, codex, gemini, cursor, and any agent you add yourself.

Run tap scan to see which agents are installed on this machine.

Zero-effort capture (Claude Code plugin)

Install the bundled Claude Code plugin so capture happens automatically — no manual tap out:

git clone https://github.com/MIthunvasanth/tapout.git
cd tapout
claude plugin marketplace add ./
claude plugin install tapout@tapout

• PreCompact + SessionEnd hooks refresh HANDOFF.md + .tapout/task-state.json automatically before Claude compacts context or the session ends. After you /exit, the handoff is already written — just tap codex.
  • This first pass is a fast, no-LLM heuristic (instant, survives session teardown). Seconds later, a detached background process refines it into a real LLM summary — tap refine runs in the background automatically; opt out per-machine with ~/.tapout/config.toml:

    refine_on_capture = false
    

    If claude isn't on PATH, refinement is skipped silently and the heuristic handoff stands. Run tap refine --transcript <path> --repo <path> yourself anytime to re-refine a stale handoff.
• /tapout:pause captures on demand mid-session.
• tap watch shows a live usage line and prints run: tap codex when your 5-hour window is spent. Add the statusline to ~/.claude/settings.json:

  { "statusLine": { "type": "command", "command": "tap statusline", "refreshInterval": 5 } }
  

  tap statusline prints tap: N% and records state that tap watch reads.

Manual capture (CI / scripting fallback)

If you're not using the plugin, capture from a Claude Code session directly. With no --session-transcript, tapout auto-picks the newest session transcript for the current repo:

python -m tapout capture --agent claude   # auto-picks this repo's latest session
tap codex                                  # or tap cursor, tap gemini

Pass --session-transcript <path> to pick a specific transcript. This is the same capture logic the hooks invoke.

Zero-install via uvx

Once published, the hooks (and you) can run tapout without installing it: uvx tapout <command>. The plugin's hook launcher prefers your installed package and falls back to uvx tapout.

Adding your own agent

Agents are data, not code. Drop a ~/.tapout/agents.toml to add or override any agent — no package changes:

[mytool]
display_name = "My Tool"
binaries = ["mytool"]
config_dirs = ["~/.mytool"]
resume_style = "cli_prompt"                 # or clipboard_gui / clipboard_only
launch_template = ["{binary}", "{prompt}"]  # {binary} {prompt} {cwd} substituted
version_probe = { args = ["--version"], timeout_sec = 5 }

Then tap resume mytool (or tap scan to confirm it's detected). User keys win over the bundled registry.

Each entry can also set prompt_delivery: "argv" (default), "stdin" (pipe the prompt to the child — bypasses cmd.exe, the safe default for codex/gemini/claude), "file:<flag>" (write the prompt to a file, pass the path via <flag>), or "clipboard".

Note: Gemini CLI's free tier was deprecated in December 2025 — the registry flags this, and tap scan surfaces the note.

First run in a new folder

The first tap <agent> in a repo may hit the receiving agent's own setup: trust/workspace-approval dialogs, IDE-connect prompts, or a sign-in. That's the target agent, not tapout. Get through those once — subsequent handoffs into that folder go straight to work.

Windows notes

• npm-installed agents ship both an extensionless shim and a real .cmd; tapout resolves the .cmd (PATHEXT-aware) so launches don't fail with WinError 193.
• When an argv-delivery launcher is a .cmd/.bat and the handoff contains shell metacharacters (& | % " ^ < >), tapout will not pass the prompt as a command-line argument (cmd.exe would re-parse it — the "BatBadBut" class of bug). It falls back to clipboard. Agents using stdin or file delivery (codex, gemini, claude) avoid this entirely.
• PowerShell's type may mangle UTF-8; run chcp 65001 first, or open HANDOFF.md in an editor.

Early alpha (0.1.0.dev0). Manual + auto (Claude Code plugin) handoff; usage monitor via tap watch.