token-harness 0.1.0 → 0.1.1

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 +500 -236
  2. package/package.json +1 -1
  3. package/sbom.json +5 -5
  4. package/token-harness.mjs +595 -187
package/README.md CHANGED
@@ -1,241 +1,534 @@
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
+ | [Headroom](https://github.com/headroomlabs-ai/headroom) | Compress tool, MCP, file, and RAG payloads | Not active — candidate |
36
+ | [Context Mode](https://github.com/mksglu/context-mode) | Keep raw tool results outside model context | Not active — candidate |
37
+ | [LLMLingua](https://github.com/microsoft/LLMLingua) | Compress long prompts and context | Not active — candidate |
38
+ | [Caveman](https://github.com/JuliusBrussee/caveman) | Reduce visible model-output verbosity | Not active — candidate |
39
+
40
+ Candidate status means only that the project has identified a useful optimization layer. A tool
41
+ becomes active only after its installation, conflicts, rollback behavior, verification, and
42
+ metrics attribution have been implemented and tested. Token Harness never installs a candidate
43
+ merely because it is present on the machine.
44
+
45
+ ## Quick start
46
+
47
+ Install the CLI:
48
+
49
+ ```sh
50
+ npm install --global token-harness
51
+ token-harness --version
52
+ ```
70
53
 
71
- ```text
54
+ Then run the complete workflow from the project in which you use your coding agent:
55
+
56
+ ```sh
57
+ # 1. Inspect the machine. This does not change agent configuration.
72
58
  token-harness doctor
59
+
60
+ # 2. Preview every proposed change.
73
61
  token-harness plan
62
+
63
+ # 3. Apply the reviewed plan. This is the first configuration-changing step.
74
64
  token-harness apply --yes
65
+
66
+ # 4. Restart the coding agent, then run a normal shell command through it.
67
+
68
+ # 5. Check configuration, real interception evidence, and savings.
69
+ token-harness status
75
70
  token-harness verify
76
71
  token-harness metrics --since 7d
77
- token-harness status
78
- token-harness rollback --yes
79
72
  ```
80
73
 
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.
74
+ `doctor` ends with a `NEXT` section. If you are unsure what to do, run the command shown
75
+ there.
76
+
77
+ To try the read-only diagnosis without installing Token Harness globally:
78
+
79
+ ```sh
80
+ npx token-harness doctor
81
+ ```
82
+
83
+ `npx` may download Token Harness into npm's cache, but it does not install or configure RTK,
84
+ HarnessTrim, or a coding agent.
85
+
86
+ ## How the components fit together
87
+
88
+ There are three separate layers. Installing one does not automatically provide the others.
89
+
90
+ | Layer | Examples | Who installs it? |
91
+ | --- | --- | --- |
92
+ | Coding agent (harness) | Claude Code, Codex, OpenCode | You, using the agent's official installer |
93
+ | Token Harness | `token-harness` | You, from npm or this repository |
94
+ | Optimization provider | RTK, HarnessTrim | RTK can be installed by Token Harness; HarnessTrim Claude skills can be installed safely when HarnessTrim 0.0.7 is already available |
95
+
96
+ Token Harness does not install Claude Code, Codex, or OpenCode. Install and run at least one of
97
+ them first so that `token-harness doctor` can detect it.
98
+
99
+ | Provider | Claude Code | Codex | OpenCode | Installed by Token Harness |
100
+ | --- | --- | --- | --- | --- |
101
+ | RTK | Configure, verify, and measure | Not managed | Not managed | **Yes**, for the supported Claude Code path |
102
+ | HarnessTrim | Claude skills only; no reducer hook or reduce-pipe instruction | Detect, adopt, verify, and measure | Detect, adopt, verify, and measure | **Yes**, when `harnesstrim 0.0.7` is already installed |
103
+
104
+ "Not managed" does not mean the upstream tool cannot support that agent. It means this release
105
+ does not claim ownership of that integration and will not modify it.
106
+
107
+ The generated compatibility tables, tested version ranges, platform coverage, and known
108
+ limitations are in [docs/matrices.md](docs/matrices.md).
109
+
110
+ ## Installing each component
111
+
112
+ ### 1. Install Token Harness
113
+
114
+ Recommended, from npm:
115
+
116
+ ```sh
117
+ npm install --global token-harness
118
+ token-harness --help
119
+ ```
120
+
121
+ If the command is not found after installation, find npm's global binary directory with:
122
+
123
+ ```sh
124
+ npm prefix --global
125
+ ```
126
+
127
+ Ensure that directory's executable location is on `PATH`, then open a new terminal.
128
+
129
+ #### Build and install from source
130
+
131
+ The repository uses the pnpm version declared in `package.json`.
132
+
133
+ ```sh
134
+ git clone https://github.com/giuliastro/token-harness.git
135
+ cd token-harness
136
+ corepack enable
137
+ pnpm install
138
+ pnpm build
139
+ pnpm package
140
+ npm install --global ./dist/package
141
+ token-harness --version
142
+ ```
143
+
144
+ `pnpm build` creates the self-contained CLI at `dist/bundle/token-harness.mjs`.
145
+ `pnpm package` creates the installable package under `dist/package`.
146
+ If `corepack` is unavailable, install the pinned package manager with
147
+ `npm install --global pnpm@10.33.4` instead.
84
148
 
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.
149
+ ### 2. Install or adopt RTK
90
150
 
91
- Additional tools, and joint reduction by two providers, are introduced only after
92
- compatibility and attribution tests prove they compose safely.
151
+ For the supported managed path, you normally do **not** install RTK yourself:
93
152
 
94
- ## Status
153
+ ```sh
154
+ token-harness plan --harness claude --provider rtk
155
+ ```
95
156
 
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.
157
+ If RTK is absent, the plan contains two actions:
100
158
 
101
- ### The nine criteria
159
+ 1. install RTK through the selected package manager;
160
+ 2. append one RTK entry to Claude Code's `PreToolUse` hook configuration.
102
161
 
103
- PLAN §2 lists what makes `0.1.0` useful. Measured, not estimated:
162
+ The channel selected by this release is:
104
163
 
105
- | # | Criterion | State |
164
+ | Platform | Channel used by the plan | Required command on `PATH` |
106
165
  | --- | --- | --- |
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
166
+ | Windows | WinGet package `rtk-ai.rtk` | `winget` |
167
+ | macOS | Cargo package `rtk` | `cargo` |
168
+ | Linux and WSL | Cargo package `rtk` | `cargo` |
118
169
 
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)
170
+ The Cargo path in this release invokes `cargo install rtk`. That channel is declared but has not
171
+ been exercised by this project, and upstream documents a crates.io name collision. On macOS,
172
+ Linux, and WSL, the safer current route is to install RTK with an upstream-recommended method,
173
+ confirm that `rtk gain` works, and let Token Harness adopt and configure the existing binary.
174
+
175
+ Review the plan's `Network`, `Elevation`, and `Actions` sections before applying it:
176
+
177
+ ```sh
178
+ token-harness apply --yes --harness claude --provider rtk
129
179
  ```
130
180
 
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
181
+ If RTK is already installed and configured, Token Harness adopts it instead of reinstalling or
182
+ rewriting it. User-owned configuration remains user-owned.
183
+
184
+ Important boundaries:
185
+
186
+ - Token Harness writes the reviewed hook itself; it does not run `rtk init`.
187
+ - A package install is not reversed by file rollback. `rollback` restores configuration files,
188
+ not installed binaries.
189
+ - `uninstall` removes only integration entries written by Token Harness; it deliberately leaves
190
+ the RTK executable installed.
191
+ - On native Windows, Claude Code exposes both Bash and PowerShell tool families. The current RTK
192
+ matcher covers Bash only, so `doctor` can correctly report PowerShell as bypassed.
193
+
194
+ For manual installation or use outside Token Harness's managed surface, follow the
195
+ [RTK installation guide](https://github.com/rtk-ai/rtk/blob/master/INSTALL.md), then run:
196
+
197
+ ```sh
198
+ rtk --version
199
+ rtk gain
200
+ token-harness doctor --provider rtk
137
201
  ```
138
202
 
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.
203
+ `rtk gain` is an important identity check because another unrelated package also uses the name
204
+ `rtk`.
142
205
 
143
- `metrics` on the same machine reports **91,600 tokens saved over 2,847 intercepted
144
- commands** — exactly what `rtk gain` reports independently.
206
+ ### 3. Install or adopt HarnessTrim
145
207
 
146
- ### The full command surface
208
+ With HarnessTrim `0.0.7` already on `PATH`, `token-harness plan --harness claude` can install its
209
+ Claude skills without creating the competing Bash hook or reduce-pipe instruction. The planned
210
+ upstream invocation is:
147
211
 
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
212
+ ```sh
213
+ harnesstrim install claude <project> --apply --no-hook --no-instructions
214
+ ```
215
+
216
+ Codex and OpenCode remain adoption-only. Install those integrations with HarnessTrim's own CLI,
217
+ first as a dry run and then with its explicit apply flag. Consult the
218
+ [HarnessTrim README](https://github.com/giuliastro/HarnessTrim#quick-start) because its adapter
219
+ contents, modes, and telemetry differ by coding agent.
220
+
221
+ After installing it:
222
+
223
+ ```sh
224
+ token-harness doctor --provider harnesstrim
225
+ token-harness status --provider harnesstrim
226
+ token-harness verify --provider harnesstrim
227
+ token-harness metrics --provider harnesstrim --since 7d
158
228
  ```
159
229
 
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
230
+ Do not configure RTK and HarnessTrim to reduce the same shell output. In the `safe` profile,
231
+ Token Harness gives that exclusive surface to RTK and treats an existing overlap as a hard
232
+ conflict instead of guessing an execution order. It never deletes the competing entry for you.
233
+
234
+ HarnessTrim telemetry is opt-in in some adapters. Without a `.harnesstrim/metrics.jsonl` file,
235
+ verification can still inspect configuration, but `metrics` has no HarnessTrim events to import.
236
+
237
+ ## The recommended operating workflow
238
+
239
+ ### Step 1: diagnose
240
+
241
+ ```sh
223
242
  token-harness doctor
224
243
  ```
225
244
 
226
- To run it without installing:
245
+ This answers:
246
+
247
+ - which supported coding agents are installed;
248
+ - which providers are installed and runnable;
249
+ - which agent configuration files exist;
250
+ - which provider is wired to which agent;
251
+ - whether Token Harness owns the integration or merely adopted it;
252
+ - whether a version, configuration file, or tool-family matcher needs attention.
253
+
254
+ Common states:
255
+
256
+ | State | Meaning |
257
+ | --- | --- |
258
+ | `not found` / `absent` | The executable and usable configuration were not detected |
259
+ | `installed` | The provider runs but is not connected to a supported agent |
260
+ | `configured` | A relevant hook or plugin entry exists |
261
+ | `broken` | Configuration refers to something missing or unreadable |
262
+ | `set up by you` | Token Harness adopted existing configuration and will not remove it |
263
+ | `set up by this tool` | A committed Token Harness transaction owns the exact entry |
264
+
265
+ `doctor` is diagnostic. An empty machine is a valid state and exits successfully.
266
+
267
+ ### Step 2: review the plan
268
+
269
+ ```sh
270
+ token-harness plan
271
+ ```
272
+
273
+ Narrow the operation when useful:
274
+
275
+ ```sh
276
+ token-harness plan --harness claude
277
+ token-harness plan --provider rtk
278
+ token-harness plan --project /path/to/project
279
+ ```
280
+
281
+ Read these sections before proceeding:
282
+
283
+ - `Capability ownership`: which provider is allowed to transform each surface;
284
+ - `Excluded`: detected providers intentionally left out;
285
+ - `Actions`: every package operation and file change;
286
+ - `Network`: destinations contacted by later mutation;
287
+ - `Elevation`: whether administrator/root access would be required;
288
+ - `Backups`: how many files will be snapshotted.
289
+
290
+ `plan` does not modify agent or project configuration. It may persist the serialized plan in
291
+ Token Harness's private state directory so the exact reviewed artifact can be applied later.
292
+
293
+ If the plan prints an ID, apply that exact plan with:
294
+
295
+ ```sh
296
+ token-harness apply --plan <plan-id> --yes
297
+ ```
298
+
299
+ The stored plan is rejected before any action runs if the project, versions, ownership, or file
300
+ preconditions changed after review.
301
+
302
+ ### Step 3: apply
303
+
304
+ ```sh
305
+ token-harness apply --yes
306
+ ```
307
+
308
+ Without `--yes`, `apply` shows what it would do and exits with code 8. Every affected file is
309
+ snapshotted before mutation, including the prior absence of a newly created file. A failure
310
+ triggers automatic restoration and the result states whether that restoration was verified.
311
+
312
+ After a successful apply, restart the coding agent so it reloads its hooks or plugins.
313
+
314
+ ### Step 4: create real traffic
315
+
316
+ Passive verification needs evidence from an operation that actually passed through the provider.
317
+ Open the configured coding agent and ask it to run a normal shell command such as `git status` or
318
+ a test command. Then return to the terminal.
319
+
320
+ ### Step 5: verify configuration and execution
321
+
322
+ Use both commands; they answer different questions:
323
+
324
+ ```sh
325
+ token-harness status
326
+ token-harness verify
327
+ ```
328
+
329
+ `status` compares the live environment with committed receipts. It finds drift, changed versions,
330
+ and competing entries on exclusive surfaces.
331
+
332
+ `verify` checks the strongest evidence the integration declares:
333
+
334
+ | Tier | What it proves |
335
+ | --- | --- |
336
+ | `presence` | The executable resolves and reports a version |
337
+ | `config-only` | The expected configuration entry exists |
338
+ | `canary` | Provider records show a real operation crossed the interception point |
339
+
340
+ `config-only` is not proof that the hook ran. It is the honest ceiling for integrations whose
341
+ runtime state cannot be observed externally.
342
+
343
+ `not-exercised` means no attributable operation has been observed yet. It is neither success nor
344
+ failure: run a command through the agent and check again.
345
+
346
+ ### Step 6: inspect savings
347
+
348
+ ```sh
349
+ token-harness metrics
350
+ token-harness metrics --since 24h
351
+ token-harness metrics --since 2026-07-01 --until 2026-08-01
352
+ token-harness metrics --provider rtk --since 7d
353
+ ```
354
+
355
+ The default window is seven days. Durations such as `12h`, `7d`, and `2w`, plus ISO dates, are
356
+ accepted. Date boundaries are midnight UTC.
357
+
358
+ The report keeps measurement types and units separate:
359
+
360
+ | Report line | Interpretation |
361
+ | --- | --- |
362
+ | `Exact local` | Before and after token counts were observed for the same operation |
363
+ | `Estimated local` | The payload changed, but the reported unit or tokenizer is an estimate |
364
+ | `Counterfactual` | A dry run measured what could have changed; it is not realized saving |
365
+ | `End-to-end billed` | Comparable billed sessions were measured; otherwise it says `no A/B run` |
366
+ | `Coverage` | Share of relevant operations that were actually changed |
367
+ | `Bypassed` | Operations observed but passed through unchanged or outside coverage |
368
+
369
+ Token counts are never added to character counts, and estimated or counterfactual values are never
370
+ silently merged into an exact total.
371
+
372
+ ## Undoing changes
373
+
374
+ Choose the command based on what you want to undo:
375
+
376
+ ```sh
377
+ # Remove only exact integration entries owned by Token Harness.
378
+ token-harness uninstall --yes
379
+
380
+ # Restore all files from the most recent committed transaction snapshot.
381
+ token-harness rollback --yes
382
+ ```
383
+
384
+ `uninstall` is usually the safer choice after subsequent manual edits: it is surgical and refuses
385
+ to remove an owned entry if its content no longer matches what Token Harness wrote.
386
+
387
+ `rollback` restores whole files to their pre-transaction bytes. Changes made to those files after
388
+ the transaction are therefore also reverted. It does not restore or remove provider packages.
389
+
390
+ Neither command removes user-owned RTK or HarnessTrim configuration.
391
+
392
+ ## Command reference
393
+
394
+ | Command | Purpose | Changes agent/project configuration? |
395
+ | --- | --- | --- |
396
+ | `doctor` | Detect agents, providers, ownership, and problems | No |
397
+ | `plan` | Resolve ownership and preview exact actions | No; stores the plan in private state |
398
+ | `apply` | Apply a plan transactionally | Yes, only with `--yes` |
399
+ | `status` | Detect drift and competing hooks | No |
400
+ | `verify` | Check the declared verification tier | No |
401
+ | `metrics` | Import provider records and report savings | No; updates only Token Harness state |
402
+ | `update` | Query channels and update installed providers | Yes, only with `--yes` |
403
+ | `rollback` | Restore files from the latest committed transaction | Yes, only with `--yes` |
404
+ | `uninstall` | Remove owned integration entries | Yes, only with `--yes` |
405
+
406
+ Every command supports `--help`. Common filters are:
407
+
408
+ ```text
409
+ --harness claude|codex|opencode
410
+ --provider rtk|harnesstrim
411
+ --project <directory>
412
+ --json
413
+ ```
414
+
415
+ ## Automation and JSON output
416
+
417
+ Use `--json` in scripts:
418
+
419
+ ```sh
420
+ token-harness doctor --json
421
+ token-harness verify --json
422
+ token-harness metrics --since 7d --json
423
+ ```
227
424
 
228
- ```bash
229
- node dist/bundle/token-harness.mjs doctor
425
+ stdout contains exactly one JSON document with this top-level contract:
426
+
427
+ ```json
428
+ {
429
+ "schemaVersion": 1,
430
+ "command": "verify",
431
+ "toolVersion": "0.1.0",
432
+ "status": "ok",
433
+ "exitCode": 0,
434
+ "data": {},
435
+ "diagnostics": []
436
+ }
230
437
  ```
231
438
 
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.
439
+ Important exit codes:
440
+
441
+ | Code | Meaning |
442
+ | ---: | --- |
443
+ | 0 | Completed with nothing actionable |
444
+ | 2 | Invalid command or argument |
445
+ | 3 | A read-only check found an actionable problem |
446
+ | 4 | A capability conflict blocks the plan |
447
+ | 5 | The environment drifted from the stored plan or journal |
448
+ | 6 | Mutation failed and rollback was verified |
449
+ | 7 | Mutation failed and state was not fully restored; inspect the named paths |
450
+ | 8 | The command needs explicit confirmation (`--yes`) |
451
+ | 9 | Unsupported or unverifiable environment |
452
+
453
+ Do not treat every non-zero code as the same failure. In particular, code 8 is the expected result
454
+ of previewing a mutating command without approval.
455
+
456
+ ## State, backups, and privacy
457
+
458
+ Token Harness stores plans, journals, backups, receipts, import cursors, and normalized metrics
459
+ outside the repository:
460
+
461
+ | Platform | Default state root |
462
+ | --- | --- |
463
+ | Windows | `%LOCALAPPDATA%\TokenHarness` |
464
+ | macOS | `~/Library/Application Support/TokenHarness` |
465
+ | Linux and WSL | `${XDG_STATE_HOME:-~/.local/state}/token-harness` |
466
+
467
+ Normalized metrics do not contain raw command text, tool output, source code, prompts, credentials,
468
+ or raw file paths. Provider records are read in place; Token Harness imports only normalized event
469
+ data.
470
+
471
+ ## Troubleshooting
472
+
473
+ ### `token-harness` is not found
474
+
475
+ Confirm Node and the global npm installation:
476
+
477
+ ```sh
478
+ node --version
479
+ npm list --global token-harness
480
+ npm prefix --global
481
+ ```
482
+
483
+ Node must be at least 22.13.0. Add npm's global executable directory to `PATH`, then reopen the
484
+ terminal.
485
+
486
+ ### `plan` says there is nothing to do
487
+
488
+ Run `token-harness doctor`. The usual causes are:
489
+
490
+ - no supported coding agent was detected;
491
+ - the requested provider does not claim that coding agent in this release;
492
+ - an existing user-managed integration already satisfies the target state;
493
+ - the safe profile excluded an overlapping provider.
494
+
495
+ RTK is managed only for Claude Code in 0.1.0. A Codex-only or OpenCode-only machine therefore does
496
+ not produce an RTK installation action.
497
+
498
+ ### The plan is blocked by `exclusive-scope-contested`
499
+
500
+ RTK and HarnessTrim both claim the same reducing surface. Token Harness will not choose an order or
501
+ overwrite either configuration. Remove or disable one integration using the tool that owns it, then
502
+ run `doctor` and `plan` again.
503
+
504
+ ### `verify` reports `not-exercised`
505
+
506
+ Restart the coding agent, ask it to run a shell command through the configured tool family, then
507
+ run `token-harness verify` again. For a `config-only` integration, no stronger external receipt may
508
+ exist; the output states that limitation explicitly.
509
+
510
+ ### `metrics` shows no data
511
+
512
+ Check all of the following:
513
+
514
+ - the provider has processed at least one operation in the requested time window;
515
+ - `rtk gain` works for RTK;
516
+ - HarnessTrim telemetry is enabled and `.harnesstrim/metrics.jsonl` exists for the project;
517
+ - `--project` points to the project whose records you expect;
518
+ - `--since` is not excluding older events.
519
+
520
+ An empty metrics report exits 0 because it is a valid observation, not a command failure.
521
+
522
+ ### A newer provider or agent version is reported
523
+
524
+ The tested ranges record versions actually exercised by this project. A newer version is reported
525
+ and handled conservatively rather than assumed compatible. Check [docs/matrices.md](docs/matrices.md)
526
+ and the upstream release notes before applying configuration changes.
235
527
 
236
528
  ## Development
237
529
 
238
- ```bash
530
+ ```sh
531
+ corepack enable
239
532
  pnpm install
240
533
  pnpm typecheck
241
534
  pnpm lint
@@ -246,44 +539,15 @@ pnpm package
246
539
  pnpm smoke:install
247
540
  ```
248
541
 
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.
542
+ Tests use temporary homes and fake process runners; they do not install third-party tools.
543
+ `pnpm smoke` runs the bundle from outside the workspace, and `pnpm smoke:install` validates the
544
+ packed npm artifact.
256
545
 
257
- ## Release gates
546
+ Before changing architecture or public behavior, read [PLAN.md](PLAN.md) and the accepted RFCs in
547
+ [docs/rfcs](docs/rfcs). The CLI and JSON contract is defined by
548
+ [RFC 0006](docs/rfcs/0006-cli-contract.md).
258
549
 
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)
550
+ ## License
551
+
552
+ Token Harness is licensed under the [Apache License 2.0](LICENSE). RTK and HarnessTrim are
553
+ independent upstream projects distributed under their own licenses.