handoff-cli 0.3.4__tar.gz → 0.3.5__tar.gz

{handoff_cli-0.3.4 → handoff_cli-0.3.5}/.github/workflows/publish.yml

@@ -21,6 +21,11 @@ jobs:
       - name: Build
         run: uv build
 
+      - name: Check long description rendering
+        run: |
+          pip install twine
+          twine check dist/*
+
       - name: Publish to PyPI
         run: uv publish --token ${{ secrets.PYPI }}
 

handoff_cli-0.3.5/Makefile

@@ -0,0 +1,7 @@
+.PHONY: render
+
+render:  ## Preview PyPI long description rendering
+	pip install -q "readme_renderer[md]" 2>/dev/null
+	python -m readme_renderer README.md > /tmp/handoff-pypi-preview.html
+	@echo "✅  /tmp/handoff-pypi-preview.html  ($(shell wc -c < /tmp/handoff-pypi-preview.html | tr -d ' ') bytes)"
+	open /tmp/handoff-pypi-preview.html

handoff_cli-0.3.5/PKG-INFO

@@ -0,0 +1,217 @@
+Metadata-Version: 2.4
+Name: handoff-cli
+Version: 0.3.5
+Summary: Multi coding-agent task dispatcher — a CLI proxy for claude that sends coding tasks to configurable AI backends
+Requires-Python: >=3.9
+Requires-Dist: pyyaml<7,>=6
+Requires-Dist: textual<3,>=2
+Description-Content-Type: text/markdown
+
+<div align="center">
+<img src="https://raw.githubusercontent.com/dazuiba/handoff/main/docs/assets/handoff-hero.jpg" width="100%" alt="hero">
+
+# With **Handoff**, your coding agents can finally work together.
+
+
+| You're in | Hand off to | Why |
+| :-- | :-- | :-- |
+| Claude Code / Codex | **DeepSeek** | It does the simple work fast and cheap; save the expensive quota for decisions |
+| DeepSeek | **Codex / Opus** | Borrow a brain for hard problems, bring the answer back to your session |
+
+No tool-switching, no lost context.
+
+**English** · [简体中文](README.zh-CN.md)
+
+</div>
+
+## Why handoff
+
+If you use more than one coding agent, these will sound familiar:
+
+- 💸 **"Claude / Codex: the $20 plan never lasts. The $100 plan costs too much."**<br>
+  — Just say: *"Give this task to `/handoff-ds`."* DeepSeek does the work fast and cheap. Save your expensive quota for decisions.
+- 🤔 **"DeepSeek is stuck. I want a second opinion from Codex."**<br>
+  — Just say: *"Ask `/handoff-codex` what it thinks."* No new terminal. No re-explaining. The answer comes back to your current session.
+- 🔁 **"`/handoff-ds` finished that task. Now I have a follow-up task for it."**<br>
+  — Just say: *"Resume the last `/handoff-ds` session, then do X."* It just sends one more message in the old conversation — all the old context is still there.
+
+
+**The math is simple:** DeepSeek V4 is as capable as Sonnet, and on [OpenCode Go](https://opencode.ai/go?ref=D5926WCTD8) the same money buys **18× the work**:
+
+| Option | Relative cost for the same work |
+| --- | --- |
+| Claude Sonnet (subscription) | 1× (baseline) |
+| DeepSeek official API | **1/3** |
+| [OpenCode Go](https://opencode.ai/go?ref=D5926WCTD8) (includes DeepSeek V4) | **1/18** |
+
+So: **only pay for the SOTA model** (Opus / GPT-5.5) — use it to plan and review. Everything else goes to DeepSeek. With handoff, **$20 Claude Code (plan + dispatch) + $5 OpenCode Go (execution) ≈ the work of a $200 Claude Code Max.**
+
+## Quick start
+
+> **Before you start:** handoff works inside Claude Code (CLI or desktop app) or Codex. You need at least one of them installed and logged in.
+
+### 1. Install
+
+```bash
+uv tool install handoff-cli
+handoff init        # creates the config, links skill / agent files
+```
+
+Upgrade with `uv tool upgrade handoff-cli`.
+
+### 2. Set your token
+
+The `opus` and `codex` backends reuse your existing Claude Code / Codex logins — zero config. **Only DeepSeek needs a token.**
+
+For DeepSeek, we recommend the [OpenCode Go plan](https://opencode.ai/go?ref=D5926WCTD8) (lowest cost, includes DeepSeek V4). Once you have a key, edit `~/.handoff/config.yaml` and change just the `ANTHROPIC_AUTH_TOKEN` line:
+
+```yaml
+# ~/.handoff/config.yaml — handoff init generates this for you
+backends:
+  deepseek:                          # ← first = default
+    type: claude
+    model: deepseek-v4-flash
+    pro_model: "deepseek-v4-pro[1m]"
+    env:
+      ANTHROPIC_BASE_URL: https://api.deepseek.com/anthropic
+      ANTHROPIC_AUTH_TOKEN: "sk-..."  # ← change this. Local proxy setup: https://github.com/iTzFaisal/oc-cc-proxy
+      ANTHROPIC_MODEL: "{model}"
+
+  opus:                              # local claude login — zero config
+    type: claude
+    ...
+  codex:                             # local codex login — zero config
+    type: codex
+    ...
+```
+
+### 3. Dispatch your first task
+
+Go back to Claude Code and say:
+
+> Make a plan, then hand it to `/handoff-ds`.
+
+The task runs in the background; your session is never blocked. When it finishes, the agent reads the result and reports back.
+
+### 4. Who you can hand work off to
+
+| What you say | From | Hands off to | Best for |
+| --- | --- | --- | --- |
+| `/handoff-ds` | Claude Code | DeepSeek V4 | Execution work: writing code, running tests, refactors, bulk edits |
+| `handoff-ds` (subagent) | Codex | DeepSeek V4 | Same as above — use this when you're inside Codex |
+| `/handoff-codex` | Claude Code | Codex (GPT-5.5) | Heavy reasoning, second opinions, hard bugs |
+| `/handoff-opus` | Claude Code | Claude Opus | Decisions that deserve the top model |
+
+> Codex has no slash commands — from Codex you invoke the subagent of the same name instead: say "have `handoff-ds` execute the task above."
+
+### 5. Watch progress / browse history
+
+Inside Claude Code, expand the background shell and you'll see live progress right there — it renders in the shell view and uses none of your main session's context. To browse history or follow a task on its own, use `handoff list` and `handoff tail` (see the FAQ below).
+
+## FAQ
+
+<details>
+<summary><b>How do I browse the task list or watch a task's progress?</b></summary>
+
+<br>
+
+Dispatching and resuming are the AI's job (`handoff run` / `handoff resume` under the hood). These two commands are for you — browse the list, watch the progress:
+
+<table>
+<tr>
+<td width="50%" valign="top">
+
+**`handoff list` / `handoff ls`** — interactive TUI over your full task history. See the full prompt, live status, and final result; press `G` on a row to reload that conversation and keep chatting.
+
+</td>
+<td width="50%" valign="top">
+
+**`handoff tail <run-id>`** — follow a task's output stream live, like looking over its shoulder.
+
+</td>
+</tr>
+<tr>
+<td valign="top">
+
+<!-- docs/assets/list-tui.jpg — ~480px wide — TUI list + detail view, highlight G/C shortcuts -->
+<img src="https://raw.githubusercontent.com/dazuiba/handoff/main/docs/assets/list-tui.jpg" width="100%" alt="handoff list interactive TUI">
+
+</td>
+<td valign="top">
+
+<!-- docs/assets/tail.jpg — ~480px wide — handoff tail live stream -->
+<img src="https://raw.githubusercontent.com/dazuiba/handoff/main/docs/assets/tail.jpg" width="100%" alt="handoff tail live follow">
+
+</td>
+</tr>
+</table>
+
+</details>
+
+<details>
+<summary><b>Can I dispatch several tasks at once?</b></summary>
+
+<br>
+
+Yes. Have your agent send off several tasks in one message. Each runs on its own and reports back on its own — they never get in each other's way.
+
+<!-- docs/assets/parallel.jpg — ~621px wide — 2–3 background tasks from one message, each with its own RESULT= path -->
+<img src="https://raw.githubusercontent.com/dazuiba/handoff/main/docs/assets/parallel.jpg" width="621" alt="Parallel dispatch">
+
+</details>
+
+<details>
+<summary><b>No uv / installing from source?</b></summary>
+
+<br>
+
+`pipx install handoff-cli` or `pip install handoff-cli` work just as well. From source:
+
+```bash
+git clone https://github.com/dazuiba/handoff && cd handoff
+uv tool install -e .
+handoff init
+```
+
+</details>
+
+<details>
+<summary><b>How do I add a custom backend / what goes in the env block?</b></summary>
+
+<br>
+
+Add one more entry under `backends` — any Anthropic-compatible endpoint works:
+
+```yaml
+backends:
+  kimi:
+    type: claude
+    model: kimi-k3
+    env:
+      ANTHROPIC_BASE_URL: https://api.moonshot.cn/anthropic
+      ANTHROPIC_AUTH_TOKEN: "${MOONSHOT_API_KEY}"
+      ANTHROPIC_MODEL: "{model}"
+```
+
+The env block is entirely yours — every key=value you set is exported before the CLI launches. `{model}` substitutes the resolved model name, `${ENV_VAR}` expands from your shell. Run `handoff env` to see where everything lives. Full details: **[configuration docs (Chinese) →](docs/configuration.zh-CN.md)**.
+
+</details>
+
+<details>
+<summary><b>How does it actually work?</b></summary>
+
+<br>
+
+1. Your agent hands the whole task to handoff, which runs it **in the background** — your session never blocks.
+2. handoff launches the matching CLI (`claude -p` / `codex exec`) in an isolated context and streams the full output to disk.
+3. The main session receives exactly one line: `RESULT=<path-to-result-file>`. Progress goes to the background shell view — **never** into your main context.
+4. On completion the agent gets notified, reads the result file, and reports back to you.
+5. The `RESULT=` path is also a stable handle for the conversation: every follow-up round resumes the same session.
+
+</details>
+
+**More docs**
+
+- **[CLI reference (Chinese) →](docs/cli-reference.zh-CN.md)** — full usage of `run` / `resume` / `list` / `tail` / `env` / `init`, run-id encoding, on-disk file layout.
+- **[Configuration (Chinese) →](docs/configuration.zh-CN.md)** — mechanism vs data layers, env block, `${ENV}` interpolation, include, custom backends.
+- **[Design notes (Chinese) →](docs/design.zh-CN.md)** — why Claude Code uses background shells while Codex uses a subagent; the RESULT= protocol.

{handoff_cli-0.3.4 → handoff_cli-0.3.5}/README.md

@@ -1,12 +1,12 @@
 <div align="center">
-<img src="docs/assets/handoff-hero.jpg" width="100%" alt="hero">
+<img src="https://raw.githubusercontent.com/dazuiba/handoff/main/docs/assets/handoff-hero.jpg" width="100%" alt="hero">
 
 # With **Handoff**, your coding agents can finally work together.
 
 
-| coding agent | → Hand off to | Why |
+| You're in | Hand off to | Why |
 | :-- | :-- | :-- |
-| Claude Code / Codex | **DeepSeek** | Execution work is fast and cheap; save the expensive quota for decisions |
+| Claude Code / Codex | **DeepSeek** | It does the simple work fast and cheap; save the expensive quota for decisions |
 | DeepSeek | **Codex / Opus** | Borrow a brain for hard problems, bring the answer back to your session |
 
 No tool-switching, no lost context.
@@ -23,23 +23,24 @@ If you use more than one coding agent, these will sound familiar:
   — Just say: *"Give this task to `/handoff-ds`."* DeepSeek does the work fast and cheap. Save your expensive quota for decisions.
 - 🤔 **"DeepSeek is stuck. I want a second opinion from Codex."**<br>
   — Just say: *"Ask `/handoff-codex` what it thinks."* No new terminal. No re-explaining. The answer comes back to your current session.
-- 🔁 **"I want to continue that task from before."**<br>
-  — Just say: *"Resume that `/handoff-ds` session."* Everything is still there: the files it changed, the code it read, what it concluded.
-- 🔄 **"A new model means a new session. I have to explain everything again."**<br>
-  — Don't switch. Stay in your session. handoff passes the task over, then brings the result back.
+- 🔁 **"`/handoff-ds` finished that task. Now I have a follow-up task for it."**<br>
+  — Just say: *"Resume the last `/handoff-ds` session, then do X."* It just sends one more message in the old conversation — all the old context is still there.
 
-**Do the math:** for transactional work — writing code, running tests — DeepSeek V4 matches Sonnet-class models at a fraction of the price. What is really scarce, and worth a subscription, is the judgment of the one or two models at the very top (Opus / GPT-5.5).
+
+**The math is simple:** DeepSeek V4 is as capable as Sonnet, and on [OpenCode Go](https://opencode.ai/go?ref=D5926WCTD8) the same money buys **18× the work**:
 
 | Option | Relative cost for the same work |
 | --- | --- |
-| Claude Sonnet | 1× (baseline) |
+| Claude Sonnet (subscription) | 1× (baseline) |
 | DeepSeek official API | **1/3** |
 | [OpenCode Go](https://opencode.ai/go?ref=D5926WCTD8) (includes DeepSeek V4) | **1/18** |
 
-Let the top model talk to you, split the work, and review; hand all execution off — **a $20 subscription directing $5 of compute gets you ~$200 worth of work.** That's all there is to it: one sentence inside your agent session.
+So: **only pay for the SOTA model** (Opus / GPT-5.5) — use it to plan and review. Everything else goes to DeepSeek. With handoff, **$20 Claude Code (plan + dispatch) + $5 OpenCode Go (execution) ≈ the work of a $200 Claude Code Max.**
 
 ## Quick start
 
+> **Before you start:** handoff works inside Claude Code (CLI or desktop app) or Codex. You need at least one of them installed and logged in.
+
 ### 1. Install
 
 ```bash
@@ -51,9 +52,9 @@ Upgrade with `uv tool upgrade handoff-cli`.
 
 ### 2. Set your token
 
-opus / codex reuse your local claude / codex logins — zero config. **Only DeepSeek needs a token.**
+The `opus` and `codex` backends reuse your existing Claude Code / Codex logins — zero config. **Only DeepSeek needs a token.**
 
-For DeepSeek compute we recommend the [OpenCode Go plan](https://opencode.ai/go?ref=D5926WCTD8) (lowest cost, includes DeepSeek V4). Once you have a key, edit `~/.handoff/config.yaml` and change just the `ANTHROPIC_AUTH_TOKEN` line:
+For DeepSeek, we recommend the [OpenCode Go plan](https://opencode.ai/go?ref=D5926WCTD8) (lowest cost, includes DeepSeek V4). Once you have a key, edit `~/.handoff/config.yaml` and change just the `ANTHROPIC_AUTH_TOKEN` line:
 
 ```yaml
 # ~/.handoff/config.yaml — handoff init generates this for you
@@ -92,11 +93,11 @@ The task runs in the background; your session is never blocked. When it finishes
 | `/handoff-codex` | Claude Code | Codex (GPT-5.5) | Heavy reasoning, second opinions, hard bugs |
 | `/handoff-opus` | Claude Code | Claude Opus | Decisions that deserve the top model |
 
-> Codex has no slash commands, so that row is the subagent of the same name — say "have `handoff-ds` execute the task above."
+> Codex has no slash commands — from Codex you invoke the subagent of the same name instead: say "have `handoff-ds` execute the task above."
 
 ### 5. Watch progress / browse history
 
-Inside Claude Code, expand the background shell and the live progress is right there — it renders in the shell view and uses none of your main session's context. To browse history or follow a task on its own, use `handoff list` and `handoff tail` (see the FAQ below).
+Inside Claude Code, expand the background shell and you'll see live progress right there — it renders in the shell view and uses none of your main session's context. To browse history or follow a task on its own, use `handoff list` and `handoff tail` (see the FAQ below).
 
 ## FAQ
 
@@ -124,13 +125,13 @@ Dispatching and resuming are the AI's job (`handoff run` / `handoff resume` unde
 <td valign="top">
 
 <!-- docs/assets/list-tui.jpg — ~480px wide — TUI list + detail view, highlight G/C shortcuts -->
-<img src="docs/assets/list-tui.jpg" width="100%" alt="handoff list interactive TUI">
+<img src="https://raw.githubusercontent.com/dazuiba/handoff/main/docs/assets/list-tui.jpg" width="100%" alt="handoff list interactive TUI">
 
 </td>
 <td valign="top">
 
 <!-- docs/assets/tail.jpg — ~480px wide — handoff tail live stream -->
-<img src="docs/assets/tail.jpg" width="100%" alt="handoff tail live follow">
+<img src="https://raw.githubusercontent.com/dazuiba/handoff/main/docs/assets/tail.jpg" width="100%" alt="handoff tail live follow">
 
 </td>
 </tr>
@@ -146,7 +147,7 @@ Dispatching and resuming are the AI's job (`handoff run` / `handoff resume` unde
 Yes. Have your agent send off several tasks in one message. Each runs on its own and reports back on its own — they never get in each other's way.
 
 <!-- docs/assets/parallel.jpg — ~621px wide — 2–3 background tasks from one message, each with its own RESULT= path -->
-<img src="docs/assets/parallel.jpg" width="621" alt="Parallel dispatch">
+<img src="https://raw.githubusercontent.com/dazuiba/handoff/main/docs/assets/parallel.jpg" width="621" alt="Parallel dispatch">
 
 </details>
 

{handoff_cli-0.3.4 → handoff_cli-0.3.5}/README.zh-CN.md

@@ -1,5 +1,5 @@
 <div align="center">
-<img src="docs/assets/handoff-hero.jpg" width="100%" alt="hero">
+<img src="https://raw.githubusercontent.com/dazuiba/handoff/main/docs/assets/handoff-hero.jpg" width="100%" alt="hero">
 
 # 有了 **Handoff**，你手里的几个 coding agent 终于可以互相协作了。
 
@@ -126,13 +126,13 @@ backends:
 <td valign="top">
 
 <!-- docs/assets/list-tui.jpg — 建议 ~480 宽 — TUI 列表 + 详情视图，圈出 G/C 快捷键 -->
-<img src="docs/assets/list-tui.jpg" width="100%" alt="handoff list 交互式 TUI">
+<img src="https://raw.githubusercontent.com/dazuiba/handoff/main/docs/assets/list-tui.jpg" width="100%" alt="handoff list 交互式 TUI">
 
 </td>
 <td valign="top">
 
 <!-- docs/assets/tail.jpg — 建议 ~480 宽 — handoff tail 实时输出流 -->
-<img src="docs/assets/tail.jpg" width="100%" alt="handoff tail 实时跟踪">
+<img src="https://raw.githubusercontent.com/dazuiba/handoff/main/docs/assets/tail.jpg" width="100%" alt="handoff tail 实时跟踪">
 
 </td>
 </tr>
@@ -148,7 +148,7 @@ backends:
 可以。在同一条消息里让 agent 派出多个任务，各自独立执行、独立完成通知，互不干扰。
 
 <!-- docs/assets/parallel.jpg — 建议 621 宽 — 同一条消息派发 2~3 个后台任务，各自拿到不同 RESULT= 路径 -->
-<img src="docs/assets/parallel.jpg" width="621" alt="并行派发多任务">
+<img src="https://raw.githubusercontent.com/dazuiba/handoff/main/docs/assets/parallel.jpg" width="621" alt="并行派发多任务">
 
 </details>
 

{handoff_cli-0.3.4 → handoff_cli-0.3.5}/pyproject.toml

@@ -1,7 +1,8 @@
 [project]
 name = "handoff-cli"
-version = "0.3.4"
+version = "0.3.5"
 description = "Multi coding-agent task dispatcher — a CLI proxy for claude that sends coding tasks to configurable AI backends"
+readme = "README.md"
 requires-python = ">=3.9"
 dependencies = [
     "PyYAML>=6,<7",

handoff_cli-0.3.4/PKG-INFO

@@ -1,7 +0,0 @@
-Metadata-Version: 2.4
-Name: handoff-cli
-Version: 0.3.4
-Summary: Multi coding-agent task dispatcher — a CLI proxy for claude that sends coding tasks to configurable AI backends
-Requires-Python: >=3.9
-Requires-Dist: pyyaml<7,>=6
-Requires-Dist: textual<3,>=2