Handoff
dazuiba/handoff
Delegue tarefas entre Claude e DeepSeek sem trocar de ferramenta
Ver no GitHubPlugin que permite delegar tarefas entre agentes de codificação (Claude Code, Codex e DeepSeek) sem perder contexto. Otimiza custos usando DeepSeek V4 para trabalhos simples e rápidos, reservando modelos premium para decisões complexas.
Instalação
npx convez-ai dazuiba/handoff1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Otimizar custo de chamadas a APIs de IA usando DeepSeek para tarefas simples
- Distribuir carga de trabalho entre múltiplos agentes de codificação
- Manter contexto ao transferir tarefas entre diferentes sessões de IA
Veredito

Ferramenta bem pensada para quem trabalha com múltiplos agentes de IA e quer otimizar custos sem sacrificar qualidade. A arquitetura de handoff é elegante, mas requer familiaridade com Claude Code/Codex e gestão de tokens de API.
README
A tradução para o português deste README ainda está na fila.
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 · 简体中文
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."
— 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."
— Just say: "Ask
/handoff-codexwhat it thinks." No new terminal. No re-explaining. The answer comes back to your current session. - 🔁 "
/handoff-dsfinished that task. Now I have a follow-up task for it." — Just say: "Resume the last/handoff-dssession, 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 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 (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
uv tool install handoff-cli
handoff init # creates the config, links skill / agent files
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 (lowest cost, includes DeepSeek V4). Once you have a key, edit ~/.handoff/config.yaml and change just the ANTHROPIC_AUTH_TOKEN line:
# ~/.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 | codex/deepseek | 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-dsexecute 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
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:
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.
handoff tail <run-id> — follow a task's output stream live, like looking over its shoulder.
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.
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.
pipx install handoff-cli or pip install handoff-cli work just as well. From source:
git clone https://github.com/dazuiba/handoff && cd handoff
uv tool install -e .
handoff init
Add one more entry under backends — any Anthropic-compatible endpoint works:
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) →.
- Your agent hands the whole task to handoff, which runs it in the background — your session never blocks.
- handoff launches the matching CLI (
claude -p/codex exec) in an isolated context and streams the full output to disk. - The main session receives exactly one line:
RESULT=<path-to-result-file>. Progress goes to the background shell view — never into your main context. - On completion the agent gets notified, reads the result file, and reports back to you.
- The
RESULT=path is also a stable handle for the conversation: every follow-up round resumes the same session.
More docs
- CLI reference (Chinese) → — full usage of
run/resume/list/tail/env/init, run-id encoding, on-disk file layout. - Configuration (Chinese) → — mechanism vs data layers, env block,
${ENV}interpolation, include, custom backends. - Design notes (Chinese) → — why Claude Code uses background shells while Codex uses a subagent; the RESULT= protocol.