token-harness 0.1.0 → 0.1.2

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.
Files changed (4) hide show
  1. package/README.md +577 -236
  2. package/package.json +1 -1
  3. package/sbom.json +5 -5
  4. package/token-harness.mjs +1756 -275
package/README.md CHANGED
@@ -1,241 +1,611 @@
1
1
  # Token Harness
2
2
 
3
- > One control plane for token-efficient coding agents.
3
+ Token Harness has one objective: **reduce the tokens consumed by coding agents without hiding
4
+ useful information or overstating the result**.
4
5
 
5
- Token Harness is an open-source orchestrator for token-saving tools used by coding
6
- agents. It detects the active coding harness, installs compatible optimization
7
- providers, prevents conflicting integrations, verifies that the resulting pipeline
8
- works, and reports savings through one normalized metrics model.
6
+ Coding sessions repeatedly send test logs, command output, repository context, MCP schemas,
7
+ tool results, and conversation history back to the model. Specialized tools can reduce each of
8
+ those sources, but installing them independently creates a second problem: overlapping hooks,
9
+ double reduction, incompatible configurations, and savings counted more than once.
9
10
 
10
- Token Harness is not another compressor. It coordinates specialized projects at
11
- different layers of the agent pipeline. This is the current integration landscape;
12
- "candidate" means researched, not supported or installed by this release.
11
+ Token Harness is the control plane for that optimization stack. It finds the coding agents and
12
+ token-saving tools on the machine, selects a compatible owner for each interception point, shows
13
+ every proposed change before applying it, verifies whether the integration is genuinely being
14
+ used, and reports how many tokens or characters were saved.
13
15
 
14
- | System | Layer and added value | Token Harness state |
16
+ The reduction still happens inside specialized providers such as RTK and HarnessTrim. Token
17
+ Harness makes those providers safe to combine, observable, reversible, and comparable.
18
+
19
+ ## Optimization ecosystem
20
+
21
+ The long-term goal is to coordinate token savings across the whole coding-agent pipeline. Only
22
+ tools marked **active** are integrated in this release; every other row is a candidate and is
23
+ neither installed nor configured by Token Harness.
24
+
25
+ | Tool | Optimization layer | Token Harness status |
15
26
  | --- | --- | --- |
