@critiquedotsh/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 (3) hide show
  1. package/README.md +257 -7
  2. package/dist/cli.js +534 -123
  3. package/package.json +3 -2
package/README.md CHANGED
@@ -1,14 +1,264 @@
1
- # @critiquedotsh/harness
1
+ # CritiqueCode (`@critiquedotsh/harness`)
2
2
 
3
- CritiqueCode author agent. Same npm org as [`@critiquedotsh/cli`](../critique-cli). Not a rename of that sidecar.
3
+ **CritiqueCode** is an author agent for a local git repository. It implements in an interactive terminal session, then the controller forces independent review and verified repair. It is a Claude Code / Codex-style coding loop, not a PR comment bot.
4
+
5
+ | Product | npm package | Binary | Job |
6
+ | --- | --- | --- | --- |
7
+ | **CritiqueCode** (this package) | [`@critiquedotsh/harness`](https://www.npmjs.com/package/@critiquedotsh/harness) | `critique-code` | Author: write the change, then survive review |
8
+ | **Critique CLI** | [`@critiquedotsh/cli`](https://www.npmjs.com/package/@critiquedotsh/cli) | `critique` | Sidecar reviewer for agents you already run |
9
+
10
+ Same npm org. Different products. Do not install CritiqueCode by swapping `@critiquedotsh/cli`. Do not call `critique finish` as a substitute for this harness.
11
+
12
+ Docs: [CritiqueCode](https://critique.sh/docs/platform/critique-code) · [Inference API](https://critique.sh/docs/platform/inference-api) · [Critique CLI](https://critique.sh/docs/platform/cli)
13
+
14
+ ## Requirements
15
+
16
+ - Node.js **20.19** or newer
17
+ - A **git repository** (run the binary in the project you want to edit)
18
+ - A model route: **Critique Inference** (website login, no pasted key) or a BYOK provider key
19
+
20
+ Optional:
21
+
22
+ - [`@earendil-works/pi-coding-agent`](https://www.npmjs.com/package/@earendil-works/pi-coding-agent) (installed automatically as an optional dependency; the live author kernel)
23
+ - [`ffmpeg-static`](https://www.npmjs.com/package/ffmpeg-static) (optional dependency; bundled microphone recorder for `/voice`)
24
+
25
+ ## Install
26
+
27
+ ```bash
28
+ npm install --global @critiquedotsh/harness
29
+ ```
30
+
31
+ Confirm the binary:
32
+
33
+ ```bash
34
+ critique-code help
35
+ ```
36
+
37
+ Always `cd` into the repository you intend to change. CritiqueCode uses the **current working directory**.
4
38
 
5
39
  ```bash
6
40
  cd /path/to/your-project
7
- node /path/to/this-checkout/packages/critique-code/bin/critique-code.mjs
8
- # after publish:
9
- # npm install --global @critiquedotsh/harness && critique-code
41
+ critique-code
42
+ ```
43
+
44
+ From a Critique platform checkout (not the published install):
45
+
46
+ ```bash
47
+ cd /path/to/your-project
48
+ node /path/to/critique/packages/critique-code/bin/critique-code.mjs
49
+ ```
50
+
51
+ `pnpm critique-code` from the Critique checkout uses **that** checkout as cwd unless you pass `--cwd`. That is the wrong default when you are trying the agent on another project.
52
+
53
+ ## Quick start (no API key paste)
54
+
55
+ 1. Install the package.
56
+ 2. Enter your repo.
57
+ 3. Connect Critique Inference in the browser:
58
+
59
+ ```bash
60
+ cd /path/to/your-project
61
+ critique-code login
62
+ ```
63
+
64
+ The terminal prints a URL and a short code, opens the browser when it can, and waits. Approve on [critique.sh/device](https://critique.sh/device). CritiqueCode stores a machine key under `~/.critique/code/` and sets the default route to **Critique Inference** with model `critique/auto`.
65
+
66
+ Same flow from an already-open session: type `/login`.
67
+
68
+ Then:
69
+
70
+ ```bash
71
+ critique-code
72
+ ```
73
+
74
+ Describe the change. Slash lines (`/review`, `/ship`, …) are never sent to the model.
75
+
76
+ ## What a session does
77
+
78
+ 1. **Author** implements in the working tree (writes go through a content-addressed apply path).
79
+ 2. You can ask the model to run a workspace command via `critique_run`. **You** approve or deny each request. Denied means nothing runs. Output is not Evidence.
80
+ 3. **`/review` or `/ship`** starts the evidence harness. Author chat is withheld from the reviewer.
81
+ 4. **`/repair`** runs verified repair on promoted findings. It is not auto-applied chatter.
82
+ 5. `none_promoted` means nothing was promoted. It is **not** a correctness proof.
83
+
84
+ The TTY shows a wordmark, a compact live status (`thinking` / `write path` / `read path`), then a one-line `▸` summary before the reply. It does not stream thinking paragraphs.
85
+
86
+ Interactive TTY sessions keep **stdout quiet**. Pass `--json` for the session envelope. `review`, `repair`, and `capabilities` still print JSON on stdout. Live chrome goes to stderr.
87
+
88
+ ## CLI
89
+
90
+ ```text
91
+ critique-code
92
+ critique-code chat [--intent <text>] [--models provider/model,...] [--cwd <dir>] [--store <dir>] [--voice] [--json]
93
+ critique-code login
94
+ critique-code settings | keys | models
95
+ critique-code review [--depth quick|standard|paranoid] [--focus general,security] [--models ...] [--base <ref>] [--intent <text>] [--cwd <dir>] [--store <dir>]
96
+ critique-code repair <review-run-id> [--store <dir>] [--cwd <dir>] [--models ...]
97
+ critique-code capabilities [--cwd <dir>]
98
+ critique-code skills [--cwd <dir>]
99
+ critique-code import-skills [--cwd <dir>]
100
+ critique-code help
101
+ ```
102
+
103
+ | Command | Purpose |
104
+ | --- | --- |
105
+ | `critique-code` / `chat` | Interactive author session |
106
+ | `login` | Browser device approval; connect Critique Inference |
107
+ | `settings` / `keys` / `models` | TUI for route, stored keys, and model ids |
108
+ | `review` | Evidence harness (JSON on stdout) |
109
+ | `repair <id>` | Verified repair for a stored review run |
110
+ | `capabilities` | Discovered local check tools |
111
+ | `skills` | Built-in plus imported Claude Code / Codex / Cursor `SKILL.md` folders |
112
+ | `import-skills` | Copy discovered skills into `~/.critique/code/skills` |
113
+
114
+ ### Flags
115
+
116
+ | Flag | Meaning |
117
+ | --- | --- |
118
+ | `--cwd <dir>` | Repository to edit (default: process cwd) |
119
+ | `--store <dir>` | Where review/repair artifacts are stored |
120
+ | `--models <list>` | Comma-separated `provider/model` or `provider:family:model_id`, or a JSON array |
121
+ | `--intent <text>` | Starting author or review intent |
122
+ | `--depth quick\|standard\|paranoid` | Review depth |
123
+ | `--focus general,security,...` | Review lenses: `general`, `stress`, `security`, `performance`, `reliability` |
124
+ | `--base <ref>` | Review against a git base ref (not a checkout) |
125
+ | `--voice` | Start the author session in voice mode |
126
+ | `--json` | Print the session envelope on stdout even on a TTY |
127
+ | `-h` / `help` | Help |
128
+
129
+ `critique-code review` is read-only. Use `critique-code repair <review-run-id>` for explicit repair. `--repair apply` on `review` is rejected.
130
+
131
+ ## Interactive commands
132
+
133
+ Type `/` or `/help` for a selectable picker. **Lines that start with `/` never go to the model.**
134
+
135
+ | Command | Effect |
136
+ | --- | --- |
137
+ | `/` `/help` | Picker / help |
138
+ | `/login` | Connect Critique Inference in the browser |
139
+ | `/voice` | Record one spoken prompt (Qwen3 ASR) |
140
+ | `/voice on` | Keep listening after each reply |
141
+ | `/voice off` | Return to the keyboard |
142
+ | `/review` | Evidence harness since the last review checkpoint |
143
+ | `/review all` | Evidence harness on the current tree even if unchanged |
144
+ | `/repair` | Verified repair of promoted findings |
145
+ | `/ship` | Review, then end if the controller allows |
146
+ | `/settings` | Keys, route, models |
147
+ | `/models` | Pick author/review model |
148
+ | `/keys` | Store BYOK keys |
149
+ | `/skills` | List built-in and imported skills |
150
+ | `/done` | End after a review |
151
+ | `/exit` | Leave |
152
+
153
+ Spoken `review`, `repair`, `ship`, and `exit` match the typed commands when voice is on. An empty clip after `/voice on` returns to the keyboard.
154
+
155
+ Unknown `/foo` is rejected in the TUI. It is not forwarded as chat.
156
+
157
+ ## Voice mode
158
+
159
+ Talk to the author and the reviewer. `/voice` records one clip (Enter to stop). `/voice on` keeps listening after each reply. `/voice off` returns to the keyboard. `critique-code --voice` starts already listening.
160
+
161
+ Transcription uses **Qwen3 ASR 0.6B** (`qwen/qwen3-asr-0.6b`) on Critique Inference, billed at **$0.000003 per second** of audio. An OpenRouter key works if you are not on Inference. The recorder is bundled `ffmpeg-static`; you do not need a system `sox` or `ffmpeg` install.
162
+
163
+ Needs a microphone and an interactive TTY. Voice is dictation in. Replies stay on screen. Docs: [CritiqueCode voice mode](https://critique.sh/docs/platform/critique-code).
164
+
165
+ ## Skills
166
+
167
+ Built-in author skills cover **code review**, **Critique `/review`**, and **TDD**. Sessions also load `SKILL.md` from Claude Code, Codex, Cursor, OpenCode, and Agents folders in the repo and your home directory. No export step required. Built-in names win on collision. `critique-code import-skills` copies them into `~/.critique/code/skills`.
168
+
169
+ ## Models and billing
170
+
171
+ ### Default: Critique Inference
172
+
173
+ After `critique-code login` or a `crt_` / `CRITIQUE_API_KEY`, the default route is **Critique Inference** and the default model is **`critique/auto`**.
174
+
175
+ `critique/auto` is a session coding selector over Critique-resold models: efficient specialists first, sticky while the loop is healthy, one escalate onto a frontier rung if tools keep failing. It does not search the full OpenRouter catalogue.
176
+
177
+ Managed Inference traffic bills **raw USD**:
178
+
179
+ ```text
180
+ inputUsd = (prompt_tokens / 1_000_000) × input_rate_per_M
181
+ outputUsd = (completion_tokens / 1_000_000) × output_rate_per_M
10
182
  ```
11
183
 
12
- Author agent: implements in an interactive session, then the controller forces review and verified repair. Default is Critique Inference `critique/auto` after `critique-code login` (approve on the website) or a `crt_` key. `/voice` talks to the author through Qwen3 ASR. OpenAI, OpenRouter, and other BYOK keys stay optional. Inference bills $/1M input and output, not review credits. OpenRouter Activity attributes traffic to `critique.sh`. Interactive TTY keeps stdout quiet unless `--json`.
184
+ That spend does **not** consume the PR review credit pool. Rate cards and `critique/auto` live on [critique.sh/inference-api](https://critique.sh/inference-api).
185
+
186
+ Voice transcription uses Qwen3 ASR 0.6B (`POST /api/v1/audio/transcriptions`) at **$0.000003 per second** of audio.
187
+
188
+ ### Bring your own key
189
+
190
+ `/keys` and environment variables still accept other providers. If Critique Inference is connected, it stays the default until you change the route in `/settings`.
191
+
192
+ | Provider | Environment |
193
+ | --- | --- |
194
+ | Critique Inference | `CRITIQUE_API_KEY` or `CRITIQUE_INFERENCE_API_KEY` |
195
+ | OpenRouter | `OPENROUTER_API_KEY` |
196
+ | OpenAI | `OPENAI_API_KEY` |
197
+ | Anthropic | `ANTHROPIC_API_KEY` or `ANTHROPIC_AUTH_TOKEN` |
198
+ | Google Gemini | `GEMINI_API_KEY` or `GOOGLE_API_KEY` |
199
+ | xAI | `XAI_API_KEY` |
200
+ | Groq | `GROQ_API_KEY` |
201
+ | DeepSeek | `DEEPSEEK_API_KEY` |
202
+ | LLM Gateway | `LLM_GATEWAY_API_KEY` or `LLMGATEWAY_API_KEY` |
203
+ | Vercel AI Gateway | `AI_GATEWAY_API_KEY` |
204
+ | Custom OpenAI-compatible | `CUSTOM_OPENAI_API_KEY` plus base URL in settings |
205
+
206
+ OpenRouter default when that route is selected: `deepseek/deepseek-v4-flash-0731`.
207
+
208
+ OpenRouter Activity attributes CritiqueCode traffic to **critique.sh** (`HTTP-Referer: https://critique.sh`, title `critique.sh`), not to the underlying agent kernel.
209
+
210
+ Also:
211
+
212
+ - `CRITIQUE_CODE_HOME` — override `~/.critique/code`
213
+ - `CRITIQUE_CODE_MODELS` — same model list syntax as `--models`
214
+ - `CRITIQUE_INFERENCE_BASE_URL` — override `https://critique.sh/api/v1`
215
+ - `CRITIQUE_SITE_URL` — site origin for device login (default derived from the inference URL)
216
+ - `CRITIQUE_CODE_PI_DRIVER=off` — disable the live author kernel (sessions stay `kernel_required`)
217
+
218
+ ## Files on disk
219
+
220
+ Nothing secret is written into the repository.
221
+
222
+ | Path | Contents |
223
+ | --- | --- |
224
+ | `~/.critique/code/auth.json` | Stored API keys (mode `0600`) |
225
+ | `~/.critique/code/settings.json` | Route and model selection |
226
+ | Review/repair store | Outcomes and repair artifacts (`--store` or the default store root) |
227
+
228
+ Project `REVIEW_GUIDELINES.md` is loaded as a review constraint. `AGENTS.md`, `CRITIQUE.md`, and `CLAUDE.md` can seed author instructions.
229
+
230
+ ## Safety
231
+
232
+ - The model cannot pick a working directory, open a network path, or run a process on its own.
233
+ - `critique_run` is the only workspace exec path. You approve or deny each call. Output is not Evidence.
234
+ - Promotion of findings stays on `/review` and `/ship`.
235
+ - Named checks are controller-owned. Author check output is not Evidence.
236
+ - `none_promoted` is not a proof that the tree is correct.
237
+
238
+ ## Exit codes
239
+
240
+ | Code | Meaning |
241
+ | --- | --- |
242
+ | `0` | OK |
243
+ | `2` | Usage error |
244
+ | `3` | `kernel_required` (no live driver and/or no model route) |
245
+ | `4` | Blocked (review/repair ineligible, stale capsule, …) |
246
+ | `5` | Infrastructure error |
247
+
248
+ ## Runtime
249
+
250
+ The live author kernel is the open-source [Pi coding agent library](https://github.com/badlogic/pi-mono) (`@earendil-works/pi-coding-agent`). CritiqueCode **imports that library**. It does not spawn the `pi` CLI.
251
+
252
+ If the optional dependency failed to install, reinstall the package or install the library next to the binary. Set `CRITIQUE_CODE_PI_DRIVER=off` only when you want to disable the kernel on purpose.
253
+
254
+ ## License
255
+
256
+ MIT
257
+
258
+ ## Links
13
259
 
14
- Keys live in `~/.critique/code/`. Docs: [CritiqueCode](https://critique.sh/docs/platform/critique-code).
260
+ - npm: https://www.npmjs.com/package/@critiquedotsh/harness
261
+ - Docs: https://critique.sh/docs/platform/critique-code
262
+ - Inference API: https://critique.sh/inference-api
263
+ - Issues: https://github.com/repath500/critique/issues
264
+ - Sidecar CLI: https://www.npmjs.com/package/@critiquedotsh/cli