Skip to content
Back to search

handoff

Delegate tasks to DeepSeek right inside your Claude Code / Codex sessions.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/dazuiba--handoff/badge.svg)](/listings/dazuiba--handoff)

HTML

<a href="/listings/dazuiba--handoff"><img src="/api/listings/dazuiba--handoff/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

> **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

uv tool install handoff-cli
handoff init        # creates config and links Claude skills / Codex custom agents
uv tool upgrade handoff-cli   # update to the latest version

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=JC54498ZNF) (lowest cost, includes DeepSeek V4). Once you have a key, edit `~/.handoff/config.yaml` and change just the `ANTHROPIC_AUTH_TOKEN` line:

> ⚠️ **OpenCode Go users**: you need a local proxy to use OpenCode Go with Claude Code. See **[routatic/proxy](https://github.com/routatic/proxy)**.

# ~/.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
      #for opencode-go you have to setup local proxy  
      #see: https://github.com/routatic/proxy
      ANTHROPIC_AUTH_TOKEN: "sk-..."  
      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` (custom agent) | Codex | DeepSeek V4 | Same as above — use this when you're inside Codex | | `/handoff-gemini` / `handoff-gemini` | Claude Code / Codex | Gemini | Execution or investigation delegated to Gemini | | `/handoff-codex` | Claude Code | Codex (GPT-5.5) | Heavy reasoning, second opinions, hard bugs | | `handoff-opus` (custom agent) | Codex | Claude Opus | Decisions that deserve the top model |

> Codex has no slash commands — mention the custom agent by 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).

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 221 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <div align="center">
  2. <img src="https://raw.githubusercontent.com/dazuiba/handoff/main/docs/assets/handoff-hero.jpg" width="100%" alt="hero">
  3. # With **Handoff**, your coding agents can finally work together.
  4. | You're in | Hand off to | Why |
  5. | :-- | :-- | :-- |
  6. | Claude Code / Codex | **DeepSeek** | It does the simple work fast and cheap; save the expensive quota for decisions |
  7. | DeepSeek | **Codex / Opus** | Borrow a brain for hard problems, bring the answer back to your session |
  8. No tool-switching, no lost context.
  9. **English** · [简体中文](README.zh-CN.md)
  10. </div>
  11. ## Why handoff
  12. If you use more than one coding agent, these will sound familiar:
  13. - 💸 **"Claude / Codex: the $20 plan never lasts. The $100 plan costs too much."**<br>
  14. — Just say: *"Give this task to `/handoff-ds`."* DeepSeek does the work fast and cheap. Save your expensive quota for decisions.
  15. - 🤔 **"DeepSeek is stuck. I want a second opinion from Codex."**<br>
  16. — Just say: *"Ask `/handoff-codex` what it thinks."* No new terminal. No re-explaining. The answer comes back to your current session.
  17. - 🔁 **"`/handoff-ds` finished that task. Now I have a follow-up task for it."**<br>
  18. — 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.
  19. **The math is simple:** DeepSeek V4 is as capable as Sonnet, and on [OpenCode Go](https://opencode.ai/go?ref=JC54498ZNF) the same money buys **18× the work**:
  20. | Option | Relative cost for the same work |
  21. | --- | --- |
  22. | Claude Sonnet (subscription) | 1× (baseline) |
  23. | DeepSeek official API | **1/3** |
  24. | [OpenCode Go](https://opencode.ai/go?ref=JC54498ZNF) (includes DeepSeek V4) | **1/18** |
  25. 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.**
  26. ## Quick start
  27. > **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.
  28. ### 1. Install
  29. ```bash
  30. uv tool install handoff-cli
  31. handoff init # creates config and links Claude skills / Codex custom agents
  32. uv tool upgrade handoff-cli # update to the latest version
  33. ```
  34. ### 2. Set your token
  35. The `opus` and `codex` backends reuse your existing Claude Code / Codex logins — zero config. **Only DeepSeek needs a token.**
  36. For DeepSeek, we recommend the [OpenCode Go plan](https://opencode.ai/go?ref=JC54498ZNF) (lowest cost, includes DeepSeek V4). Once you have a key, edit `~/.handoff/config.yaml` and change just the `ANTHROPIC_AUTH_TOKEN` line:
  37. > ⚠️ **OpenCode Go users**: you need a local proxy to use OpenCode Go with Claude Code. See **[routatic/proxy](https://github.com/routatic/proxy)**.
  38. ```yaml
  39. # ~/.handoff/config.yaml — handoff init generates this for you
  40. backends:
  41. deepseek: # ← first = default
  42. type: claude
  43. model: deepseek-v4-flash
  44. pro_model: "deepseek-v4-pro[1m]"
  45. env:
  46. ANTHROPIC_BASE_URL: https://api.deepseek.com/anthropic
  47. #for opencode-go you have to setup local proxy
  48. #see: https://github.com/routatic/proxy
  49. ANTHROPIC_AUTH_TOKEN: "sk-..."
  50. ANTHROPIC_MODEL: "{model}"
  51. opus: # local claude login — zero config
  52. type: claude
  53. ...
  54. codex: # local codex login — zero config
  55. type: codex
  56. ...
  57. ```
  58. ### 3. Dispatch your first task
  59. Go back to Claude Code and say:
  60. > Make a plan, then hand it to `/handoff-ds`.
  61. The task runs in the background; your session is never blocked. When it finishes, the agent reads the result and reports back.
  62. ### 4. Who you can hand work off to
  63. | What you say | From | Hands off to | Best for |
  64. | --- | --- | --- | --- |
  65. | `/handoff-ds` | Claude Code | DeepSeek V4 | Execution work: writing code, running tests, refactors, bulk edits |
  66. | `handoff-ds` (custom agent) | Codex | DeepSeek V4 | Same as above — use this when you're inside Codex |
  67. | `/handoff-gemini` / `handoff-gemini` | Claude Code / Codex | Gemini | Execution or investigation delegated to Gemini |
  68. | `/handoff-codex` | Claude Code | Codex (GPT-5.5) | Heavy reasoning, second opinions, hard bugs |
  69. | `handoff-opus` (custom agent) | Codex | Claude Opus | Decisions that deserve the top model |
  70. > Codex has no slash commands — mention the custom agent by name instead: say "have `handoff-ds` execute the task above."
  71. ### 5. Watch progress / browse history
  72. 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).
  73. ## FAQ
  74. <details>
  75. <summary><b>How do I browse the task list or watch a task's progress?</b></summary>
  76. <br>
  77. 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:
  78. <table>
  79. <tr>
  80. <td width="50%" valign="top">
  81. **`handoff list` / `handoff ls`** — interactive TUI over your full task history. See the full prompt, live status, and final result; press `O` on a row to reload that conversation and keep chatting.
  82. </td>
  83. <td width="50%" valign="top">
  84. **`handoff tail <run-id>`** — follow a task's output stream live, like looking over its shoulder.
  85. </td>
  86. </tr>
  87. <tr>
  88. <td valign="top">
  89. <!-- docs/assets/list-tui.jpg — ~480px wide — TUI list + detail view, highlight G/C shortcuts -->
  90. <img src="https://raw.githubusercontent.com/dazuiba/handoff/main/docs/assets/list-tui.jpg" width="100%" alt="handoff list interactive TUI">
  91. </td>
  92. <td valign="top">
  93. <!-- docs/assets/tail.jpg — ~480px wide — handoff tail live stream -->
  94. <img src="https://raw.githubusercontent.com/dazuiba/handoff/main/docs/assets/tail.jpg" width="100%" alt="handoff tail live follow">
  95. </td>
  96. </tr>
  97. </table>
  98. </details>
  99. <details>
  100. <summary><b>Can I change the TUI theme?</b></summary>
  101. <br>
  102. Yes. Inside `handoff list` and `handoff tail`, press `D` to toggle between `textual-dark` and `textual-light`. Your choice is saved automatically to `~/.handoff/tui_state.json` and restored next time you run the TUI.
  103. </details>
  104. <details>
  105. <summary><b>Can I dispatch several tasks at once?</b></summary>
  106. <br>
  107. 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.
  108. <!-- docs/assets/parallel.jpg — ~621px wide — 2–3 background tasks from one message, each with its own RESULT= path -->
  109. <img src="https://raw.githubusercontent.com/dazuiba/handoff/main/docs/assets/parallel.jpg" width="621" alt="Parallel dispatch">
  110. </details>
  111. <details>
  112. <summary><b>No uv / installing from source?</b></summary>
  113. <br>
  114. `pipx install handoff-cli` or `pip install handoff-cli` work just as well. From source:
  115. ```bash
  116. git clone https://github.com/dazuiba/handoff && cd handoff
  117. uv tool install -e .
  118. handoff init
  119. ```
  120. </details>
  121. <details>
  122. <summary><b>How do I add a custom backend / what goes in the env block?</b></summary>
  123. <br>
  124. Add one more entry under `backends` — any Anthropic-compatible endpoint works:
  125. ```yaml
  126. backends:
  127. kimi:
  128. type: claude
  129. model: kimi-k3
  130. env:
  131. ANTHROPIC_BASE_URL: https://api.moonshot.cn/anthropic
  132. ANTHROPIC_AUTH_TOKEN: "${MOONSHOT_API_KEY}"
  133. ANTHROPIC_MODEL: "{model}"
  134. ```
  135. 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)**.
  136. </details>
  137. <details>
  138. <summary><b>How does it actually work?</b></summary>
  139. <br>
  140. 1. Your agent hands the whole task to handoff, which runs it **in the background** — your session never blocks.
  141. 2. handoff launches the matching CLI (`claude -p` / `codex exec`) in an isolated context and streams the full output to disk.
  142. 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.
  143. 4. On completion the agent gets notified, reads the result file, and reports back to you.
  144. 5. The `RESULT=` path is also a stable handle for the conversation: every follow-up round resumes the same session.
  145. </details>
  146. **More docs**
  147. - **[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.
  148. - **[Configuration (Chinese) →](docs/configuration.zh-CN.md)** — mechanism vs data layers, env block, `${ENV}` interpolation, include, custom backends.
  149. - **[Design notes (Chinese) →](docs/design.zh-CN.md)** — why Claude Code uses skills while Codex uses custom agents, plus the RESULT= protocol.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.