Metadata-Version: 2.4
Name: tapout
Version: 0.1.2
Summary: Pass the baton between AI coding agents - hit a limit in Claude Code, resume exactly where you left off in Codex, Gemini, or Cursor.
Project-URL: Homepage, https://github.com/MIthunvasanth/tapout
Project-URL: Repository, https://github.com/MIthunvasanth/tapout
Project-URL: Issues, https://github.com/MIthunvasanth/tapout/issues
Author: Mithun
License-Expression: MIT
Keywords: agents,ai,claude,cli,codex,cursor,gemini,handoff
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Testing
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Requires-Dist: pydantic>=2.0
Requires-Dist: rich>=13.0
Requires-Dist: tomli>=2.0; python_version < '3.11'
Requires-Dist: typer>=0.12
Provides-Extra: clipboard
Requires-Dist: pyperclip>=1.8; extra == 'clipboard'
Provides-Extra: dev
Requires-Dist: pyperclip>=1.8; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Description-Content-Type: text/markdown

# 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

```bash
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`:

```bash
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`:
    ```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`:
  ```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:

```bash
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:

```toml
[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`._
