diffowl 0.3.3 → 0.5.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +140 -341
- package/dist/cli.js +11905 -4417
- package/dist/cli.js.map +1 -1
- package/package.json +14 -5
package/README.md
CHANGED
|
@@ -7,447 +7,255 @@
|
|
|
7
7
|
" "
|
|
8
8
|
```
|
|
9
9
|
|
|
10
|
-
|
|
11
|
-
>
|
|
12
|
-
> An independent reviewer that runs locally on every commit — on the model you already use, no matter which agent (or human) wrote the code.
|
|
13
|
-
|
|
14
|
-
Coding agents now write much of the code, but the agent that wrote a patch shouldn't be its only reviewer. DiffOwl is a separate, independent review pass: it builds bounded local context from your diff and asks a model for structured, durable findings. It works the same whether the change came from Claude Code, Cursor, OpenCode, or your own hands.
|
|
15
|
-
|
|
16
|
-
Under the hood it drives a headless [OpenCode](https://opencode.ai/docs/server/) session for model execution, so you bring your own provider and pay no one but them — no DiffOwl account, no service in the loop.
|
|
17
|
-
|
|
18
|
-
---
|
|
19
|
-
|
|
20
|
-
## Features
|
|
21
|
-
|
|
22
|
-
- **Agent-Agnostic**: Reviews code from any source — Claude Code, Cursor, OpenCode, or a human. The reviewer stays independent from whoever wrote the patch.
|
|
23
|
-
- **Provider-Neutral**: Runs on whatever model and provider you have configured in OpenCode (Copilot, OpenAI, local, and more). No separate keys, no DiffOwl account, no per-seat bill.
|
|
24
|
-
- **First-Class TypeScript Support**: Automatically extracts modified TypeScript AST nodes (functions, classes, interfaces, types, enums, methods, properties, and top-level const declarations) to feed rich, structured context to the AI reviewer.
|
|
25
|
-
- **Automatic Git Hooks**: Reviews run on every commit and stay out of your way — results land in `.diffowl/` when they are ready.
|
|
26
|
-
- **Review Chat Handoff**: Reopen the OpenCode session behind the latest or any selected review with `diffowl chat`.
|
|
27
|
-
- **Review Depth Profiles**: Choose `shallow` or `default` context strategies to match fast hooks or normal reviews.
|
|
28
|
-
- **Intelligent File Filtering**: Supports `include` and `exclude` glob patterns to focus reviews on source directories while skipping build artifacts, lockfiles, and node modules.
|
|
29
|
-
- **Project-Specific Rules**: Inject custom guidelines directly into the reviewer's system prompt (e.g., "Check for SQL injection", "Ensure TypeScript types are explicit").
|
|
30
|
-
- **Interactive Model Selector**: Automatically queries OpenCode to present a clean, interactive list of your connected providers and models.
|
|
31
|
-
- **Local Reports**: Generates markdown reviews under `.diffowl/reviews/`, including durable finding IDs and hidden session metadata that makes reports chat-capable.
|
|
32
|
-
- **Durable Findings (0.3)**: Persists reviews and findings in `.diffowl/state.db` with stable `fnd_*` IDs, occurrence tracking, and lifecycle commands for fix, dismiss, defer, and reopen.
|
|
33
|
-
- **Agent-Assisted Resolution**: Includes an optional portable skill that lets coding agents investigate findings, fix confirmed issues, record dismissals, and archive handled reports.
|
|
34
|
-
- **Hook Log Retention**: Bounds accumulated hook logs without deleting review history.
|
|
35
|
-
|
|
36
|
-
---
|
|
37
|
-
|
|
38
|
-
## Quick Start
|
|
39
|
-
|
|
40
|
-
### 1. Prerequisites
|
|
41
|
-
|
|
42
|
-
1. **Verify Node.js 22.14.0 or newer is installed**:
|
|
43
|
-
```bash
|
|
44
|
-
node --version
|
|
45
|
-
```
|
|
46
|
-
2. **Install OpenCode CLI**:
|
|
47
|
-
```bash
|
|
48
|
-
npm install --global opencode-ai
|
|
49
|
-
```
|
|
50
|
-
3. **Authenticate a provider and confirm a model is available**:
|
|
51
|
-
```bash
|
|
52
|
-
opencode
|
|
53
|
-
```
|
|
54
|
-
In OpenCode, connect or authenticate a provider such as GitHub Copilot, OpenAI, or Ollama. Confirm that at least one model is available before continuing.
|
|
55
|
-
|
|
56
|
-
### 2. Install DiffOwl
|
|
10
|
+
Review agent-written code with a second model before it ships.
|
|
57
11
|
|
|
58
|
-
|
|
59
|
-
npm install --global diffowl
|
|
60
|
-
```
|
|
12
|
+
DiffOwl is a local code review CLI. It builds focused context from a Git diff, runs a model through OpenCode or Codex, and records actionable findings in your repository.
|
|
61
13
|
|
|
62
|
-
|
|
14
|
+
It works with changes from any coding agent or human. You choose the backend and model on your machine. DiffOwl does not require a hosted DiffOwl account.
|
|
63
15
|
|
|
64
|
-
|
|
16
|
+
## Why DiffOwl
|
|
65
17
|
|
|
66
|
-
|
|
67
|
-
diffowl init
|
|
68
|
-
```
|
|
18
|
+
The agent that wrote a change should not be its only reviewer. Asking it to review its own work can repeat the same assumptions that produced the bug.
|
|
69
19
|
|
|
70
|
-
|
|
20
|
+
DiffOwl adds an independent pass between writing code and shipping it:
|
|
71
21
|
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
22
|
+
- Review the last commit, staged changes, a specific commit, or a whole branch.
|
|
23
|
+
- Review through OpenCode or a local Codex CLI authenticated with ChatGPT.
|
|
24
|
+
- Give the reviewer bounded local context instead of dumping the entire repository into a prompt.
|
|
25
|
+
- Keep findings after the review ends, with stable IDs and lifecycle states.
|
|
26
|
+
- Inspect and disposition durable findings after the review ends.
|
|
27
|
+
- Run reviews automatically after commits without blocking them.
|
|
76
28
|
|
|
77
|
-
|
|
78
|
-
> DiffOwl uses OpenCode's existing provider credentials. It does not configure provider keys itself. If initialization reports no active models, run `opencode`, connect or re-authenticate a provider, confirm a model is available, and rerun `diffowl init`.
|
|
29
|
+
TypeScript reviews can include changed AST symbols, related tests, file excerpts, and bounded import references. The structured import-reference section is TypeScript-only; non-TypeScript changes still get diff-centered review with targeted repository exploration.
|
|
79
30
|
|
|
80
|
-
|
|
31
|
+
## How it works
|
|
81
32
|
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
33
|
+
1. DiffOwl reads the Git change you selected.
|
|
34
|
+
2. It filters files and assembles relevant local context.
|
|
35
|
+
3. A separate model reviews the change through your selected local backend.
|
|
36
|
+
4. DiffOwl writes a Markdown report and persists findings in SQLite.
|
|
37
|
+
5. You inspect the findings, record their disposition, or hand them to a coding agent for resolution.
|
|
87
38
|
|
|
88
|
-
|
|
39
|
+
The orchestration and state stay in your repository. Review context goes only to the backend and model you selected.
|
|
89
40
|
|
|
90
|
-
|
|
91
|
-
2. Connect or re-authenticate the provider and confirm the configured model is available.
|
|
92
|
-
3. Retry with `diffowl review`.
|
|
41
|
+
## Quick start
|
|
93
42
|
|
|
94
|
-
|
|
43
|
+
You need Node.js 22.14.0 or newer. OpenCode is the default backend for existing installations.
|
|
95
44
|
|
|
96
45
|
```bash
|
|
97
|
-
|
|
46
|
+
npm install --global opencode-ai
|
|
47
|
+
opencode
|
|
98
48
|
```
|
|
99
49
|
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
## Resolve Findings With an Agent
|
|
103
|
-
|
|
104
|
-
DiffOwl can use an inexpensive model for review generation while a stronger coding agent verifies and resolves the resulting findings. The optional `diffowl-resolve` skill works with agents that support the open [Agent Skills](https://skills.sh/) format.
|
|
105
|
-
|
|
106
|
-
### Install the skill
|
|
107
|
-
|
|
108
|
-
Install the `diffowl-resolve` skill:
|
|
50
|
+
Connect a provider in OpenCode, then install and initialize DiffOwl:
|
|
109
51
|
|
|
110
52
|
```bash
|
|
111
|
-
|
|
53
|
+
npm install --global diffowl
|
|
54
|
+
cd your-repository
|
|
55
|
+
diffowl init
|
|
112
56
|
```
|
|
113
57
|
|
|
114
|
-
|
|
58
|
+
`diffowl init` reports the selected runtime and the gitignored preference path. With OpenCode selected, it lists the models from your connected providers. Use `diffowl backend codex` before initialization if you want Codex, then choose a bare Codex model ID. The committed `.diffowl.yml` contains review policy, never your backend or model choice.
|
|
115
59
|
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
First generate a review:
|
|
60
|
+
Codex reviews use an existing ChatGPT login from the local Codex CLI:
|
|
119
61
|
|
|
120
62
|
```bash
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
Then ask your coding agent in plain language:
|
|
125
|
-
|
|
126
|
-
```text
|
|
127
|
-
Resolve the latest DiffOwl review.
|
|
63
|
+
codex
|
|
64
|
+
diffowl backend codex
|
|
65
|
+
diffowl model gpt-5-codex
|
|
128
66
|
```
|
|
129
67
|
|
|
130
|
-
|
|
68
|
+
Review the last commit:
|
|
131
69
|
|
|
132
|
-
```
|
|
133
|
-
|
|
134
|
-
Resolve all open DiffOwl reviews.
|
|
135
|
-
Resolve the latest 3 DiffOwl reviews.
|
|
136
|
-
Check whether the older DiffOwl findings have already been fixed.
|
|
137
|
-
Archive fully resolved DiffOwl reviews.
|
|
70
|
+
```bash
|
|
71
|
+
diffowl
|
|
138
72
|
```
|
|
139
73
|
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
1. Treat findings as candidates and verify them against the current code.
|
|
143
|
-
2. Fix confirmed issues using the repository's normal workflow.
|
|
144
|
-
3. For durable findings (0.3+), record lifecycle status with `diffowl findings fix`, `dismiss`, or `defer`.
|
|
145
|
-
4. For legacy reports, mark findings as fixed, already fixed, agent dismissed, user dismissed, deferred, or open in a `## Resolution` checklist.
|
|
146
|
-
5. Append or merge resolution state without rewriting the generated review body.
|
|
147
|
-
6. Move fully handled timestamped reports into `.diffowl/reviews/resolved/` when every finding is complete.
|
|
148
|
-
|
|
149
|
-
`latest.md` is only a copy of the newest report and is overwritten by future reviews. Markdown reports from 0.3+ are immutable snapshots; SQLite is the authoritative backlog for durable findings.
|
|
150
|
-
|
|
151
|
-
For legacy pre-0.3 reports, resolution state is appended under `## Resolution`. To reopen the OpenCode session for an archived report, pass its explicit path:
|
|
74
|
+
Or review work before committing:
|
|
152
75
|
|
|
153
76
|
```bash
|
|
154
|
-
|
|
77
|
+
git add -p
|
|
78
|
+
diffowl review --staged
|
|
155
79
|
```
|
|
156
80
|
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
| Status | Meaning | Complete? |
|
|
160
|
-
| --------------- | ------------------------------------------------------------- | --------- |
|
|
161
|
-
| Fixed | The agent changed code or configuration and verified the fix. | Yes |
|
|
162
|
-
| Already fixed | Current code no longer exhibits the reported issue. | Yes |
|
|
163
|
-
| Agent dismissed | Investigation showed the finding was noise or incorrect. | Yes |
|
|
164
|
-
| User dismissed | You explicitly chose not to address the finding. | Yes |
|
|
165
|
-
| Deferred | The issue is valid but intentionally left for later. | No |
|
|
166
|
-
| Open | The finding has not been fully investigated. | No |
|
|
167
|
-
|
|
168
|
-
Reports containing deferred or open findings remain in `.diffowl/reviews/`. DiffOwl never deletes review history automatically.
|
|
169
|
-
|
|
170
|
-
### Troubleshooting
|
|
171
|
-
|
|
172
|
-
- **No review exists:** Run `diffowl review` first, or install `diffowl hook install` and make a commit.
|
|
173
|
-
- **The agent does not load the skill:** Verify project installation with `npx skills list` or global installation with `npx skills list --global`, then restart or reload the agent.
|
|
174
|
-
- **The skill is installed for the wrong agent:** Reinstall with `--agent <agent-name>`, or use `--agent '*'` to install for every detected agent.
|
|
175
|
-
- **A hook review timed out:** Run the retry command shown by the next foreground DiffOwl command, or retry manually with `diffowl review --commit <sha> --depth shallow`.
|
|
176
|
-
- **You prefer manual resolution:** Edit code normally; the skill is optional and does not affect the DiffOwl CLI.
|
|
177
|
-
|
|
178
|
-
---
|
|
179
|
-
|
|
180
|
-
## CLI Reference
|
|
181
|
-
|
|
182
|
-
### `diffowl` (or `diffowl review`)
|
|
81
|
+
The latest report is written to `.diffowl/reviews/latest.md`.
|
|
183
82
|
|
|
184
|
-
|
|
83
|
+
## Choose what to review
|
|
185
84
|
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
- `--reasoning <effort>`: Overrides configured OpenCode reasoning variant. Valid values: `auto`, `none`, `minimal`, `low`, `medium`, `high`, `max`, `xhigh`.
|
|
194
|
-
- `--verbose`: Includes suppressed findings and extra review details in the report.
|
|
195
|
-
- `--format <format>`: Output format: `text` (default) or `json`. JSON writes a versioned document to stdout and persists SQLite state. Review `status` is `open` when unsuppressed `error`/`warning` findings remain, `advisory` when only `info` findings remain, `resolved` when none remain, or `skipped`.
|
|
85
|
+
| Command | Reviews |
|
|
86
|
+
| ------------------------------- | ------------------------------------------------- |
|
|
87
|
+
| `diffowl` | The last commit |
|
|
88
|
+
| `diffowl review --staged` | Staged changes |
|
|
89
|
+
| `diffowl review --commit <ref>` | One commit |
|
|
90
|
+
| `diffowl review --base` | Committed branch changes since the default branch |
|
|
91
|
+
| `diffowl review --base <ref>` | Committed branch changes since an explicit base |
|
|
196
92
|
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
Rendered findings use stable `Finding N` headings. Reports from DiffOwl 0.3+ also include durable `fnd_*` IDs and observation classification (`new`, `existing`, `regressed`), making prompts such as “investigate finding 2” or `diffowl findings show fnd_abc` map directly to the backlog.
|
|
200
|
-
|
|
201
|
-
Review depth controls both how much local context DiffOwl preloads and how much exploration the reviewer is expected to do:
|
|
202
|
-
|
|
203
|
-
- `shallow`: Cheap, surface-level review. Uses a smaller diff-centered prompt with no AI tools enabled. It is expected to miss deeper issues, but can catch obvious local bugs such as off-by-one errors, inverted conditions, unsafe null handling, missing awaits, and implementation anti-patterns visible in the diff.
|
|
204
|
-
- `default`: Normal review. Includes changed TypeScript AST symbols, small file excerpts, related tests, and bounded Potential Call Flow snippets from `git grep`. Permissionless read/search tools are enabled for targeted exploration when context is incomplete; permission prompts are rejected.
|
|
93
|
+
Useful review options:
|
|
205
94
|
|
|
206
95
|
```bash
|
|
207
|
-
#
|
|
208
|
-
diffowl
|
|
209
|
-
|
|
210
|
-
# Review staged files
|
|
211
|
-
diffowl review --staged
|
|
96
|
+
# Faster review with less context
|
|
97
|
+
diffowl review --staged --depth shallow
|
|
212
98
|
|
|
213
|
-
#
|
|
214
|
-
diffowl review --
|
|
99
|
+
# Use a different model once
|
|
100
|
+
diffowl review --staged --model openai/gpt-5.6-luna
|
|
215
101
|
|
|
216
|
-
#
|
|
217
|
-
diffowl review --
|
|
102
|
+
# Use Codex once without changing saved preferences
|
|
103
|
+
diffowl review --staged --backend codex --model gpt-5-codex
|
|
218
104
|
|
|
219
|
-
#
|
|
220
|
-
diffowl review --base
|
|
105
|
+
# Emit a versioned JSON document for scripts
|
|
106
|
+
diffowl review --base --format json
|
|
221
107
|
|
|
222
|
-
#
|
|
223
|
-
diffowl review --base
|
|
224
|
-
|
|
225
|
-
# Include suppressed outside-file findings in the report
|
|
226
|
-
diffowl review --staged --verbose
|
|
227
|
-
|
|
228
|
-
# Request a high reasoning variant for models that support it
|
|
229
|
-
diffowl review --staged --reasoning high
|
|
108
|
+
# Exit 1 when actionable findings remain
|
|
109
|
+
diffowl review --base --fail-on-findings
|
|
230
110
|
```
|
|
231
111
|
|
|
232
|
-
Branch review uses merge
|
|
233
|
-
request. It never includes staged or unstaged changes. `--base` cannot be combined with `--staged`
|
|
234
|
-
or `--commit`; use those as separate review surfaces.
|
|
112
|
+
Branch review uses the merge base through `HEAD`, matching the committed diff in a pull request. It does not include staged or unstaged changes.
|
|
235
113
|
|
|
236
|
-
|
|
114
|
+
## Work with findings
|
|
237
115
|
|
|
238
|
-
|
|
239
|
-
gitignored `.diffowl/preferences.yml`, so every linked worktree uses the same model without changing
|
|
240
|
-
the committed `.diffowl.yml`.
|
|
116
|
+
DiffOwl stores durable findings in `.diffowl/state.db`. A finding stays open until someone records what happened to it. A later model review that fails to mention it does not silently mark it fixed.
|
|
241
117
|
|
|
242
118
|
```bash
|
|
243
|
-
#
|
|
244
|
-
diffowl
|
|
245
|
-
|
|
246
|
-
# Manually set a model
|
|
247
|
-
diffowl model opencode/big-pickle
|
|
119
|
+
# List unresolved findings
|
|
120
|
+
diffowl findings
|
|
248
121
|
|
|
249
|
-
#
|
|
250
|
-
diffowl
|
|
122
|
+
# Inspect a finding by ID, ID prefix, or latest:N
|
|
123
|
+
diffowl findings show fnd_abc
|
|
251
124
|
|
|
252
|
-
#
|
|
253
|
-
diffowl
|
|
125
|
+
# Record the outcome
|
|
126
|
+
diffowl findings fix fnd_abc --note "Added a null guard." --verified-by "pnpm run test"
|
|
127
|
+
diffowl findings dismiss fnd_abc --reason "The caller already validates this value."
|
|
128
|
+
diffowl findings defer fnd_abc --reason "Blocked by an upstream change."
|
|
129
|
+
diffowl findings reopen fnd_abc --reason "The bug returned in a new path."
|
|
254
130
|
```
|
|
255
131
|
|
|
256
|
-
|
|
257
|
-
review commands ask you to configure a model rather than assuming provider access.
|
|
132
|
+
Use `--format json` with `findings list`, `show`, or `summary` when another tool needs the backlog.
|
|
258
133
|
|
|
259
|
-
|
|
134
|
+
Inspect a finding with `diffowl findings show`, then record its disposition with `fix`, `dismiss`, `defer`, or `reopen`. Run a new review when you need new model analysis.
|
|
260
135
|
|
|
261
|
-
|
|
136
|
+
## Resolve findings with a coding agent
|
|
137
|
+
|
|
138
|
+
The optional `diffowl-resolve` skill lets a coding agent investigate findings instead of accepting the review at face value. It verifies each candidate against the current code, fixes confirmed problems, records dismissals or deferrals, and preserves the report history.
|
|
262
139
|
|
|
263
140
|
```bash
|
|
264
|
-
|
|
265
|
-
|
|
141
|
+
npx skills add gutierrezje/diffowl --skill diffowl-resolve
|
|
142
|
+
```
|
|
266
143
|
|
|
267
|
-
|
|
268
|
-
diffowl chat review-2026-06-07T07-30-42-762Z.md
|
|
144
|
+
Restart or reload the agent, then ask:
|
|
269
145
|
|
|
270
|
-
|
|
271
|
-
|
|
146
|
+
```text
|
|
147
|
+
Resolve the latest DiffOwl review.
|
|
272
148
|
```
|
|
273
149
|
|
|
274
|
-
|
|
150
|
+
You can also ask it to investigate one finding, resolve every open review, or archive reports whose findings are fully handled.
|
|
275
151
|
|
|
276
|
-
|
|
152
|
+
## Run reviews automatically
|
|
277
153
|
|
|
278
|
-
|
|
154
|
+
Install the non-blocking post-commit hook:
|
|
279
155
|
|
|
280
156
|
```bash
|
|
281
|
-
# Install non-blocking post-commit review hook
|
|
282
157
|
diffowl hook install
|
|
283
|
-
|
|
284
|
-
# Check whether the hook is installed and up to date
|
|
285
|
-
diffowl hook status
|
|
286
|
-
|
|
287
|
-
# Uninstall the hook
|
|
288
|
-
diffowl hook uninstall
|
|
289
158
|
```
|
|
290
159
|
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
Only one hook review runs per project at a time. Each commit is recorded under `.diffowl/pending-reviews/`, and a background worker processes pending commits in order. Successful reviews remove their marker; failed reviews remain pending and are retried when a later commit triggers the hook. Review failures are recorded with their commit SHA in `.diffowl/last-hook-status.json` and reported on the next foreground review with commands to retry at default or shallow depth. Result files without a matching pending marker are removed automatically.
|
|
294
|
-
|
|
295
|
-
### `diffowl server start | stop | status`
|
|
296
|
-
|
|
297
|
-
Manually manage the OpenCode server lifecycle.
|
|
160
|
+
The hook queues each commit, returns control to the terminal, and writes output to `.diffowl/hook.log`. Failed reviews remain pending and retry after a later commit.
|
|
298
161
|
|
|
299
162
|
```bash
|
|
300
|
-
|
|
301
|
-
diffowl
|
|
302
|
-
|
|
303
|
-
# Start it manually
|
|
304
|
-
diffowl server start
|
|
305
|
-
|
|
306
|
-
# Stop the server
|
|
307
|
-
diffowl server stop
|
|
163
|
+
diffowl hook status
|
|
164
|
+
diffowl hook uninstall
|
|
308
165
|
```
|
|
309
166
|
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
Inspect and manage the durable findings backlog stored in the repo's shared `.diffowl/state.db`.
|
|
167
|
+
Claude Code users can also show the current finding summary when a session starts:
|
|
313
168
|
|
|
314
169
|
```bash
|
|
315
|
-
|
|
316
|
-
diffowl findings
|
|
317
|
-
|
|
318
|
-
# Machine-readable backlog for agents and scripts
|
|
319
|
-
diffowl findings --format json
|
|
320
|
-
|
|
321
|
-
# Inspect one finding by full id, id prefix, or latest:N
|
|
322
|
-
diffowl findings show fnd_abc --format json
|
|
323
|
-
|
|
324
|
-
# Mark fixed after verification
|
|
325
|
-
diffowl findings fix fnd_abc --note "Added null guard." --verified-by "pnpm run test"
|
|
326
|
-
|
|
327
|
-
# Dismiss a false positive
|
|
328
|
-
diffowl findings dismiss fnd_abc --reason "Guarded by caller."
|
|
329
|
-
|
|
330
|
-
# Defer intentionally
|
|
331
|
-
diffowl findings defer fnd_abc --reason "Needs upstream change."
|
|
332
|
-
|
|
333
|
-
# Reopen a previously fixed or dismissed finding
|
|
334
|
-
diffowl findings reopen fnd_abc --reason "Regression in new path."
|
|
170
|
+
diffowl agent-hook install --client claude
|
|
335
171
|
```
|
|
336
172
|
|
|
337
|
-
|
|
338
|
-
|
|
339
|
-
The unresolved backlog is durable: a finding does not auto-resolve just because a later review fails to mention it. Absence from a later model review never marks a finding fixed.
|
|
173
|
+
## Configuration
|
|
340
174
|
|
|
341
|
-
|
|
342
|
-
|
|
343
|
-
## Configuration (`.diffowl.yml`)
|
|
344
|
-
|
|
345
|
-
Your committed `.diffowl.yml` configures repository review policy. Model selection is deliberately
|
|
346
|
-
absent because provider access belongs to each developer. Legacy `model` keys remain readable for
|
|
347
|
-
compatibility but are ignored and removed the next time DiffOwl saves project config.
|
|
175
|
+
Project review policy lives in `.diffowl.yml`. Backend and model selection stay in the shared, gitignored `.diffowl/preferences.yml`. Linked worktrees use the same preference file.
|
|
348
176
|
|
|
349
177
|
```yaml
|
|
350
|
-
# OpenCode server settings
|
|
351
|
-
server:
|
|
352
|
-
port: 4096
|
|
353
|
-
auto_start: true
|
|
354
|
-
|
|
355
|
-
# Local review context strategy: shallow or default
|
|
356
178
|
context:
|
|
357
179
|
depth: default
|
|
358
180
|
|
|
359
|
-
# OpenCode model variant for reasoning/thinking effort.
|
|
360
|
-
# auto leaves the selected model/provider default alone.
|
|
361
181
|
reasoning:
|
|
362
182
|
effort: auto
|
|
363
183
|
|
|
364
|
-
|
|
365
|
-
|
|
366
|
-
# Before each hook review, retain approximately this many KiB
|
|
367
|
-
# of previous hook.log output. The new run may exceed this target.
|
|
368
|
-
hook_log_kb: 1024
|
|
184
|
+
gate:
|
|
185
|
+
fail_on_findings: false
|
|
369
186
|
|
|
370
|
-
# Review timeout in seconds
|
|
371
187
|
timeout: 300
|
|
372
|
-
|
|
373
|
-
# Minimum confidence level of findings to report: low, medium, or high
|
|
374
188
|
min_confidence: medium
|
|
375
|
-
|
|
376
|
-
# Skip reviews when every changed file is documentation-like
|
|
377
189
|
skip_doc_only: false
|
|
378
190
|
|
|
379
|
-
# Include suppressed outside-file findings and extra details in reports
|
|
380
|
-
verbose: false
|
|
381
|
-
|
|
382
|
-
# Review scope
|
|
383
191
|
include:
|
|
384
192
|
- "src/**/*"
|
|
385
|
-
- "lib/**/*"
|
|
386
193
|
|
|
387
194
|
exclude:
|
|
388
195
|
- "**/*.test.*"
|
|
389
|
-
- "**/*.spec.*"
|
|
390
196
|
- "**/*.lock"
|
|
391
|
-
- "**/node_modules/**"
|
|
392
197
|
- "**/dist/**"
|
|
393
|
-
- "**/build/**"
|
|
394
198
|
|
|
395
|
-
# Custom project-specific review rules
|
|
396
199
|
rules:
|
|
397
|
-
- "
|
|
398
|
-
- "
|
|
399
|
-
- "Suggest readability and architectural improvements where relevant"
|
|
200
|
+
- "Flag hardcoded secrets."
|
|
201
|
+
- "Check authorization at every write boundary."
|
|
400
202
|
```
|
|
401
203
|
|
|
402
|
-
|
|
204
|
+
Inspect or change the local backend and its model without editing project policy:
|
|
403
205
|
|
|
404
|
-
|
|
405
|
-
|
|
406
|
-
|
|
206
|
+
```bash
|
|
207
|
+
diffowl backend
|
|
208
|
+
diffowl backend opencode
|
|
209
|
+
diffowl backend codex
|
|
210
|
+
diffowl backend --reset
|
|
407
211
|
|
|
408
|
-
|
|
409
|
-
|
|
410
|
-
|
|
411
|
-
.diffowl/reviews/latest.md # Ephemeral copy of the newest report
|
|
412
|
-
.diffowl/reviews/resolved/review-<timestamp>.md # Fully handled report archived by the skill
|
|
212
|
+
diffowl model
|
|
213
|
+
diffowl model provider/model
|
|
214
|
+
diffowl model --reset
|
|
413
215
|
```
|
|
414
216
|
|
|
415
|
-
|
|
416
|
-
|
|
417
|
-
```yaml
|
|
418
|
-
---
|
|
419
|
-
diffowl:
|
|
420
|
-
schema_version: 1
|
|
421
|
-
review_id: rev_...
|
|
422
|
-
session_id: ses_...
|
|
423
|
-
project_root: /path/to/project
|
|
424
|
-
---
|
|
425
|
-
```
|
|
217
|
+
Each backend keeps its own model choice. Switching backends does not erase the other model. A legacy preference containing only `model: provider/model` still selects OpenCode.
|
|
426
218
|
|
|
427
|
-
|
|
219
|
+
Configuration is deep-merged with defaults, so the file only needs the settings your repository changes.
|
|
428
220
|
|
|
429
|
-
|
|
430
|
-
#### Finding 1 (`fnd_...`) — **new**
|
|
221
|
+
## Files DiffOwl creates
|
|
431
222
|
|
|
432
|
-
|
|
433
|
-
|
|
223
|
+
```text
|
|
224
|
+
.diffowl.yml # Committed project policy
|
|
225
|
+
.diffowl/preferences.yml # Gitignored backend and model choices
|
|
226
|
+
.diffowl/state.db # Authoritative findings backlog
|
|
227
|
+
.diffowl/reviews/review-<timestamp>.md # Immutable review snapshot
|
|
228
|
+
.diffowl/reviews/latest.md # Copy of the newest report
|
|
229
|
+
.diffowl/reviews/resolved/ # Reports archived by the resolution skill
|
|
434
230
|
```
|
|
435
231
|
|
|
436
|
-
|
|
232
|
+
Linked Git worktrees share the durable backlog and review reports from the primary checkout. Runtime files such as hook logs and server state remain checkout-specific.
|
|
437
233
|
|
|
438
|
-
|
|
234
|
+
## Command reference
|
|
439
235
|
|
|
440
|
-
|
|
441
|
-
|
|
442
|
-
|
|
443
|
-
|
|
444
|
-
|
|
236
|
+
| Command | Purpose |
|
|
237
|
+
| -------------------- | ------------------------------------------- |
|
|
238
|
+
| `diffowl init` | Configure DiffOwl in the current repository |
|
|
239
|
+
| `diffowl review` | Run a review |
|
|
240
|
+
| `diffowl backend` | Inspect or change the local review backend |
|
|
241
|
+
| `diffowl model` | View or change the selected model |
|
|
242
|
+
| `diffowl findings` | Inspect and update durable findings |
|
|
243
|
+
| `diffowl hook` | Manage the post-commit hook |
|
|
244
|
+
| `diffowl agent-hook` | Manage supported agent client hooks |
|
|
245
|
+
| `diffowl server` | Manage the local OpenCode server |
|
|
445
246
|
|
|
446
|
-
|
|
247
|
+
Run `diffowl <command> --help` for every option.
|
|
447
248
|
|
|
448
|
-
##
|
|
249
|
+
## Troubleshooting
|
|
449
250
|
|
|
450
|
-
|
|
251
|
+
- No models found: run `opencode`, connect or re-authenticate a provider, then rerun `diffowl init`.
|
|
252
|
+
- Codex runtime missing: install the Codex CLI and make sure `codex` is on `PATH`.
|
|
253
|
+
- Codex authentication missing: run `codex` and sign in with ChatGPT.
|
|
254
|
+
- Review timed out: retry with `diffowl review --depth shallow`.
|
|
255
|
+
- Hook review failed: run the retry command shown by the next foreground DiffOwl command, or inspect `.diffowl/hook.log`.
|
|
256
|
+
- Agent did not load `diffowl-resolve`: verify it with `npx skills list`, then restart or reload the agent.
|
|
257
|
+
|
|
258
|
+
## Develop locally
|
|
451
259
|
|
|
452
260
|
```bash
|
|
453
261
|
git clone https://github.com/gutierrezje/diffowl.git
|
|
@@ -457,23 +265,14 @@ pnpm run build
|
|
|
457
265
|
pnpm link --global
|
|
458
266
|
```
|
|
459
267
|
|
|
460
|
-
|
|
461
|
-
|
|
462
|
-
```bash
|
|
463
|
-
pnpm run build
|
|
464
|
-
git add -p
|
|
465
|
-
diffowl review --staged
|
|
466
|
-
```
|
|
467
|
-
|
|
468
|
-
To verify model discovery against an authenticated OpenCode server already running on port 4096:
|
|
268
|
+
Run the checks:
|
|
469
269
|
|
|
470
270
|
```bash
|
|
471
|
-
|
|
271
|
+
pnpm run lint
|
|
272
|
+
pnpm run test
|
|
472
273
|
```
|
|
473
274
|
|
|
474
|
-
|
|
475
|
-
|
|
476
|
-
---
|
|
275
|
+
After changing `src/**`, rebuild before testing the globally linked `diffowl` command.
|
|
477
276
|
|
|
478
277
|
## License
|
|
479
278
|
|