dsh-baton-mcp 0.6.2 → 0.6.4-next.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +152 -98
- package/README.zh-CN.md +150 -98
- package/WINDOWS.md +3 -1
- package/host/README.md +4 -4
- package/host/lib/client.js +3 -38
- package/host/lib/index.js +52 -11
- package/host/package.json +3 -3
- package/package.json +1 -1
- package/server.json +2 -2
- package/src/cli.mjs +7 -6
- package/src/codex-hook.mjs +137 -78
- package/src/core.mjs +35 -6
- package/src/evidence.mjs +38 -5
- package/src/mcp.mjs +66 -37
- package/src/register.mjs +225 -199
- package/src/server.mjs +9 -3
- package/src/setup.mjs +7 -9
package/README.md
CHANGED
|
@@ -1,161 +1,188 @@
|
|
|
1
1
|
<p align="center">
|
|
2
|
-
<img src="./assets/readme/hero.gif" width="100%" alt="dsh-baton: pass the baton from Claude Code or Codex to DeepSeek Harness, watch it run live, and get it handed back when it's done">
|
|
2
|
+
<picture><source media="(prefers-color-scheme: dark)" srcset="./assets/readme/en/hero-dark.gif"><img src="./assets/readme/en/hero.gif" width="100%" alt="dsh-baton: pass the baton from Claude Code or Codex to DeepSeek Harness, watch it run live, and get it handed back when it's done"></picture>
|
|
3
3
|
</p>
|
|
4
4
|
|
|
5
5
|
<p align="center">
|
|
6
|
-
English | <a href="README.zh-CN.md">中文</a>
|
|
6
|
+
English | <a href="README.zh-CN.md">中文</a> · macOS · Windows (<a href="WINDOWS.md">guide</a>) · no Node.js needed · zero dependencies · MIT
|
|
7
7
|
</p>
|
|
8
8
|
|
|
9
|
-
<p align="center">
|
|
10
|
-
macOS · Windows (<a href="WINDOWS.md">guide</a>) · no Node.js needed · zero dependencies · MIT
|
|
11
|
-
</p>
|
|
9
|
+
<p align="center"><a href="#quick-start">Quick start</a> · <a href="#see-it-run">See it run</a> · <a href="#token-usage">Token usage</a> · <a href="#how-it-works">How it works</a> · <a href="#tools">Tools</a> · <a href="#security-and-limits">Security</a></p>
|
|
12
10
|
|
|
13
|
-
|
|
11
|
+
<br>
|
|
14
12
|
|
|
15
|
-
|
|
13
|
+
Hand coding tasks from Claude Code or Codex to DeepSeek Harness on your machine: the task runs live in the Harness window, the main agent hears back once when it ends, and it gets back the files that changed, the project's own test results and a requirement-by-requirement checklist.
|
|
16
14
|
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
15
|
+
- **Cheaper on money and on quota:** with Claude Code, the total cost, DeepSeek included, is 51–78% lower. On a long Codex job, the share of a ChatGPT Plus 5-hour window it uses goes from 86.01% to 16.01% with GPT-6 Astra, and from 13.71% to 2.67% with GPT-6.1 Sol.
|
|
16
|
+
- **Nothing to watch or poll:** Claude Code is woken once when the run ends; Codex waits out a run of up to an hour in a single call.
|
|
17
|
+
- **A clear split of the work:** Claude Code or Codex writes the request and checks the result; DeepSeek writes the code and runs the tests in Harness. The one who checks is not the one who wrote it.
|
|
20
18
|
|
|
21
|
-
|
|
22
|
-
<img src="./assets/readme/flow.gif" width="100%" alt="Typical flow: create a workspace, send the task, wait without polling (Claude Code and Codex are woken when the run ends), follow up in the same session">
|
|
23
|
-
</p>
|
|
19
|
+
Needs DeepSeek Harness ≥ 0.2.1-rc.2 (signed in) and Claude Code or Codex. [Quick start →](#quick-start)
|
|
24
20
|
|
|
25
|
-
##
|
|
21
|
+
## What it is
|
|
26
22
|
|
|
27
|
-
|
|
23
|
+
dsh-baton is an MCP server plus a small Harness plugin. The main agent hands the task to an ordinary Harness session with one tool call: you watch it run in the Harness window and can step in at any time, and the main agent hears back once, without polling. Unlike a plain MCP bridge to another model, the work stays visible and the proof comes back with the result.
|
|
28
24
|
|
|
29
|
-
<p align="center">
|
|
30
|
-
<img src="./assets/demos/s3-queue-en.gif" width="100%" alt="Codex on the left starts a DeepSeek task, queues a follow-up, steers the running turn and waits; DeepSeek Harness on the right runs each one live">
|
|
31
|
-
</p>
|
|
25
|
+
<p align="center"><picture><source media="(prefers-color-scheme: dark)" srcset="./assets/readme/en/divider-dark.svg"><img src="./assets/readme/en/divider.svg" width="100%" alt=""></picture></p>
|
|
32
26
|
|
|
33
|
-
|
|
27
|
+
## Why split the work
|
|
34
28
|
|
|
35
|
-
|
|
36
|
-
<img src="./assets/demos/s8-relay-en-zoom.gif" width="100%" alt="Harness chat where messages alternate between Codex and Claude, each labelled Sent by ChatGPT or Sent by Claude from another chat">
|
|
37
|
-
</p>
|
|
29
|
+
Beyond the savings, the split itself helps:
|
|
38
30
|
|
|
39
|
-
|
|
31
|
+
- **A spec before the code.** The main agent turns your request into concrete items before handing it over, so Harness gets a spec rather than a one-line "build me an X".
|
|
32
|
+
- **Checked on evidence.** The result carries the changed files, your project's own test output and a point-by-point check against the request; anything missing goes back for another round, instead of taking "done" on trust.
|
|
33
|
+
- **The main conversation keeps the decisions.** Hundreds of steps of reading files, editing and running tests stay in the Harness session; the main conversation holds your request and the conclusions.
|
|
34
|
+
- **Visible and steerable.** The work runs live in the Harness window. You can step in there at any time, and the main agent can steer a new requirement into the running turn.
|
|
35
|
+
|
|
36
|
+
<p align="center"><picture><source media="(prefers-color-scheme: dark)" srcset="./assets/readme/en/divider-dark.svg"><img src="./assets/readme/en/divider.svg" width="100%" alt=""></picture></p>
|
|
40
37
|
|
|
41
38
|
## Quick start
|
|
42
39
|
|
|
43
40
|
<p align="center">
|
|
44
|
-
<img src="./assets/readme/install.svg" width="100%" alt="Step 1: in Harness open Plugins, Add plugin, enter dsh-baton-host, Install, Enable now; it registers dsh-baton for Claude Code and Codex. Step 2
|
|
41
|
+
<picture><source media="(prefers-color-scheme: dark)" srcset="./assets/readme/en/install-dark.svg"><img src="./assets/readme/en/install.svg" width="100%" alt="Step 1: in Harness open Plugins, Add plugin, enter dsh-baton-host, Install, Enable now; it registers dsh-baton for Claude Code and Codex. Step 2: open a new conversation in Claude Code or Codex; Codex asks once to approve the dsh-baton tools. Step 3: ask it to call dsh_list_workspaces; it lists your Harness workspaces."></picture>
|
|
45
42
|
</p>
|
|
46
43
|
|
|
47
|
-
|
|
44
|
+
Nothing else to install: no Node.js, no terminal. The steps are the same on macOS and Windows.
|
|
48
45
|
|
|
49
46
|
**1. Add the plugin in Harness:** **Plugins** (插件) → **Add plugin** (添加插件) → type `dsh-baton-host` → **Install** (安装) → **Enable now** (立即启用).
|
|
50
47
|
|
|
51
48
|
Switched on, the plugin registers dsh-baton for Claude Code and Codex, for every folder, and Harness says so.
|
|
52
49
|
|
|
53
|
-
**2.
|
|
50
|
+
**2. Open a new chat:** in Claude Code or Codex, start a **new** conversation; one that was already open does not see dsh-baton yet. The steps are the same for both. Codex asks you to approve MCP tool calls: approve the `dsh-baton` tools (for unattended `codex exec` runs, add `--approve-for-me`).
|
|
54
51
|
|
|
55
|
-
**3. Check:**
|
|
52
|
+
**3. Check:** ask it to call `dsh_list_workspaces`. It lists your Harness workspaces.
|
|
56
53
|
|
|
57
|
-
That is all.
|
|
54
|
+
That is all. To hand a task over, end the request with "hand it to DeepSeek Harness". Updating, removing, Windows, and registering by hand when the plugin could not, are [further down](#install-details).
|
|
58
55
|
|
|
59
|
-
|
|
56
|
+
**New in 0.6.4:** Codex waits in one `dsh_wait` call of up to 59 minutes, so a run that ends within the hour costs one model request to wait for, and the result arrives as an ordinary reply in the chat. Update the plugin in Harness and new Codex conversations have it, with no restart.
|
|
60
57
|
|
|
61
|
-
<p align="center">
|
|
62
|
-
|
|
63
|
-
|
|
58
|
+
<p align="center"><picture><source media="(prefers-color-scheme: dark)" srcset="./assets/readme/en/divider-dark.svg"><img src="./assets/readme/en/divider.svg" width="100%" alt=""></picture></p>
|
|
59
|
+
|
|
60
|
+
## See it run
|
|
61
|
+
|
|
62
|
+
*Claude Code and Codex each hand DeepSeek Harness a task, and its subagents build this rainy-night street in 1 h 41 min. 40 s, sound on.*
|
|
63
|
+
|
|
64
|
+
https://github.com/user-attachments/assets/72e2fdff-275e-48bc-8e5a-39ffb025a0a8
|
|
64
65
|
|
|
65
66
|
<p align="center">
|
|
66
|
-
<img src="./assets/readme/
|
|
67
|
+
<picture><source media="(prefers-color-scheme: dark)" srcset="./assets/readme/en/flow-dark.gif"><img src="./assets/readme/en/flow.gif" width="100%" alt="Typical flow: create a workspace, send the task, wait without polling (Claude Code is woken once, Codex waits up to 59 minutes in one dsh_wait call), follow up in the same session"></picture>
|
|
67
68
|
</p>
|
|
68
69
|
|
|
69
|
-
|
|
70
|
-
- **Claude Code** waits for a run in the background (the `wait_command` that `dsh_send` returns) and is woken once, when the run ends.
|
|
71
|
-
- **Codex** with the dsh-baton Stop hook trusted (from 0.6.1): after `dsh_send` it ends its turn; the hook waits for the run outside the model and, when the run ends or asks something, continues the same conversation with the result. One model request per run instead of one every 270 s.
|
|
72
|
-
- **Codex** without the hook waits inside `dsh_wait`, up to 270 s per call, just under its 300 s tool timeout. An unfinished wait returns only the state, so Codex calls again without summarising. Codex gets no `wait_command`: its terminal cannot wake it, so it would poll.
|
|
73
|
-
- Codex asks you to approve MCP tool calls: approve the `dsh-baton` tools. For unattended `codex exec` runs, add `--approve-for-me`.
|
|
74
|
-
|
|
75
|
-
**Pick a model** (from 0.6.1): just say which one, for example "hand it to DeepSeek, V4 Pro". `dsh_send` passes it as `model` (and `reasoning_effort`), matched against the models Harness lists, so a model Harness adds later works as soon as it shows up. It applies to that session only; Harness's default model stays as it was. `dsh_list_models` shows what is available.
|
|
70
|
+
One Codex chat starts a task, queues a follow-up, steers the running turn, and waits for all three:
|
|
76
71
|
|
|
77
|
-
|
|
72
|
+
<p align="center">
|
|
73
|
+
<img src="./assets/demos/s3-queue-en.gif" width="100%" alt="Codex on the left starts a DeepSeek task, queues a follow-up, steers the running turn and waits; DeepSeek Harness on the right runs each one live">
|
|
74
|
+
</p>
|
|
78
75
|
|
|
79
|
-
|
|
76
|
+
Codex and Claude take turns in the same Harness session, and every message is labelled with who sent it:
|
|
80
77
|
|
|
81
78
|
<p align="center">
|
|
82
|
-
<img src="./
|
|
79
|
+
<img src="./assets/demos/s8-relay-en-zoom.gif" width="100%" alt="Harness chat where messages alternate between Codex and Claude, each labelled Sent by ChatGPT or Sent by Claude from another chat">
|
|
83
80
|
</p>
|
|
84
81
|
|
|
82
|
+
<p align="center"><a href="docs/demos.md">More demos →</a></p>
|
|
83
|
+
|
|
84
|
+
<p align="center"><picture><source media="(prefers-color-scheme: dark)" srcset="./assets/readme/en/divider-dark.svg"><img src="./assets/readme/en/divider.svg" width="100%" alt=""></picture></p>
|
|
85
|
+
|
|
85
86
|
## Token usage
|
|
86
87
|
|
|
87
|
-
**In short: hand over the big, long jobs.**
|
|
88
|
+
**In short: hand over the big, long jobs.** With Claude Code the total cost, DeepSeek included, is 51–78% lower. With Codex on GPT-6 Astra it is 47–81% lower, and the long kanban app takes 16.01% of a ChatGPT Plus 5-hour window instead of 86.01%.
|
|
88
89
|
|
|
89
|
-
**
|
|
90
|
+
**Hand it over:** big jobs, long jobs, and whenever the 5-hour window is running low. The main agent's own spend drops 61–87% on every task and model.
|
|
90
91
|
|
|
91
|
-
**
|
|
92
|
+
**Do it yourself:** small tasks on Codex with GPT-6.1 Sol. Sol is cheap enough that DeepSeek's part of a hand-over, two thirds or more, outweighs what Sol saves.
|
|
92
93
|
|
|
93
|
-
**The
|
|
94
|
-
- **Task 1 · CLI tool:** a command-line task manager in Node, no dependencies, split into modules, with tests. [Request](docs/benchmarks/token-usage-2026-10/natural/medium.md)
|
|
95
|
-
- **Task 2 · Web app:** a task manager with a Node server and a page, REST API, stats, tests and a README. [Request](docs/benchmarks/token-usage-2026-10/natural/large.md)
|
|
94
|
+
**The three test tasks**, asked the way a user would (the requests are in Chinese, linked as written):
|
|
95
|
+
- **Task 1 · CLI tool:** a command-line task manager in Node, no dependencies, split into modules, with tests. [Request](docs/benchmarks/token-usage-2026-10/natural/medium.md)
|
|
96
|
+
- **Task 2 · Web app:** a task manager with a Node server and a page, REST API, stats, tests and a README. [Request](docs/benchmarks/token-usage-2026-10/natural/large.md)
|
|
97
|
+
- **Task 3 · Kanban app (phased):** a kanban board in plain Node and a plain front end, in three phases given one after another in the same conversation: ① the core (REST API, storage, drag and drop); ② labels, due dates, search syntax, archive, undo and redo, activity log, import and export; ③ version conflicts, WIP limits, bulk actions, live sync over SSE, stats. 55 acceptance tests written beforehand, the same for both arms. Requests: [phase 1](docs/benchmarks/token-usage-2026-10/xxl/seed/docs/phase1.md) · [phase 2](docs/benchmarks/token-usage-2026-10/xxl/seed/docs/phase2.md) · [phase 3](docs/benchmarks/token-usage-2026-10/xxl/seed/docs/phase3.md)
|
|
98
|
+
|
|
99
|
+
| Task 3 | Alone | Handed over |
|
|
100
|
+
|---|---|---|
|
|
101
|
+
| Opus 5.5 high | 55/55, 39 min | 55/55, 93 min |
|
|
102
|
+
| GPT-6.1 Sol high | 55/55, 18 min | 55/55, 101 min |
|
|
103
|
+
| GPT-6 Astra high | 55/55, about 31 min | 55/55, about 87 min |
|
|
104
|
+
|
|
105
|
+
Cost per task at list price, DeepSeek V4.1 Flash 1017 at its peak price. Opus 5.5 runs in Claude Code, GPT-6.1 Sol and GPT-6 Astra in Codex, all at high effort:
|
|
106
|
+
|
|
107
|
+
| Task | Model | Alone | Handed over: main agent | Handed over: DeepSeek | Handed over: total | Total | Main agent | 5-hour window, alone → handed over |
|
|
108
|
+
|---|---|---|---|---|---|---|---|---|
|
|
109
|
+
| Task 1 · CLI tool | Opus 5.5 high | $1.07 | $0.42 | $0.10 | $0.52 | −51.2% | −60.8% | — |
|
|
110
|
+
| | GPT-6.1 Sol high | $0.17 | $0.06 | $0.13 | $0.20 | +15.3% | −62.9% | 2.08% → 0.77% |
|
|
111
|
+
| | GPT-6 Astra high | $0.79 | $0.30 | $0.12 | $0.42 | −47.4% | −62.0% | 7.83% → 2.98% |
|
|
112
|
+
| Task 2 · Web app | Opus 5.5 high | $2.13 | $0.47 | $0.13 | $0.60 | −71.7% | −77.7% | — |
|
|
113
|
+
| | GPT-6.1 Sol high | $0.41 | $0.06 | $0.18 | $0.25 | −40.2% | −84.5% | 5.08% → 0.79% |
|
|
114
|
+
| | GPT-6 Astra high | $2.27 | $0.30 | $0.13 | $0.42 | −81.4% | −86.9% | 22.43% → 2.94% |
|
|
115
|
+
| Task 3 · Kanban app (phased) | Opus 5.5 high | $14.18 | $2.32 | $0.84 | $3.16 | −77.7% | −83.6% | — |
|
|
116
|
+
| | GPT-6.1 Sol high | $1.12 | $0.22 | $0.81 | $1.03 | −8.1% | −80.5% | 13.71% → 2.67% |
|
|
117
|
+
| | GPT-6 Astra high | $8.69 | $1.62 | $0.74 | $2.35 | −72.9% | −81.4% | 86.01% → 16.01% |
|
|
96
118
|
|
|
97
119
|
<p align="center">
|
|
98
|
-
<img src="./docs/benchmarks/token-usage-2026-10/charts/
|
|
120
|
+
<img src="./docs/benchmarks/token-usage-2026-10/charts/cost.svg" width="100%" alt="Cost per task in USD, working alone vs handed over, grouped by model. Opus 5.5 high: $1.07 vs $0.52, $2.13 vs $0.60, $14.18 vs $3.16. GPT-6.1 Sol high: $0.17 vs $0.20, $0.41 vs $0.25, $1.12 vs $1.03. GPT-6 Astra high: $0.79 vs $0.42, $2.27 vs $0.42, $8.69 vs $2.35">
|
|
99
121
|
</p>
|
|
100
122
|
|
|
101
|
-
Cost per task at list price, DeepSeek V4.1 Flash 1017 at its peak price:
|
|
102
|
-
|
|
103
|
-
| Client · model | Task | Alone | Handed over, client only | Handed over, with DeepSeek |
|
|
104
|
-
|---|---|---|---|---|
|
|
105
|
-
| Claude Code · Opus 5.5 high | Task 1 · CLI tool | $1.07 | $0.42 (−61%) | $0.52 (−51%) |
|
|
106
|
-
| Claude Code · Opus 5.5 high | Task 2 · Web app | $2.13 | $0.47 (−78%) | $0.60 (−72%) |
|
|
107
|
-
| Codex · GPT-6.1 Sol high | Task 1 · CLI tool | $0.17 | $0.06 (−63%) | $0.20 (+15%) |
|
|
108
|
-
| Codex · GPT-6.1 Sol high | Task 2 · Web app | $0.41 | $0.06 (−84%) | $0.25 (−40%) |
|
|
109
|
-
| Codex · GPT-6 Astra high | Task 1 · CLI tool | $0.79 | $0.30 (−62%) | $0.42 (−47%) |
|
|
110
|
-
| Codex · GPT-6 Astra high | Task 2 · Web app | $2.27 | $0.30 (−87%) | $0.42 (−81%) |
|
|
111
|
-
|
|
112
123
|
<p align="center">
|
|
113
|
-
<img src="./docs/benchmarks/token-usage-2026-10/charts/
|
|
124
|
+
<img src="./docs/benchmarks/token-usage-2026-10/charts/quota.svg" width="100%" alt="Share of a ChatGPT Plus 5-hour window in Codex, working alone vs handed over, grouped by model. GPT-6.1 Sol high: 2.08% vs 0.77%, 5.08% vs 0.79%, 13.71% vs 2.67%. GPT-6 Astra high: 7.83% vs 2.98%, 22.43% vs 2.94%, 86.01% vs 16.01%">
|
|
114
125
|
</p>
|
|
115
126
|
|
|
116
|
-
|
|
127
|
+
<details>
|
|
128
|
+
<summary>What was tested, and how</summary>
|
|
129
|
+
|
|
130
|
+
- **The only difference** in the hand-over runs is one line added at the end of the request: 交给 DeepSeek Harness 去做。 ("Hand it to DeepSeek Harness.")
|
|
131
|
+
- Same model and effort in both arms, and every run judged by the same acceptance check, which the model never sees.
|
|
132
|
+
- Tasks 1 and 2: the mean of three runs per cell. Task 3: one run per cell. Every run passed its acceptance check, with no rework.
|
|
133
|
+
- Prices are list prices. DeepSeek is counted at its peak price; the real DeepSeek bill came to about 58% of that.
|
|
134
|
+
- The 5-hour window share is worked out from each run's cost: 12.27 points per $1 for GPT-6.1 Sol, 9.90 for GPT-6 Astra.
|
|
135
|
+
- 0.6.2 cuts the MCP instructions to one sentence, so Codex reads a few thousand to over ten thousand fewer new input tokens per hand-over. The Codex runs were measured with 0.6.1 to 0.6.3, where a Stop hook did the waiting; from 0.6.4 one `dsh_wait` call does it, also in one model request for every 59 minutes of a run.
|
|
117
136
|
|
|
118
|
-
|
|
137
|
+
</details>
|
|
119
138
|
|
|
120
|
-
|
|
139
|
+
<p align="center"><picture><source media="(prefers-color-scheme: dark)" srcset="./assets/readme/en/divider-dark.svg"><img src="./assets/readme/en/divider.svg" width="100%" alt=""></picture></p>
|
|
140
|
+
|
|
141
|
+
## How it works
|
|
121
142
|
|
|
122
143
|
<p align="center">
|
|
123
|
-
<img src="./
|
|
144
|
+
<picture><source media="(prefers-color-scheme: dark)" srcset="./assets/readme/en/architecture-dark.gif"><img src="./assets/readme/en/architecture.gif" width="100%" alt="MCP clients call dsh-baton-mcp over stdio; it reaches the dsh-baton-host plugin inside Harness through an owner-only local socket; the plugin drives Harness sessions live, with dsh headless as fallback"></picture>
|
|
124
145
|
</p>
|
|
125
146
|
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
| 5-hour window | 86% | about 16% (−81%) |
|
|
132
|
-
| Acceptance tests | 55/55, first try | 55/55, first try |
|
|
133
|
-
| Time | about 31 min | about 87 min |
|
|
134
|
-
| Lines of code | 1,876 | 9,953 |
|
|
147
|
+
<p align="center">
|
|
148
|
+
<picture><source media="(prefers-color-scheme: dark)" srcset="./assets/readme/en/comparison-dark.svg"><img src="./assets/readme/en/comparison.svg" width="100%" alt="Plugin vs headless: only the plugin shows runs live in the Harness UI, continues desktop sessions and uses desktop agent presets; both reuse the desktop sign-in"></picture>
|
|
149
|
+
</p>
|
|
150
|
+
|
|
151
|
+
**Pick a model:** just say which one, for example "hand it to DeepSeek, V4 Pro". `dsh_send` passes it as `model` (and `reasoning_effort`), matched against the models Harness lists, so a model Harness adds later works as soon as it shows up. It applies to that session only; Harness's default model stays as it was. `dsh_list_models` shows what is available.
|
|
135
152
|
|
|
136
|
-
|
|
153
|
+
Nothing to configure for waiting; if you want to know what each client does while a run is going:
|
|
137
154
|
|
|
138
155
|
<details>
|
|
139
|
-
<summary>
|
|
156
|
+
<summary>How each client waits</summary>
|
|
140
157
|
|
|
141
|
-
- **
|
|
142
|
-
-
|
|
143
|
-
-
|
|
144
|
-
- Prices are list prices. DeepSeek is counted at its peak price, the most conservative case; the real DeepSeek bill came to about 58% of that.
|
|
145
|
-
- Every run: [run log](docs/benchmarks/token-usage-2026-10/LOG.md) (section "0.6.2 hand-over rerun"); raw data in `docs/benchmarks/token-usage-2026-10/results/*-n062*.jsonl`; method and earlier builds in the [full report](docs/benchmarks/token-usage-2026-10.md).
|
|
158
|
+
- **Claude Code** waits for a run in the background (the `wait_command` that `dsh_send` returns) and is woken once, when the run ends.
|
|
159
|
+
- **Codex** waits inside `dsh_wait`. The plugin sets Codex's tool timeout for dsh-baton to an hour (`tool_timeout_sec = 3600`), so one call waits up to 59 minutes: a run that ends within the hour costs one model request to wait for, however long it takes, and the result comes back as an ordinary tool result in the chat. A longer run returns `timed_out` with just the state after 59 minutes, and Codex calls again without summarising. Pressing Stop ends the wait at once. Codex gets no `wait_command`: its terminal cannot wake it, so it would poll. Conversations opened before the plugin set the timeout, or an entry you wrote yourself without it, wait 270 s per call, just under Codex's default 300 s timeout. Measured in the Codex desktop app: a 28-minute run took one `dsh_wait` call; a 62-minute run took two, the first returning `timed_out` after 59 minutes and the second getting the result 3 minutes later, with no `dsh_status` calls in between.
|
|
160
|
+
- **Changing the request while it waits.** In Codex, send the change with **Steer**: Codex stops waiting at once, steers it into the same Harness session (`dsh_send` with `mode` `steer`) and waits on the new run; Harness does both in the same turn. Sent with **Queue**, Codex sees it only when the run ends; you can also press Stop first and then send it. In Claude Code, just send it: it waits in the background, so it steers the change in right away. A steered run ends together with the original and they share one result; a queued run comes back on its own. Runs working in the same folder at the same time are named in each other's results, so neither removes the other's files.
|
|
146
161
|
|
|
147
162
|
</details>
|
|
148
163
|
|
|
164
|
+
### How a hand-over is checked
|
|
165
|
+
|
|
166
|
+
You don't have to take DeepSeek's word for it. Before the run, dsh-baton notes what is in the folder. When the run ends it shows exactly which files were created, changed or deleted, and runs your project's own tests itself (`npm test`, or whatever the client passes as `checks`). A second, read-only DeepSeek agent then goes through the request point by point and ends with a table: requirement, met or not, and where (file:line). Claude or GPT reads just that, sends anything missing back in one message, and opens code only where a row says "not met". Unless `cwd` names another folder, the new Harness session starts in the folder you're already working in.
|
|
167
|
+
|
|
168
|
+
<p align="center">
|
|
169
|
+
<img src="./docs/benchmarks/token-usage-2026-10/charts/evidence-chain.svg" width="100%" alt="Evidence chain of one real hand-over: the user asks, Codex writes the spec and checks, dsh-baton snapshots the folder, DeepSeek Harness writes 11 files, dsh-baton lists the changed files and runs npm test itself, Codex sends one fix back on its own, dsh-baton checks again, Codex accepts, and the benchmark's own test passes 13 of 13">
|
|
170
|
+
</p>
|
|
171
|
+
|
|
172
|
+
<p align="center"><picture><source media="(prefers-color-scheme: dark)" srcset="./assets/readme/en/divider-dark.svg"><img src="./assets/readme/en/divider.svg" width="100%" alt=""></picture></p>
|
|
173
|
+
|
|
149
174
|
## Tools
|
|
150
175
|
|
|
151
176
|
<p align="center">
|
|
152
|
-
<img src="./assets/readme/tools.svg" width="100%" alt="Ten tools in the tool list: list workspaces, list sessions, read session, list models, send, status, wait, answer, cancel, call. Six less used tools are reached through dsh_call: create and rename workspace, session activity, rename session, update queued, list runs">
|
|
177
|
+
<picture><source media="(prefers-color-scheme: dark)" srcset="./assets/readme/en/tools-dark.svg"><img src="./assets/readme/en/tools.svg" width="100%" alt="Ten tools in the tool list: list workspaces, list sessions, read session, list models, send, status, wait, answer, cancel, call. Six less used tools are reached through dsh_call: create and rename workspace, session activity, rename session, update queued, list runs"></picture>
|
|
153
178
|
</p>
|
|
154
179
|
|
|
155
180
|
<p align="center">
|
|
156
|
-
<img src="./assets/readme/states.
|
|
181
|
+
<picture><source media="(prefers-color-scheme: dark)" srcset="./assets/readme/en/states-dark.gif"><img src="./assets/readme/en/states.gif" width="100%" alt="Run states: queued, running, waiting, completed, failed, cancelled, and interrupted when Harness restarts mid-run. A busy session takes followup (queued) or steer (interjects) messages; left unset, your Harness setting decides"></picture>
|
|
157
182
|
</p>
|
|
158
183
|
|
|
184
|
+
When you want the exact parameters and return fields of each tool:
|
|
185
|
+
|
|
159
186
|
<details>
|
|
160
187
|
<summary>Full tool reference</summary>
|
|
161
188
|
|
|
@@ -168,9 +195,9 @@ The server's MCP instructions are a single sentence (from 0.6.2); how to hand ov
|
|
|
168
195
|
| `dsh_list_sessions` | Sessions newest first, with title, folder, running state and `model` (what its next request uses); filter by folder or text. Archived sessions are left out |
|
|
169
196
|
| `dsh_list_models` | The models Harness can run (provider, id, name, reasoning efforts) and its default model |
|
|
170
197
|
| `dsh_read_session` | Recent prompts and replies of one session (with tool names); `archived: true` for an archived session |
|
|
171
|
-
| `dsh_send` | Send a message: `session_id` continues that session; otherwise a new one starts in `cwd` or `workspace_id`, or, with neither, in the folder the conversation works in (a `cwd` that is not a workspace yet is registered first; a `cwd` outside the conversation's folder is allowed and noted in `folder_note`). `checks`: test commands dsh-baton runs itself when the run ends (see How a hand-over is checked). Returns a `run_id` at once. In Harness the message is marked "Sent by Claude / ChatGPT from another chat". An archived session is refused: unarchive it in Harness, or start a new session. To a busy session, `mode` `followup` queues the message after the current turn and `steer` adds it to the running turn; left out, it does what Harness's own setting says (Settings → sending while busy: queue or steer), and `followup` when that cannot be read. `mode_source` says which applied. `model` only when the user names one ("DeepSeek-V4 Pro", "v4-pro"; `reasoning_effort` likewise): it is matched against Harness's own model list, ignoring case, spaces, hyphens and a leading DeepSeek, so a model Harness adds later (V4.1 Pro) works as soon as Harness lists it; a name that matches nothing or several fails the send, before anything is created, with the list (`provider/model` picks one). It is set on that session before the message goes in, and Harness's default model is put back as it was (Harness saves a session's pick as the default too). Left out, a continued session keeps its own model and a new one uses Harness's default. The reply says which in `model` and `model_source` |
|
|
198
|
+
| `dsh_send` | Send a message: `session_id` continues that session; otherwise a new one starts in `cwd` or `workspace_id`, or, with neither, in the folder the conversation works in (a `cwd` that is not a workspace yet is registered first; a `cwd` outside the conversation's folder is allowed and noted in `folder_note`). `checks`: test commands dsh-baton runs itself when the run ends (see [How a hand-over is checked](#how-a-hand-over-is-checked)). Returns a `run_id` at once. In Harness the message is marked "Sent by Claude / ChatGPT from another chat". An archived session is refused: unarchive it in Harness, or start a new session. To a busy session, `mode` `followup` queues the message after the current turn and `steer` adds it to the running turn; left out, it does what Harness's own setting says (Settings → sending while busy: queue or steer), and `followup` when that cannot be read. `mode_source` says which applied. `model` only when the user names one ("DeepSeek-V4 Pro", "v4-pro"; `reasoning_effort` likewise): it is matched against Harness's own model list, ignoring case, spaces, hyphens and a leading DeepSeek, so a model Harness adds later (V4.1 Pro) works as soon as Harness lists it; a name that matches nothing or several fails the send, before anything is created, with the list (`provider/model` picks one). It is set on that session before the message goes in, and Harness's default model is put back as it was (Harness saves a session's pick as the default too). Left out, a continued session keeps its own model and a new one uses Harness's default. The reply says which in `model` and `model_source` |
|
|
172
199
|
| `dsh_status` | Run progress: state, recent text and tool calls, final reply; `waiting_on` when the turn is over but sub-agents or jobs still run; `human_interjections` when someone typed in the Harness UI mid-run; state `interrupted` for a run cut short by a Harness restart; `model` the run was sent with |
|
|
173
|
-
| `dsh_wait` |
|
|
200
|
+
| `dsh_wait` | Wait for the run to end; a finished run carries `evidence` (files changed, check results) when the message was sent with `checks` (or until it stops to ask a person, see `dsh_answer`): up to 3540 s per call for Codex (its tool timeout for dsh-baton less 60 s; 270 s when that is not set), 50 s for other clients. Still going: returns `timed_out` with just the state; call it again. Clients that can wait in the background use `dsh_send`'s `wait_command` instead. `dsh_status` is a one-off look, not a way to wait |
|
|
174
201
|
| `dsh_answer` | Answer the questions a run stopped to ask (Harness's ask_user_question): per question, an option number or label, free text, or skip; one at a time or all at once. `dsh_wait` and `wait_command` return as soon as a run asks, with the questions (`needs_input`, `question`; the option Harness's model would pick is in `harness_suggested`, apart from the labels). The assistant answers by its own judgment only when you told it to decide, and then passes `reason` and tells you what it chose and why; otherwise it brings you the questions, starting with its own recommendation and reason. You can also answer in the Harness window: whoever answers first wins |
|
|
175
202
|
| `dsh_session_activity` | Through `dsh_call`. What a session is doing now: running turn, sub-agents (any depth), background jobs; `archived: true` for an archived session |
|
|
176
203
|
| `dsh_update_queued` | Through `dsh_call`. Change a message still waiting in the queue of a busy session, by its `run_id`: `edit` its text, `remove` it, or `steer` it into the running turn now. Once it has reached the conversation it can no longer be changed |
|
|
@@ -182,7 +209,14 @@ The server's MCP instructions are a single sentence (from 0.6.2); how to hand ov
|
|
|
182
209
|
|
|
183
210
|
</details>
|
|
184
211
|
|
|
185
|
-
|
|
212
|
+
<p align="center"><picture><source media="(prefers-color-scheme: dark)" srcset="./assets/readme/en/divider-dark.svg"><img src="./assets/readme/en/divider.svg" width="100%" alt=""></picture></p>
|
|
213
|
+
|
|
214
|
+
## Command line and configuration
|
|
215
|
+
|
|
216
|
+
When you want to drive Harness from a terminal or a script instead of a chat:
|
|
217
|
+
|
|
218
|
+
<details>
|
|
219
|
+
<summary>CLI commands</summary>
|
|
186
220
|
|
|
187
221
|
```bash
|
|
188
222
|
dsh-baton workspaces
|
|
@@ -199,20 +233,30 @@ dsh-baton rename session-xxxx "New title"
|
|
|
199
233
|
dsh-baton rename-workspace ~/code/new-app "New name"
|
|
200
234
|
```
|
|
201
235
|
|
|
202
|
-
|
|
236
|
+
(From source, use `node src/cli.mjs …`.)
|
|
237
|
+
|
|
238
|
+
</details>
|
|
239
|
+
|
|
240
|
+
When the defaults don't fit, for example a different socket path or forcing headless mode:
|
|
241
|
+
|
|
242
|
+
<details>
|
|
243
|
+
<summary>Environment variables</summary>
|
|
203
244
|
|
|
204
245
|
| Variable | Default | Meaning |
|
|
205
246
|
|---|---|---|
|
|
206
247
|
| `DSH_BATON_BACKEND` | `auto` | `auto`, `host` or `headless` |
|
|
207
248
|
| `DSH_BATON_HOME` | `~/.dsh-baton` | Socket and headless run records |
|
|
208
|
-
| `DSH_BATON_SOCKET` | `$DSH_BATON_HOME/host.sock` | Plugin socket path (must match on both sides); on Windows mapped to a per-user named pipe |
|
|
209
|
-
| `DSH_BATON_WAIT_S` | `
|
|
210
|
-
| `DSH_BATON_CODEX_HOOK` | `1` | `0` (set for Harness) stops the plugin adding the Codex Stop hook |
|
|
249
|
+
| `DSH_BATON_SOCKET` | `$DSH_BATON_HOME/host.sock` | Plugin socket path (must match on both sides); on Windows mapped to a per-user named pipe, see [WINDOWS.md](WINDOWS.md) |
|
|
250
|
+
| `DSH_BATON_WAIT_S` | Codex: its `tool_timeout_sec` for dsh-baton less 60 (3540 as the plugin sets it, else 270); others `50` | How long one `dsh_wait` call waits; keep it below the client's tool timeout |
|
|
211
251
|
| `DSH_BIN` | the `dsh` inside the macOS app, else `PATH` | Harness CLI for headless mode |
|
|
212
252
|
| `DSH_HOME` | `~/.dsh` | Harness data folder (headless session reads) |
|
|
213
253
|
| `DSH_BATON_ACCOUNT` | `1` | `0` uses the API-key route in headless mode |
|
|
214
254
|
| `DSH_BATON_PATCHES` | empty | Extra headless `--patch` overlays, `:`-separated |
|
|
215
255
|
|
|
256
|
+
</details>
|
|
257
|
+
|
|
258
|
+
When the Harness plugin is not reachable:
|
|
259
|
+
|
|
216
260
|
<details>
|
|
217
261
|
<summary>Headless fallback details</summary>
|
|
218
262
|
|
|
@@ -220,20 +264,26 @@ When the plugin is unreachable, the MCP server falls back to Harness's `dsh head
|
|
|
220
264
|
|
|
221
265
|
</details>
|
|
222
266
|
|
|
267
|
+
<p align="center"><picture><source media="(prefers-color-scheme: dark)" srcset="./assets/readme/en/divider-dark.svg"><img src="./assets/readme/en/divider.svg" width="100%" alt=""></picture></p>
|
|
268
|
+
|
|
223
269
|
## Install details
|
|
224
270
|
|
|
271
|
+
When you update or remove the plugin, come from dsh-bridge, run from source, or the plugin could not register:
|
|
272
|
+
|
|
225
273
|
<details>
|
|
226
274
|
<summary>What the plugin does, updating, removing, upgrading from dsh-bridge, installing from source, Windows</summary>
|
|
227
275
|
|
|
228
276
|
**What the plugin does when switched on.** It copies the MCP server to `~/.dsh-baton/app`, a folder that stays put, and writes the MCP entry into `~/.claude.json` and `~/.codex/config.toml` directly, keeping a `*.bak-dsh-baton` backup of each. It starts the server with your own Node.js ≥ 22.15 when it finds one on `PATH`; without one, with Harness's own runtime (the Harness app in Node mode, `ELECTRON_RUN_AS_NODE=1`), so nothing else has to be installed. Either way it works with only the desktop apps installed, when `claude` / `codex` are not on your `PATH`. It runs again on each Harness start: an entry that is already right, or a working one that starts another copy of dsh-baton, is left alone. In Harness, the source switches to the npm registry ("Official npm registry", 「npm 官方源」) by itself once you type the package name, and no restart is needed. To turn the registration off, set `DSH_BATON_AUTO_REGISTER=0` for Harness.
|
|
229
277
|
|
|
230
|
-
**
|
|
278
|
+
**Codex's tool timeout.** Codex stops an MCP tool call after 300 s unless the server's table sets `tool_timeout_sec`. The plugin writes `tool_timeout_sec = 3600` into `[mcp_servers.dsh-baton]` in `~/.codex/config.toml`, and adds it to an existing table that has none; a value you set yourself is kept. The server reads it and makes each `dsh_wait` that long less 60 s. Codex reads the setting when a conversation starts and keeps it: new conversations get it without restarting Codex, while conversations already open keep Codex's 300 s limit, so dsh-baton, which tells them apart by when they started (`~/.dsh-baton/codex-timeout.json` holds when the value was written), keeps their waits at 270 s.
|
|
279
|
+
|
|
280
|
+
**Updating to 0.6.4.** Nothing to restart, approve or set. Updating the plugin in Harness installs the new server into `~/.dsh-baton/app` and writes the timeout; Codex's running server picks up the new version on its next call (it checks for a newer copy before each `tools/list` and `tools/call`). New conversations wait up to 59 minutes per call; conversations already open go on as before, with 270 s waits. The Stop hook that plugins 0.6.0 to 0.6.3 added is taken out by itself, together with its trust record; there is nothing to untick in Codex. New conversations, and every conversation after Codex restarts, have no hook at all.
|
|
231
281
|
|
|
232
|
-
**Updates need no restart.** When a newer version lands in `~/.dsh-baton/app` (a plugin update, `setup`, or a copy by hand), or the same version with changed files, conversations already open in Claude Code and Codex use it from their next `dsh_*` call: the server checks the folder before each call, starts the new version, and says once in that call's result that it was updated. A `dsh_wait` that is already running finishes on the old version first. If the new version cannot start, the old one keeps working and the result says why. A tool added in the new version shows up in Claude Code at once (the server tells the client its tool list changed); Codex keeps the tool list a conversation started with, so it does not show a new tool until the next conversation;
|
|
282
|
+
**Updates need no restart.** When a newer version lands in `~/.dsh-baton/app` (a plugin update, `setup`, or a copy by hand), or the same version with changed files, conversations already open in Claude Code and Codex use it from their next `dsh_*` call: the server checks the folder before each call, starts the new version, and says once in that call's result that it was updated. A `dsh_wait` that is already running finishes on the old version first. If the new version cannot start, the old one keeps working and the result says why. A tool added in the new version shows up in Claude Code at once (the server tells the client its tool list changed); Codex keeps the tool list a conversation started with, so it does not show a new tool until the next conversation; it can still use one at once through `dsh_call`, which the update note points to, and the tools it already has run the new code right away.
|
|
233
283
|
|
|
234
284
|
**`npx -y dsh-baton-mcp setup`** does the same registration from a terminal: for a plugin that could not register, or when you come from an MCP directory. With the plugin already registered it changes nothing, then points you to the plugin if it is missing.
|
|
235
285
|
|
|
236
|
-
**Updating.** Harness has an update button only for its official plugins, so: Plugins → dsh-baton-host → **Uninstall**, then **Add plugin** → `dsh-baton-host`. For a while after a release, Harness installs the previous version instead (pnpm's `minimumReleaseAge` holds back versions published very recently, and the install dialog says so); to get the new one at once, type the version: `dsh-baton-host@0.6.
|
|
286
|
+
**Updating.** Harness has an update button only for its official plugins, so: Plugins → dsh-baton-host → **Uninstall**, then **Add plugin** → `dsh-baton-host`. For a while after a release, Harness installs the previous version instead (pnpm's `minimumReleaseAge` holds back versions published very recently, and the install dialog says so); to get the new one at once, type the version: `dsh-baton-host@0.6.4`. A pre-release must always be added by its exact version, such as `dsh-baton-host@0.6.0-next.0`: Harness resolves `@next` to a broken placeholder. Plain `dsh-baton-host` gets the latest release. Switched on again, the plugin brings the MCP server to the same version; new conversations use it. If the two are ever out of step, the first tool call that notices it says so, naming the older side and the newer side's exact version to install.
|
|
237
287
|
|
|
238
288
|
**Removing.** Harness → Plugins → dsh-baton-host → **Uninstall**, then `npx -y dsh-baton-mcp setup --remove`. The plugin cannot tell an uninstall from Harness quitting, so it leaves the MCP entries to that command, which also deletes `~/.dsh-baton/app`; run records stay in `~/.dsh-baton` until you delete it.
|
|
239
289
|
|
|
@@ -243,6 +293,10 @@ When the plugin is unreachable, the MCP server falls back to Harness's `dsh head
|
|
|
243
293
|
|
|
244
294
|
**Windows.** Same steps; [WINDOWS.md](WINDOWS.md) covers what differs (a named pipe instead of a socket file) and fixes for a Plugins page that cannot install or uninstall.
|
|
245
295
|
|
|
296
|
+
</details>
|
|
297
|
+
|
|
298
|
+
When you register by hand, or want dsh-baton in the Claude desktop chat app (not Claude Code):
|
|
299
|
+
|
|
246
300
|
<details>
|
|
247
301
|
<summary>Manual registration and the Claude desktop app</summary>
|
|
248
302
|
|
|
@@ -263,21 +317,21 @@ codex mcp add dsh-baton -- "$(command -v node)" "$PWD/dsh-baton/src/server.mjs"
|
|
|
263
317
|
|
|
264
318
|
</details>
|
|
265
319
|
|
|
266
|
-
|
|
320
|
+
<p align="center"><picture><source media="(prefers-color-scheme: dark)" srcset="./assets/readme/en/divider-dark.svg"><img src="./assets/readme/en/divider.svg" width="100%" alt=""></picture></p>
|
|
267
321
|
|
|
268
322
|
## Security and limits
|
|
269
323
|
|
|
270
324
|
<p align="center">
|
|
271
|
-
<img src="./assets/readme/security.svg" width="100%" alt="Owner-only channel (socket 0600 on macOS and Linux, per-user named pipe on Windows), no network port, Harness sandbox and approvals apply">
|
|
325
|
+
<picture><source media="(prefers-color-scheme: dark)" srcset="./assets/readme/en/security-dark.svg"><img src="./assets/readme/en/security.svg" width="100%" alt="Owner-only channel (socket 0600 on macOS and Linux, per-user named pipe on Windows), no network port, Harness sandbox and approvals apply"></picture>
|
|
272
326
|
</p>
|
|
273
327
|
|
|
274
328
|
<p align="center">
|
|
275
|
-
<img src="./assets/readme/limits.svg" width="100%" alt="Good to know: a message typed in the UI mid-run is flagged on the run as a human interjection, run records survive a Harness restart (cut-short runs show interrupted), Claude Code
|
|
329
|
+
<picture><source media="(prefers-color-scheme: dark)" srcset="./assets/readme/en/limits-dark.svg"><img src="./assets/readme/en/limits.svg" width="100%" alt="Good to know: a message typed in the UI mid-run is flagged on the run as a human interjection, run records survive a Harness restart (cut-short runs show interrupted), Claude Code is woken once when a run ends, Codex waits up to 59 minutes in one call"></picture>
|
|
276
330
|
</p>
|
|
277
331
|
|
|
278
332
|
Any process running as your OS user can drive Harness through the socket, the same as running `dsh` directly. dsh-baton relies on Harness 0.2.1-series internal service APIs, so a major Harness update may need a follow-up release.
|
|
279
333
|
|
|
280
|
-
<p align="center"><
|
|
334
|
+
<p align="center"><picture><source media="(prefers-color-scheme: dark)" srcset="./assets/readme/en/divider-dark.svg"><img src="./assets/readme/en/divider.svg" width="100%" alt=""></picture></p>
|
|
281
335
|
|
|
282
336
|
## License
|
|
283
337
|
|