16
- | [RTK](https://github.com/rtk-ai/rtk) | Command rewriting and shell-output reduction | **Integrated today** for Claude Code |
17
- | [HarnessTrim](https://github.com/giuliastro/HarnessTrim) | Deterministic reducers, harness adapters, skills, pipes, and MCP integration | **MVP provider in progress**: detection, adoption, conflict reconciliation, and metrics |
18
- | [Dejavu](https://github.com/Salnika/dejavu) | Emits only the delta when a command produces repeated output | Priority candidate; requires an RTK ordering fixture and native-Windows work |
19
- | [Lazy MCP](https://github.com/voicetreelab/lazy-mcp) | Loads MCP tool schemas only when the agent needs them | Priority, largely orthogonal candidate |
20
- | [repowise](https://github.com/repowise-dev/repowise) | Retrieves task-shaped repository context instead of repeated grep/read loops | Priority candidate; response bounds and attribution must be verified |
21
- | [LiteLLM](https://github.com/BerriAI/litellm) | Self-hosted model gateway, fallbacks, load balancing, budgets, and usage telemetry | Routing foundation candidate; it does not by itself prove token savings |
22
- | [RouteLLM](https://github.com/lm-sys/RouteLLM) | Routes easier requests to a cheaper model through an OpenAI-compatible endpoint | Learned-routing candidate; needs coding-agent quality benchmarks |
23
- | [vLLM Semantic Router](https://github.com/vllm-project/semantic-router) | Routes by task, complexity, tools, and deployment locality for self-hosted inference | Alternative routing candidate for local inference fleets |
24
- | [Headroom](https://github.com/headroomlabs-ai/headroom) | Compresses tool, MCP, file, and RAG payloads and can lower effort on routine turns | Broad-context candidate; alternative to Context Mode, with overlap tests required |
25
- | [Context Mode](https://github.com/mksglu/context-mode) | Keeps raw tool/MCP results outside context and restores compact session memory | Broad-context candidate; alternative to Headroom, source-available under ELv2 |
26
- | [LLMLingua](https://github.com/microsoft/LLMLingua) | Model-based prompt compression engine for long context | Engine candidate, not yet a direct harness adapter |
27
- | [Caveman](https://github.com/JuliusBrussee/caveman) | Steers shorter visible model replies | Opt-in candidate; output savings only, with quality and prompt-overhead checks |
28
-
29
- The evidence, licenses, conflicts, and recommended admission order are recorded in the
30
- [provider landscape](docs/provider-landscape.md). Routing savings are reported as cost or
31
- quality trade-offs, never silently added to exact token savings.
32
-
33
- Upstream tools remain independent. Token Harness installs supported releases through
34
- their official distribution channels and never silently vendors or forks them.
35
-
36
- ## Product identity
37
-
38
- | Surface | Value |
39
- | --- | --- |
40
- | Product name | Token Harness |
41
- | Repository/package slug | `token-harness` |
42
- | CLI command | `token-harness` |
43
- | License | Apache-2.0 |
44
- | Runtime | Node.js 22.13.0+ |
45
- | Language | TypeScript |
46
- | Package manager | pnpm |
47
-
48
- ## Core principles
49
-
50
- 1. **Plan before apply.** Every mutation is represented as a reviewable plan. Dry-run
51
- is the default, and no flag skips planning.
52
- 2. **One owner per interception surface.** The planner prevents two providers from
53
- rewriting or compressing the same payload unless that exact chain is validated — and
54
- it keeps checking after installation, because config files keep changing.
55
- 3. **Upstreams stay upstream.** Providers wrap official installers and APIs instead
56
- of copying their implementations.
57
- 4. **Measured, not marketed.** Exact, estimated, and counterfactual savings are
58
- reported separately and never summed into one headline number.
59
- 5. **Proven, not assumed.** Verification states its tier: presence, config-only, or an
60
- observed canary. A configuration that looks correct is never presented as proof that
61
- the harness reaches the provider.
62
- 6. **Reversible by construction.** Configuration edits are marker-owned, backed up,
63
- journaled, and removable.
64
- 7. **Local-first.** No account or telemetry is required. Usage data stays local unless
65
- the user explicitly enables an upstream service.
66
- 8. **Cross-platform.** Windows, macOS, Linux, and WSL are first-class targets, with
67
- unsupported combinations surfaced before installation.
68
-
69
- ## Initial user experience
27
+ | [RTK](https://github.com/rtk-ai/rtk) | Shell-command rewriting and command-output reduction | **Active — integrated** |
28
+ | [HarnessTrim](https://github.com/giuliastro/HarnessTrim) | Deterministic reducers, harness adapters, skills, pipes, and MCP reduction | **Active — integrated** |
29
+ | [Dejavu](https://github.com/Salnika/dejavu) | Emit only the delta when command output repeats | Not active — candidate |
30
+ | [Lazy MCP](https://github.com/voicetreelab/lazy-mcp) | Load MCP tool schemas only when needed | Not active — candidate |
31
+ | [repowise](https://github.com/repowise-dev/repowise) | Retrieve task-specific repository context | Not active — candidate |
32
+ | [LiteLLM](https://github.com/BerriAI/litellm) | Model routing, fallbacks, budgets, and usage telemetry | Not active — candidate |
33
+ | [RouteLLM](https://github.com/lm-sys/RouteLLM) | Route simpler requests to less expensive models | Not active — candidate |
34
+ | [vLLM Semantic Router](https://github.com/vllm-project/semantic-router) | Route by task, complexity, tools, and deployment locality | Not active — candidate |
35
+ | [Claude Code Router](https://github.com/musistudio/claude-code-router) | Route coding-agent requests across models and providers with effort-based rules and fallback chains | Not active — candidate · high priority |
36
+ | [LLMRouter](https://github.com/ulab-uiuc/LLMRouter) | Select the model by task complexity, cost, and quality across routing strategies | Not active — candidate · high priority |
37
+ | [Headroom](https://github.com/headroomlabs-ai/headroom) | Compress tool, MCP, file, and RAG payloads | Not active — candidate |
38
+ | [Context Mode](https://github.com/mksglu/context-mode) | Keep raw tool results outside model context | Not active — candidate |
39
+ | [LLMLingua](https://github.com/microsoft/LLMLingua) | Compress long prompts and context | Not active — candidate |
40
+ | [Caveman](https://github.com/JuliusBrussee/caveman) | Reduce visible model-output verbosity | Not active — candidate |
41
+
42
+ Candidate status means only that the project has identified a useful optimization layer. A tool
43
+ becomes active only after its installation, conflicts, rollback behavior, verification, and
44
+ metrics attribution have been implemented and tested. Token Harness never installs a candidate
45
+ merely because it is present on the machine. Rows marked `high priority` are the next intended
46
+ intake; the admission gates each one carries are recorded in
47
+ [docs/provider-landscape.md](docs/provider-landscape.md).
48
+
49
+ ## Quick start
50
+
51
+ Install the CLI:
52
+
53
+ ```sh
54
+ npm install --global token-harness
55
+ token-harness --version
56
+ ```
70
57
 
71
- ```text
58
+ Then run the complete workflow from the project in which you use your coding agent:
59
+
60
+ ```sh
61
+ # 1. Inspect the machine. This does not change agent configuration.
72
62
  token-harness doctor
63
+
64
+ # 2. Preview every proposed change.
73
65
  token-harness plan
66
+
67
+ # 3. Apply the reviewed plan. This is the first configuration-changing step.
74
68
  token-harness apply --yes
69
+
70
+ # 4. Restart the coding agent, then run a normal shell command through it.
71
+
72
+ # 5. Check configuration, real interception evidence, and savings.
73
+ token-harness status
75
74
  token-harness verify
76
75
  token-harness metrics --since 7d
77
- token-harness status
78
- token-harness rollback --yes
79
76
  ```
80
77
 
81
- Existing installations are adopted, not replaced. If RTK or HarnessTrim is already
82
- configured by hand, Token Harness detects it, plans around it, and leaves it in place on
83
- uninstall.
78
+ `doctor` ends with a `NEXT` section. If you are unsure what to do, run the command shown
79
+ there.
80
+
81
+ To try the read-only diagnosis without installing Token Harness globally:
82
+
83
+ ```sh
84
+ npx token-harness doctor
85
+ ```
84
86
 
85
- `0.1.0` supports Codex, Claude Code, and OpenCode. RTK is managed end to end: detected,
86
- configured, verified, measured. HarnessTrim is detected, adopted, reconciled against RTK's
87
- ownership, and measured — but not installed, because at its current release no configuration
88
- exists that would let both tools reduce output without contesting the same surface. Token
89
- Harness reports that contest instead of hiding it.
87
+ `npx` may download Token Harness into npm's cache, but it does not install or configure RTK,
88
+ HarnessTrim, or a coding agent.
90
89
 
91
- Additional tools, and joint reduction by two providers, are introduced only after
92
- compatibility and attribution tests prove they compose safely.
90
+ ### Managed compatibility rows
93
91
 
94
- ## Status
92
+ Token Harness changes a harness configuration only when a reviewed compatibility row covers the
93
+ exact provider version, harness version, platform, and configuration schema. Two rows ship, and each
94
+ names the recording it stands on:
95
95
 
96
- **Version `0.1.0`.** PLAN §16 defines that number as: RTK and HarnessTrim, three harnesses,
97
- transactional install, verification with declared tiers, metrics, and brownfield adoption. All
98
- of it is here, and a test refuses the version string unless the registries and the command
99
- surface actually back it.
96
+ | Provider | Harness | Platform | Tested versions | Tier |
97
+ | --- | --- | --- | --- | --- |
98
+ | RTK | Claude Code | Windows | rtk 0.44.0, Claude Code 2.1.220 | `canary` |
99
+ | HarnessTrim | Claude Code | Windows | harnesstrim 0.1.0, Claude Code 2.1.220 | `config-only` |
100
100
 
101
- ### The nine criteria
101
+ Everything else is refused, and that is the design rather than a gap: `doctor` detects and reports on
102
+ every supported platform, and only the *mutation* is narrower. An uncovered combination exits 9 and
103
+ the diagnostic names what is missing — the reviewed fixture, or the nearest row it does have.
102
104
 
103
- PLAN §2 lists what makes `0.1.0` useful. Measured, not estimated:
105
+ What is not covered today, and why:
104
106
 
105
- | # | Criterion | State |
107
+ - **macOS and Linux.** No row on either. The recordings a row needs are states of a real machine, and
108
+ a fixture cannot be written from a machine nobody ran. On those platforms `plan` and `apply` refuse;
109
+ install the provider with its own installer and Token Harness will detect, verify, and measure it.
110
+ - **Codex and OpenCode.** Both providers are detected and adopted there, and neither is written:
111
+ RTK's plan builder produces a Claude-shaped hook list, and HarnessTrim's reviewed write set covers
112
+ Claude only. A row would admit a mutation that nothing proposes.
113
+ - **A newer Claude Code.** The range is a single observed version. `2.1.221` reads `unknown-newer` and
114
+ refuses rather than assuming it behaves like `2.1.220`.
115
+
116
+ The recordings are under `tests/fixtures/rows/`, one directory per row, each with a README stating
117
+ which stages exist and which do not.
118
+
119
+ ## How the components fit together
120
+
121
+ There are three separate layers. Installing one does not automatically provide the others.
122
+
123
+ | Layer | Examples | Who installs it? |
106
124
  | --- | --- | --- |
107
- | 1 | `doctor` detects Codex, Claude Code, or OpenCode | **done** — all three |
108
- | 2 | RTK and HarnessTrim: available, installed, configured, broken | **done** |
109
- | 3 | Dry-run plan for a compatible setup | **done** |
110
- | 4 | Apply that plan transactionally | **done** |
111
- | 5 | Verify the integration, with the tier stated | **done** |
112
- | 6 | Inspect normalized savings | **done** — both providers |
113
- | 7 | Uninstall or roll back without damage | **done** |
114
- | 8 | Adopt an existing hand-configured installation | **done** — both providers |
115
- | 9 | Windows, macOS, Linux | **done** — CI on all three, every commit |
116
-
117
- ### What it looks like on a real machine
125
+ | Coding agent (harness) | Claude Code, Codex, OpenCode | You, using the agent's official installer |
126
+ | Token Harness | `token-harness` | You, from npm or this repository |
127
+ | Optimization provider | RTK, HarnessTrim | Both can be installed by Token Harness where a compatibility row covers the combination; otherwise install them with their own installers and Token Harness detects and measures them |
118
128
 
119
- ```text
120
- $ token-harness doctor
121
- Harnesses
122
- claude configured ~/.claude/settings.json
123
- codex configured ~/.codex/config.toml
124
- opencode detected ~/.config/opencode/opencode.jsonc
125
-
126
- Providers
127
- rtk configured 0.42.0 configured for claude (adopted, not managed)
128
- harnesstrim configured configured for codex (adopted, not managed)
129
+ Token Harness does not install Claude Code, Codex, or OpenCode. Install and run at least one of
130
+ them first so that `token-harness doctor` can detect it.
131
+
132
+ | Provider | Claude Code | Codex | OpenCode | Installed by Token Harness |
133
+ | --- | --- | --- | --- | --- |
134
+ | RTK | Configure, verify, and measure | Not managed | Detect, adopt, verify, and measure | **Yes**, for the supported Claude Code path |
135
+ | HarnessTrim | Claude skills only; no reducer hook or reduce-pipe instruction | Detect, adopt, verify, and measure | Detect, adopt, verify, and measure | **Yes**, on a covered row — see above |
136
+
137
+ "Not managed" does not mean the upstream tool cannot support that agent. It means this release
138
+ does not claim ownership of that integration and will not modify it.
139
+
140
+ RTK on OpenCode is detected and verified, not written: `rtk init -g --opencode` installs a plugin
141
+ module at `~/.config/opencode/plugins/rtk.ts`, and Token Harness reads that file rather than
142
+ producing it. Note that the plugin is inert under OpenCode Desktop — see
143
+ [docs/matrices.md](docs/matrices.md) for what was measured.
144
+
145
+ The generated compatibility tables, tested version ranges, platform coverage, and known
146
+ limitations are in [docs/matrices.md](docs/matrices.md).
147
+
148
+ ## Installing each component
149
+
150
+ ### 1. Install Token Harness
151
+
152
+ Recommended, from npm:
153
+
154
+ ```sh
155
+ npm install --global token-harness
156
+ token-harness --help
129
157
  ```
130
158
 
131
- ```text
132
- $ token-harness verify
133
- rtk — claude — adopted, not managed — declared tier: canary
134
- pass canary-intercepted 494 commands intercepted on 2026-07-31
135
- harnesstrim — codex — adopted, not managed — declared tier: config-only
136
- not-exercised canary-intercepted no telemetry file exists, so no interception has been recorded
159
+ If the command is not found after installation, find npm's global binary directory with:
160
+
161
+ ```sh
162
+ npm prefix --global
137
163
  ```
138
164
 
139
- That second line is the point of the whole verification model: the hook is correctly
140
- configured, and it has never run. RFC 0007 exists because "configured" and "working" are
141
- different claims, and `not-exercised` is neither a pass nor a failure.
165
+ Ensure that directory's executable location is on `PATH`, then open a new terminal.
142
166
 
143
- `metrics` on the same machine reports **91,600 tokens saved over 2,847 intercepted
144
- commands** — exactly what `rtk gain` reports independently.
167
+ #### Build and install from source
145
168
 
146
- ### The full command surface
169
+ The repository uses the pnpm version declared in `package.json`.
147
170
 
148
- ```text
149
- token-harness doctor what is here, and what is broken
150
- token-harness plan what would change; nothing is written
151
- token-harness apply --yes write it, inside a reversible transaction
152
- token-harness verify is it actually intercepting, at which tier
153
- token-harness metrics --since 7d what it saved, by measurement class
154
- token-harness status drift, and competing hooks on owned surfaces
155
- token-harness uninstall --yes remove only what Token Harness owns
156
- token-harness rollback --yes restore the files a transaction changed
157
- token-harness update what a newer version would be, per channel
171
+ ```sh
172
+ git clone https://github.com/giuliastro/token-harness.git
173
+ cd token-harness
174
+ corepack enable
175
+ pnpm install
176
+ pnpm build
177
+ pnpm package
178
+ npm install --global ./dist/package
179
+ token-harness --version
158
180
  ```
159
181
 
160
- That is all nine commands RFC 0001 declares. `update` was the last one missing.
161
-
162
- It asks each provider's own installation channel what version it offers and compares that with
163
- what is installed — the installed side comes from the provider, the available side from the
164
- channel, because `winget` knows what exists for `rtk-ai.rtk` and RTK's adapter does not. Reaching
165
- the channel is a network read and it happens on a dry run too, since a target version cannot be
166
- named without asking, so the destinations are reported.
167
-
168
- It updates and nothing else. A provider that is not installed is left alone, a channel offering
169
- something older is not acted on, and a channel that cannot be read produces *unknown* rather than
170
- the far more comfortable *up to date*. A pinned provider is skipped and its pin is named; a pin
171
- written inside a repository is reported and not honored, because a repository may not choose which
172
- version of a tool you run.
173
-
174
- And the honest limit, printed rather than implied: an updated package is not restored by a
175
- rollback. Rollback restores files, and a package is not a file.
176
-
177
- ### Guarantees worth knowing before you run `apply`
178
-
179
- - **Dry-run by default.** Without `--yes`, mutating commands display the plan and exit 8.
180
- - **One appended entry, not a rewritten list.** Your other hooks keep their content and their
181
- order; a test asserts your entry is still first afterwards.
182
- - **Every file is snapshotted first**, including files that did not exist, so a rollback can
183
- restore their absence. The restoration is verified by reading the files back — which is what
184
- separates exit 6 (rolled back) from exit 7 (did not fully restore).
185
- - **Token Harness removes only what a committed journal records as its own.** Not what merely
186
- looks like its own: an entry whose bytes match what it would have written is still yours if
187
- it did not write it, and `uninstall` says so and declines.
188
- - **A change you did not ask for is reported.** Editing a hand-formatted JSON file reformats
189
- it, and that warning reaches you rather than only the journal.
190
- - **A competing hook on an owned surface is reported, never removed.** `status` names the file,
191
- the surface, and the competing command, and exits 3.
192
-
193
- ### What is honest about the limits
194
-
195
- - **HarnessTrim is never installed**, by design rather than omission. RFC 0003 §Resolution at
196
- 0.1.0 checked its installer at `0.0.5` and found no configuration that lets it and RTK reduce
197
- output without contesting the same surface. So it is detected, adopted, reconciled, and
198
- measured — and left alone. Under `profile: custom` you may hand it the scope instead of RTK.
199
- - **An installed package cannot be rolled back.** `apply` can now run a package manager, but a
200
- package is not a file and there is no snapshot of one, so a later failure restores your files and
201
- leaves the package installed. The report says so rather than letting "rolled back" imply the
202
- machine is as it was. Elevation is refused outright, with the exact command to run yourself.
203
- - **A provider that cannot report its version is still adopted.** Older HarnessTrim builds reject
204
- `--version`; Token Harness asks, falls back, and reports the tool as installed with no version
205
- rather than as missing. It never reads the reachable `package.json`, which names the monorepo
206
- rather than the CLI.
207
- - **Codex hooks cannot be proven to run.** Enablement and trust are persisted separately from
208
- `hooks.json`, in state no adapter can read, so Codex tops out at `config-only` and says why.
209
- - **Two measurement findings that change how a number reads.** 75% of RTK's interceptions save
210
- nothing, and RTK sometimes makes output *larger* while flooring its own counter at zero — so
211
- its total is a sum of clamped values. Token Harness reports the net effect and names the
212
- inflation separately.
213
-
214
- ### Installing 0.1.0
215
-
216
- A single self-contained ESM artifact with **no dependencies at all**. Not on npm — publishing
217
- is PLAN §8.3, with provenance, SBOM, and signing — but it installs from a tarball you build
218
- yourself, and CI proves that on Windows, macOS, and Linux on every commit:
219
-
220
- ```bash
221
- pnpm install && pnpm build && pnpm package
222
- npm install -g ./dist/package
182
+ `pnpm build` creates the self-contained CLI at `dist/bundle/token-harness.mjs`.
183
+ `pnpm package` creates the installable package under `dist/package`.
184
+ If `corepack` is unavailable, install the pinned package manager with
185
+ `npm install --global pnpm@10.33.4` instead.
186
+
187
+ ### 2. Install or adopt RTK
188
+
189
+ When a reviewed compatibility row covers the installed versions, you normally do **not** install RTK yourself:
190
+
191
+ ```sh
192
+ token-harness plan --harness claude --provider rtk
193
+ ```
194
+
195
+ Once a matching compatibility row exists, if RTK is absent, the plan contains two actions:
196
+
197
+ 1. install RTK through the selected package manager;
198
+ 2. append one RTK entry to Claude Code's `PreToolUse` hook configuration.
199
+
200
+ The channel selected by this release is:
201
+
202
+ | Platform | Channel used by the plan | Required command on `PATH` |
203
+ | --- | --- | --- |
204
+ | Windows | WinGet package `rtk-ai.rtk` | `winget` |
205
+ | macOS | Cargo package `rtk` | `cargo` |
206
+ | Linux and WSL | Cargo package `rtk` | `cargo` |
207
+
208
+ The Cargo path in this release invokes `cargo install rtk`. That channel is declared but has not
209
+ been exercised by this project, and upstream documents a crates.io name collision. On macOS,
210
+ Linux, and WSL, the safer current route is to install RTK with an upstream-recommended method,
211
+ confirm that `rtk gain` works, and let Token Harness adopt and configure the existing binary.
212
+
213
+ Review the plan's `Network`, `Elevation`, and `Actions` sections before applying it:
214
+
215
+ ```sh
216
+ token-harness apply --yes --harness claude --provider rtk
217
+ ```
218
+
219
+ If RTK is already installed and configured, Token Harness adopts it instead of reinstalling or
220
+ rewriting it. User-owned configuration remains user-owned.
221
+
222
+ Important boundaries:
223
+
224
+ - Token Harness writes the reviewed hook itself; it does not run `rtk init`.
225
+ - A package install is not reversed by file rollback. `rollback` restores configuration files,
226
+ not installed binaries.
227
+ - `uninstall` removes only integration entries written by Token Harness; it deliberately leaves
228
+ the RTK executable installed.
229
+ - On native Windows, Claude Code exposes both Bash and PowerShell tool families. The current RTK
230
+ matcher covers Bash only, so `doctor` can correctly report PowerShell as bypassed.
231
+
232
+ For manual installation or use outside Token Harness's managed surface, follow the
233
+ [RTK installation guide](https://github.com/rtk-ai/rtk/blob/master/INSTALL.md), then run:
234
+
235
+ ```sh
236
+ rtk --version
237
+ rtk gain
238
+ token-harness doctor --provider rtk
239
+ ```
240
+
241
+ `rtk gain` is an important identity check because another unrelated package also uses the name
242
+ `rtk`.
243
+
244
+ ### 3. Install or adopt HarnessTrim
245
+
246
+ With HarnessTrim on `PATH`, `token-harness plan --harness claude` can install its Claude skills
247
+ without creating the competing Bash hook or reduce-pipe instruction. The invocation it delegates to
248
+ is:
249
+
250
+ ```sh
251
+ harnesstrim install claude <project> --apply --no-hook --no-instructions
252
+ ```
253
+
254
+ Codex and OpenCode remain adoption-only. Install those integrations with HarnessTrim's own CLI,
255
+ first as a dry run and then with its explicit apply flag. Consult the
256
+ [HarnessTrim README](https://github.com/giuliastro/HarnessTrim#quick-start) because its adapter
257
+ contents, modes, and telemetry differ by coding agent.
258
+
259
+ After installing it:
260
+
261
+ ```sh
262
+ token-harness doctor --provider harnesstrim
263
+ token-harness status --provider harnesstrim
264
+ token-harness verify --provider harnesstrim
265
+ token-harness metrics --provider harnesstrim --since 7d
266
+ ```
267
+
268
+ Do not configure RTK and HarnessTrim to reduce the same shell output. In the `safe` profile,
269
+ Token Harness gives that exclusive surface to RTK and treats an existing overlap as a hard
270
+ conflict instead of guessing an execution order. It never deletes the competing entry for you.
271
+
272
+ HarnessTrim telemetry is opt-in in some adapters. Without a `.harnesstrim/metrics.jsonl` file,
273
+ verification can still inspect configuration, but `metrics` has no HarnessTrim events to import.
274
+
275
+ From `0.1.0`, HarnessTrim publishes a machine-readable capability declaration: the surfaces it
276
+ intercepts per coding agent, the flags that narrow an install, and the paths each install writes.
277
+
278
+ ```sh
279
+ harnesstrim capabilities
280
+ ```
281
+
282
+ Detection reads that declaration and compares it against the one Token Harness records, so an
283
+ upstream change is reported rather than assumed compatible. A disagreement becomes a
284
+ `provider-capabilities-drift` warning naming both sides. A build older than the command cannot
285
+ answer; Token Harness then falls back to its own recorded declaration and reports nothing, because a
286
+ provider that cannot be asked must still be describable.
287
+
288
+ ## The recommended operating workflow
289
+
290
+ ### Step 1: diagnose
291
+
292
+ ```sh
223
293
  token-harness doctor
224
294
  ```
225
295
 
226
- To run it without installing:
296
+ This answers:
297
+
298
+ - which supported coding agents are installed;
299
+ - which providers are installed and runnable;
300
+ - which agent configuration files exist;
301
+ - which provider is wired to which agent;
302
+ - whether Token Harness owns the integration or merely adopted it;
303
+ - whether a version, configuration file, or tool-family matcher needs attention;
304
+ - whether the installed provider's own capability declaration still agrees with the one Token
305
+ Harness records.
306
+
307
+ Common states:
308
+
309
+ | State | Meaning |
310
+ | --- | --- |
311
+ | `not found` / `absent` | The executable and usable configuration were not detected |
312
+ | `installed` | The provider runs but is not connected to a supported agent |
313
+ | `configured` | A relevant hook or plugin entry exists |
314
+ | `broken` | Configuration refers to something missing or unreadable |
315
+ | `set up by you` | Token Harness adopted existing configuration and will not remove it |
316
+ | `set up by this tool` | A committed Token Harness transaction owns the exact entry |
317
+
318
+ `doctor` is diagnostic. An empty machine is a valid state and exits successfully.
319
+
320
+ ### Step 2: review the plan
321
+
322
+ ```sh
323
+ token-harness plan
324
+ ```
325
+
326
+ Narrow the operation when useful:
327
+
328
+ ```sh
329
+ token-harness plan --harness claude
330
+ token-harness plan --provider rtk
331
+ token-harness plan --project /path/to/project
332
+ ```
333
+
334
+ Read these sections before proceeding:
335
+
336
+ - `Capability ownership`: which provider is allowed to transform each surface;
337
+ - `Excluded`: detected providers intentionally left out;
338
+ - `Actions`: every package operation and file change;
339
+ - `Network`: destinations contacted by later mutation;
340
+ - `Elevation`: whether administrator/root access would be required;
341
+ - `Backups`: how many files will be snapshotted.
342
+
343
+ `plan` does not modify agent or project configuration. It may persist the serialized plan in
344
+ Token Harness's private state directory so the exact reviewed artifact can be applied later.
345
+
346
+ If the plan prints an ID, apply that exact plan with:
347
+
348
+ ```sh
349
+ token-harness apply --plan <plan-id> --yes
350
+ ```
351
+
352
+ The stored plan is rejected before any action runs if the project, versions, ownership, or file
353
+ preconditions changed after review.
354
+
355
+ ### Step 3: apply
356
+
357
+ ```sh
358
+ token-harness apply --yes
359
+ ```
360
+
361
+ Without `--yes`, `apply` shows what it would do and exits with code 8. Every affected file is
362
+ snapshotted before mutation, including the prior absence of a newly created file. A failure
363
+ triggers automatic restoration and the result states whether that restoration was verified.
364
+
365
+ After a successful apply, restart the coding agent so it reloads its hooks or plugins.
366
+
367
+ ### Step 4: create real traffic
368
+
369
+ Passive verification needs evidence from an operation that actually passed through the provider.
370
+ Open the configured coding agent and ask it to run a normal shell command such as `git status` or
371
+ a test command. Then return to the terminal.
372
+
373
+ ### Step 5: verify configuration and execution
374
+
375
+ Use both commands; they answer different questions:
376
+
377
+ ```sh
378
+ token-harness status
379
+ token-harness verify
380
+ ```
381
+
382
+ `status` compares the live environment with committed receipts. It finds drift, changed versions,
383
+ and competing entries on exclusive surfaces.
384
+
385
+ `verify` checks the strongest evidence the integration declares:
386
+
387
+ | Tier | What it proves |
388
+ | --- | --- |
389
+ | `presence` | The executable resolves and reports a version |
390
+ | `config-only` | The expected configuration entry exists |
391
+ | `canary` | Provider records show a real operation crossed the interception point |
392
+
393
+ `config-only` is not proof that the hook ran. It is the honest ceiling for integrations whose
394
+ runtime state cannot be observed externally.
395
+
396
+ `not-exercised` means no attributable operation has been observed yet. It is neither success nor
397
+ failure: run a command through the agent and check again.
398
+
399
+ ### Step 6: inspect savings
400
+
401
+ ```sh
402
+ token-harness metrics
403
+ token-harness metrics --since 24h
404
+ token-harness metrics --since 2026-07-01 --until 2026-08-01
405
+ token-harness metrics --provider rtk --since 7d
406
+ ```
407
+
408
+ The default window is seven days. Durations such as `12h`, `7d`, and `2w`, plus ISO dates, are
409
+ accepted. Date boundaries are midnight UTC.
410
+
411
+ The report keeps measurement types and units separate:
412
+
413
+ | Report line | Interpretation |
414
+ | --- | --- |
415
+ | `Exact local` | Before and after token counts were observed for the same operation |
416
+ | `Estimated local` | The payload changed, but the reported unit or tokenizer is an estimate |
417
+ | `Counterfactual` | A dry run measured what could have changed; it is not realized saving |
418
+ | `End-to-end billed` | Comparable billed sessions were measured; otherwise it says `no A/B run` |
419
+ | `Coverage` | Share of relevant operations that were actually changed |
420
+ | `Bypassed` | Operations observed but passed through unchanged or outside coverage |
421
+
422
+ Token counts are never added to character counts, and estimated or counterfactual values are never
423
+ silently merged into an exact total.
227
424
 
228
- ```bash
229
- node dist/bundle/token-harness.mjs doctor
425
+ The report covers one project: the one `--project` names, or the current directory. An operation a
426
+ provider recorded without a directory belongs to no project and is excluded, with a count reported
427
+ so the difference is reconcilable. When no project identity can be established the report says so
428
+ rather than presenting every project's events as one project's figures.
429
+
430
+ ## Undoing changes
431
+
432
+ Choose the command based on what you want to undo:
433
+
434
+ ```sh
435
+ # Remove only exact integration entries owned by Token Harness.
436
+ token-harness uninstall --yes
437
+
438
+ # Restore all files from the most recent committed transaction snapshot.
439
+ token-harness rollback --yes
230
440
  ```
231
441
 
232
- Every read-only command is safe to run first. `doctor`, `plan`, `status`, `verify` and
233
- `metrics` never touch a harness configuration, and `--project <dir>` retargets the
234
- project-scoped half if you want to watch it work against a scratch directory.
442
+ `uninstall` is usually the safer choice after subsequent manual edits: it is surgical and refuses
443
+ to remove an owned entry if its content no longer matches what Token Harness wrote.
444
+
445
+ `rollback` restores whole files to their pre-transaction bytes. Changes made to those files after
446
+ the transaction are therefore also reverted. It does not restore or remove provider packages.
447
+
448
+ Neither command removes user-owned RTK or HarnessTrim configuration.
449
+
450
+ ## Command reference
451
+
452
+ | Command | Purpose | Changes agent/project configuration? |
453
+ | --- | --- | --- |
454
+ | `doctor` | Detect agents, providers, ownership, and problems | No |
455
+ | `plan` | Resolve ownership and preview exact actions | No; stores the plan in private state |
456
+ | `apply` | Apply a plan transactionally | Yes, only with `--yes` |
457
+ | `status` | Detect drift and competing hooks | No |
458
+ | `verify` | Check the declared verification tier | No |
459
+ | `metrics` | Import provider records and report savings | No; updates only Token Harness state |
460
+ | `update` | Query channels and update installed providers | Yes, only with `--yes` |
461
+ | `rollback` | Restore files from the latest committed transaction | Yes, only with `--yes` |
462
+ | `uninstall` | Remove owned integration entries | Yes, only with `--yes` |
463
+
464
+ Every command supports `--help`. Common filters are:
465
+
466
+ ```text
467
+ --harness claude|codex|opencode
468
+ --provider rtk|harnesstrim
469
+ --project <directory>
470
+ --json
471
+ ```
472
+
473
+ ## Automation and JSON output
474
+
475
+ Use `--json` in scripts:
476
+
477
+ ```sh
478
+ token-harness doctor --json
479
+ token-harness verify --json
480
+ token-harness metrics --since 7d --json
481
+ ```
482
+
483
+ stdout contains exactly one JSON document with this top-level contract:
484
+
485
+ ```json
486
+ {
487
+ "schemaVersion": 1,
488
+ "command": "verify",
489
+ "toolVersion": "0.1.0",
490
+ "status": "ok",
491
+ "exitCode": 0,
492
+ "data": {},
493
+ "diagnostics": []
494
+ }
495
+ ```
496
+
497
+ Important exit codes:
498
+
499
+ | Code | Meaning |
500
+ | ---: | --- |
501
+ | 0 | Completed with nothing actionable |
502
+ | 2 | Invalid command or argument |
503
+ | 3 | A read-only check found an actionable problem |
504
+ | 4 | A capability conflict blocks the plan |
505
+ | 5 | The environment drifted from the stored plan or journal |
506
+ | 6 | Mutation failed and rollback was verified |
507
+ | 7 | Mutation failed and state was not fully restored; inspect the named paths |
508
+ | 8 | The command needs explicit confirmation (`--yes`) |
509
+ | 9 | Unsupported or unverifiable environment |
510
+
511
+ Do not treat every non-zero code as the same failure. In particular, code 8 is the expected result
512
+ of previewing a mutating command without approval.
513
+
514
+ ## State, backups, and privacy
515
+
516
+ Token Harness stores plans, journals, backups, receipts, import cursors, and normalized metrics
517
+ outside the repository:
518
+
519
+ | Platform | Default state root |
520
+ | --- | --- |
521
+ | Windows | `%LOCALAPPDATA%\TokenHarness` |
522
+ | macOS | `~/Library/Application Support/TokenHarness` |
523
+ | Linux and WSL | `${XDG_STATE_HOME:-~/.local/state}/token-harness` |
524
+
525
+ Normalized metrics do not contain raw command text, tool output, source code, prompts, credentials,
526
+ or raw file paths. Provider records are read in place; Token Harness imports only normalized event
527
+ data.
528
+
529
+ ## Troubleshooting
530
+
531
+ ### `token-harness` is not found
532
+
533
+ Confirm Node and the global npm installation:
534
+
535
+ ```sh
536
+ node --version
537
+ npm list --global token-harness
538
+ npm prefix --global
539
+ ```
540
+
541
+ Node must be at least 22.13.0. Add npm's global executable directory to `PATH`, then reopen the
542
+ terminal.
543
+
544
+ ### `plan` says there is nothing to do
545
+
546
+ Run `token-harness doctor`. The usual causes are:
547
+
548
+ - no supported coding agent was detected;
549
+ - the requested provider does not claim that coding agent in this release;
550
+ - an existing user-managed integration already satisfies the target state;
551
+ - the safe profile excluded an overlapping provider.
552
+
553
+ RTK is written only for Claude Code in 0.1.0. It claims OpenCode too, but the plan builder appends
554
+ a `hooks` entry, which is Claude Code's schema — OpenCode's integration is a plugin module, so an
555
+ OpenCode scope produces no action and the existing installation is adopted instead. A Codex-only
556
+ machine produces no RTK action at all.
557
+
558
+ ### The plan is blocked by `exclusive-scope-contested`
559
+
560
+ RTK and HarnessTrim both claim the same reducing surface. Token Harness will not choose an order or
561
+ overwrite either configuration. Remove or disable one integration using the tool that owns it, then
562
+ run `doctor` and `plan` again.
563
+
564
+ ### `verify` reports `not-exercised`
565
+
566
+ Restart the coding agent, ask it to run a shell command through the configured tool family, then
567
+ run `token-harness verify` again. For a `config-only` integration, no stronger external receipt may
568
+ exist; the output states that limitation explicitly.
569
+
570
+ ### `metrics` shows no data
571
+
572
+ Check all of the following:
573
+
574
+ - the provider has processed at least one operation in the requested time window;
575
+ - `rtk gain` works for RTK;
576
+ - HarnessTrim telemetry is enabled and `.harnesstrim/metrics.jsonl` exists for the project;
577
+ - `--project` points to the project whose records you expect;
578
+ - `--since` is not excluding older events.
579
+
580
+ An empty metrics report exits 0 because it is a valid observation, not a command failure.
581
+
582
+ ### `doctor` or `status` reports `provider-capabilities-drift`
583
+
584
+ The installed provider's own capability declaration no longer agrees with the one Token Harness
585
+ records. The warning names both sides: what the recorded declaration claims, and what the installed
586
+ build reported. Nothing is modified, and the recorded declaration still drives planning.
587
+
588
+ Three disagreements are reported:
589
+
590
+ - a coding agent that Token Harness records a capability on is missing from the build's declaration;
591
+ - the reduction surface Token Harness records is absent from the surfaces the build reports;
592
+ - the build no longer covers a reviewed write-set path, or declares a path outside the reviewed
593
+ containment boundary.
594
+
595
+ The last one matters most before a delegated install. Rollback restores the reviewed boundary, so a
596
+ path outside it would survive a rollback. Re-review the write set at the installed version, or hold
597
+ at the reviewed one.
598
+
599
+ ### A newer provider or agent version is reported
600
+
601
+ The tested ranges record versions actually exercised by this project. A newer version is reported
602
+ and handled conservatively rather than assumed compatible. Check [docs/matrices.md](docs/matrices.md)
603
+ and the upstream release notes before applying configuration changes.
235
604
 
236
605
  ## Development
237
606
 
238
- ```bash
607
+ ```sh
608
+ corepack enable
239
609
  pnpm install
240
610
  pnpm typecheck
241
611
  pnpm lint
@@ -246,44 +616,15 @@ pnpm package
246
616
  pnpm smoke:install
247
617
  ```
248
618
 
249
- `pnpm build` produces the self-contained artifact at `dist/bundle/token-harness.mjs`;
250
- `pnpm smoke` runs it from a temporary directory outside the repository, so anything
251
- that failed to inline shows up as a resolution failure rather than as a passing test.
252
- CI runs all of it on `windows-latest`, `macos-latest`, and `ubuntu-latest`, in that
253
- order and without fail-fast, because the failures this project exists to prevent are
254
- mostly Windows-specific and finding them after two green jobs is how they become
255
- workarounds instead of design.
619
+ Tests use temporary homes and fake process runners; they do not install third-party tools.
620
+ `pnpm smoke` runs the bundle from outside the workspace, and `pnpm smoke:install` validates the
621
+ packed npm artifact.
256
622
 
257
- ## Release gates
623
+ Before changing architecture or public behavior, read [PLAN.md](PLAN.md) and the accepted RFCs in
624
+ [docs/rfcs](docs/rfcs). The CLI and JSON contract is defined by
625
+ [RFC 0006](docs/rfcs/0006-cli-contract.md).
258
626
 
259
- | Version | Gate |
260
- | --- | --- |
261
- | `0.0.x` | Internal architecture and fixtures. No stability promise. |
262
- | `0.1.0` | RTK and HarnessTrim, three harnesses, transactional install, verification with declared tiers, metrics, brownfield adoption **← here** |
263
- | `0.2.0` | A third provider, goal-based profiles, the A/B benchmark matrix |
264
- | `1.0.0` | Stable provider and harness contracts, two release cycles with no configuration-loss defects, published benchmark results |
265
-
266
- `PLAN.md` §16 is the authority; this table is a summary of it.
267
-
268
- `pnpm golden` regenerates the derived halves of the golden fixtures. It never
269
- touches the five human transcripts transcribed from RFC 0006 — see
270
- [tests/fixtures/README.md](tests/fixtures/README.md).
271
-
272
- CI runs Windows, macOS, and Linux, with Windows first in the matrix and the
273
- matrix set not to fail fast.
274
-
275
- Releases publish on a `v*` tag through npm trusted publishing: OIDC, no token in the repository
276
- secrets or anywhere else, and provenance signed by npm. A tag that does not match the staged version
277
- is refused before the publish rather than discovered by whoever installs it.
278
-
279
- - [Compatibility, verification tiers, and known limitations](docs/matrices.md) — the tables are
280
- generated from the manifests and a test fails if they drift; the limitations below them are prose,
281
- and a test checks that every limitation the code declares appears there
282
- - [Development plan](PLAN.md)
283
- - [Foundation decisions](docs/rfcs/0001-foundation.md)
284
- - [Provider contract](docs/rfcs/0002-provider-contract.md)
285
- - [Capability and conflict model](docs/rfcs/0003-capabilities-and-conflicts.md)
286
- - [Safety and installation model](docs/rfcs/0004-safety-and-installation.md)
287
- - [Metrics and attribution](docs/rfcs/0005-metrics-and-attribution.md)
288
- - [CLI contract](docs/rfcs/0006-cli-contract.md)
289
- - [Live verification](docs/rfcs/0007-live-verification.md)
627
+ ## License
628
+
629
+ Token Harness is licensed under the [Apache License 2.0](LICENSE). RTK and HarnessTrim are
630
+ independent upstream projects distributed under their own licenses.