debrief-cli 0.1.0__tar.gz

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 (42) hide show
  1. debrief_cli-0.1.0/.gitignore +7 -0
  2. debrief_cli-0.1.0/LICENSE +21 -0
  3. debrief_cli-0.1.0/PKG-INFO +205 -0
  4. debrief_cli-0.1.0/README.md +186 -0
  5. debrief_cli-0.1.0/debrief/__init__.py +0 -0
  6. debrief_cli-0.1.0/debrief/build_artifact.py +83 -0
  7. debrief_cli-0.1.0/debrief/classify.py +812 -0
  8. debrief_cli-0.1.0/debrief/cli.py +291 -0
  9. debrief_cli-0.1.0/debrief/compare_definitions.py +147 -0
  10. debrief_cli-0.1.0/debrief/compare_llm.py +250 -0
  11. debrief_cli-0.1.0/debrief/config.py +204 -0
  12. debrief_cli-0.1.0/debrief/db.py +341 -0
  13. debrief_cli-0.1.0/debrief/export.py +156 -0
  14. debrief_cli-0.1.0/debrief/export_site.py +661 -0
  15. debrief_cli-0.1.0/debrief/github.py +540 -0
  16. debrief_cli-0.1.0/debrief/normalize.py +635 -0
  17. debrief_cli-0.1.0/debrief/paths.py +17 -0
  18. debrief_cli-0.1.0/debrief/prune.py +117 -0
  19. debrief_cli-0.1.0/debrief/recommend.py +271 -0
  20. debrief_cli-0.1.0/debrief/relay.py +83 -0
  21. debrief_cli-0.1.0/debrief/runner.py +163 -0
  22. debrief_cli-0.1.0/debrief/scrape.py +208 -0
  23. debrief_cli-0.1.0/debrief/site/app.js +1613 -0
  24. debrief_cli-0.1.0/debrief/site/index.html +32 -0
  25. debrief_cli-0.1.0/debrief/site/method.js +117 -0
  26. debrief_cli-0.1.0/debrief/site/style.css +520 -0
  27. debrief_cli-0.1.0/debrief/skills.py +107 -0
  28. debrief_cli-0.1.0/debrief/sources.py +341 -0
  29. debrief_cli-0.1.0/debrief/synthesize.py +1052 -0
  30. debrief_cli-0.1.0/debrief/verify_evidence.py +154 -0
  31. debrief_cli-0.1.0/pyproject.toml +45 -0
  32. debrief_cli-0.1.0/tests/conftest.py +8 -0
  33. debrief_cli-0.1.0/tests/test_classify.py +154 -0
  34. debrief_cli-0.1.0/tests/test_cli.py +379 -0
  35. debrief_cli-0.1.0/tests/test_config.py +158 -0
  36. debrief_cli-0.1.0/tests/test_export_site.py +101 -0
  37. debrief_cli-0.1.0/tests/test_export_site_db.py +160 -0
  38. debrief_cli-0.1.0/tests/test_github.py +312 -0
  39. debrief_cli-0.1.0/tests/test_paths.py +29 -0
  40. debrief_cli-0.1.0/tests/test_relay.py +95 -0
  41. debrief_cli-0.1.0/tests/test_sources.py +475 -0
  42. debrief_cli-0.1.0/tests/test_synthesize.py +251 -0
@@ -0,0 +1,7 @@
1
+ .venv/
2
+ __pycache__/
3
+ .env
4
+ .ruff_cache/
5
+ .pytest_cache/
6
+ dist/
7
+ *.db
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Michael Williams
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,205 @@
1
+ Metadata-Version: 2.5
2
+ Name: debrief-cli
3
+ Version: 0.1.0
4
+ Summary: Review your coding-agent sessions: what went wrong, and what to change.
5
+ Project-URL: Homepage, https://github.com/mvwi/debrief
6
+ Project-URL: Issues, https://github.com/mvwi/debrief/issues
7
+ License-Expression: MIT
8
+ License-File: LICENSE
9
+ Keywords: claude-code,codex,coding-agent,report,session-logs
10
+ Classifier: Development Status :: 3 - Alpha
11
+ Classifier: Environment :: Console
12
+ Classifier: Intended Audience :: Developers
13
+ Classifier: Programming Language :: Python :: 3.13
14
+ Classifier: Topic :: Software Development
15
+ Requires-Python: >=3.13
16
+ Requires-Dist: httpx>=0.28.1
17
+ Requires-Dist: python-dotenv>=1.2.3
18
+ Description-Content-Type: text/markdown
19
+
20
+ # debrief
21
+
22
+ Review your coding-agent sessions: where you had to correct the agent, what it missed, and what
23
+ to change so it happens less.
24
+
25
+ debrief reads the session logs Claude Code and Codex already keep on your machine, labels each
26
+ of your turns, groups the labels into findings with evidence, and builds a local report site.
27
+
28
+ ## Install
29
+
30
+ With Homebrew on a Mac:
31
+
32
+ brew install mvwi/tap/debrief
33
+
34
+ With uv or pipx, on Python 3.13 or newer:
35
+
36
+ uv tool install debrief-cli
37
+ pipx install debrief-cli
38
+
39
+ The package on PyPI is `debrief-cli`; the command it installs is `debrief`. The PyPI package
40
+ named `debrief` is a different project, so `uvx debrief` and `pip install debrief` fetch the
41
+ wrong tool. To run debrief once without installing it:
42
+
43
+ uvx --from debrief-cli debrief open
44
+
45
+ From source:
46
+
47
+ git clone https://github.com/mvwi/debrief && cd debrief
48
+ uv tool install .
49
+
50
+ The default labeler runs through `claude -p` on your Claude subscription, so it needs a
51
+ logged-in `claude` CLI. Without one, pick OpenRouter and save a key on the Settings page of
52
+ `debrief open`. `gh` is optional: with it, `debrief sync` adds pull-request data.
53
+
54
+ ## Use
55
+
56
+ debrief sync --dry-run # ingest logs, then say how many model calls labeling would take
57
+ debrief sync # ingest, label, find patterns, build the report
58
+ debrief open # serve the report at http://127.0.0.1:8765 and open it
59
+
60
+ Useful flags for `sync`:
61
+
62
+ --project DIR add this project to the ones sync analyses
63
+ --since YYYY-MM-DD only logs and evidence from this date on
64
+ --import DIR also load a folder of JSONL logs (Claude Code, Codex or Pi format)
65
+ --include-headless also load scripted runs (see below)
66
+ --llm openrouter label and synthesize through OpenRouter, whatever config.toml says
67
+
68
+ A re-run only reads logs that changed and only labels turns that are new.
69
+
70
+ You pick which projects get analysed. A project is the folder a session ran in. The first
71
+ `debrief sync` reads your logs, lists the projects it found with their size, and stops:
72
+
73
+ debrief sync --project ~/Dev/myrepo # pick it (kept in config.toml), then analyse
74
+
75
+ Only picked projects are labeled, analysed and shown. Each gets its own findings and ideas,
76
+ and an idea names the project it lands in (`myrepo: CLAUDE.md`). The picker in the report's
77
+ side bar scopes every page to one project. Findings about how you prompt come from the picked
78
+ projects together. To drop a project:
79
+
80
+ debrief config --drop ~/Dev/myrepo # its findings stay in the database, hidden
81
+
82
+ Unticking it on the Projects page does the same.
83
+
84
+ `debrief <stage> --help` runs one stage on its own: `ingest`, `label`, `synthesize`,
85
+ `recommend`, `verify`, `export`, `prune`.
86
+
87
+ ## What gets loaded
88
+
89
+ - Claude Code logs in `~/.claude/projects` and Codex logs in `~/.codex/sessions`.
90
+ - Scripted runs are skipped by default: `claude -p`, `codex exec`, and sessions started through
91
+ an SDK or a wrapper app that have fewer than two turns from a person. On the author's machine
92
+ that was 1,038 of 1,274 logs.
93
+ - Sub-agent logs are skipped, so tool calls made inside a sub-agent are not counted.
94
+ - A resumed or forked session copies its history into the new log. Each turn is loaded once.
95
+
96
+ ## Where your data goes
97
+
98
+ - Everything debrief writes is under `~/.local/share/debrief` (set `DEBRIEF_HOME` to move it).
99
+ - Labeling and synthesis send transcript text to a model: by default Claude, through your own
100
+ `claude` CLI. With `--llm openrouter` it goes to OpenRouter and needs `OPENROUTER_API_KEY`.
101
+ - `debrief sync` asks GitHub about the pull requests your sessions produced, through your own
102
+ logged-in `gh` CLI and read-only. It sends repo names, PR numbers, branch names and commit
103
+ SHAs, and nothing from your transcripts. `--no-github`, or `[github] enabled = false` in
104
+ config.toml, turns it off; without `gh` it is skipped.
105
+ - The report holds your transcripts. `debrief open` serves it on 127.0.0.1 only. Token-shaped
106
+ strings (GitHub, Anthropic, OpenAI, AWS, Slack, Stripe, private keys and others) are replaced
107
+ with `[redacted]` in the report, but the redaction is pattern-based: read before you share.
108
+
109
+ ## Which labeler
110
+
111
+ | | Claude Haiku (default) | Jev (`--llm openrouter`) |
112
+ |---|---|---|
113
+ | Needs | a Claude subscription | an OpenRouter key |
114
+ | Sends transcripts to | Anthropic, via your CLI | OpenRouter |
115
+ | Confidence | the model's own estimate | token probabilities |
116
+ | 2,774 items (236 sessions) | 33 min, no extra charge | about 3 min, about $0.37 |
117
+
118
+ The Jev time and cost are scaled up from a 74-item run (4 s, $0.0098).
119
+
120
+ To pick the model for each stage, write `~/.local/share/debrief/config.toml`:
121
+
122
+ [label]
123
+ llm = "openrouter" # Jev: faster and closer to a careful reader, needs a key
124
+ [synthesize]
125
+ model = "claude-sonnet-5" # optional; each llm has a default
126
+
127
+ Stages are `label`, `synthesize`, `recommend` and `verify`. `debrief config` prints what each
128
+ will use. A flag beats an environment variable, which beats the file.
129
+
130
+ ### Settings page
131
+
132
+ `debrief open` has a Settings page that does the same without editing files. It picks the
133
+ provider and model for each stage, turns the GitHub lookups on or off, and saves an OpenRouter
134
+ key.
135
+
136
+ Saving needs the link `debrief open` prints, which carries a token for that run: someone else
137
+ on the same machine can reach the port but cannot change your settings. They can still read the
138
+ report, as they can read the files.
139
+
140
+ - Saving rewrites `config.toml`; comments you wrote in it are lost.
141
+ - The key goes in `~/.local/share/debrief/.env`, readable only by you. The page shows its last
142
+ four characters and never the key. `OPENROUTER_API_KEY` set in your shell wins over the saved one.
143
+ - The server takes these writes only from a page it served itself, on `127.0.0.1`.
144
+
145
+ ### Run from the page
146
+
147
+ `debrief open` can also run the analysis, so you need not go back to the terminal. With no
148
+ report yet it reads your local logs first (no model calls) and serves what it found.
149
+
150
+ The Projects page is where you do it: tick the projects to analyse (each tick is saved to
151
+ `config.toml` at once), ask for an estimate, then press "Check my data now". It shows the stage
152
+ and the count while the run goes, and has a Cancel button. When the run ends every page shows
153
+ the new report without a refresh. Underneath it uses:
154
+
155
+ GET /api/run state (idle, running, done, failed, cancelled), stage, done/total,
156
+ start and end times, exit code, last 30 lines of output
157
+ POST /api/run start `debrief sync`; 409 if a run or an estimate is going
158
+ DELETE /api/run stop the run and the `claude -p` calls it started
159
+ POST /api/estimate run `debrief sync --dry-run`, rebuild the pages, return the counts
160
+
161
+ - The writes need the same token as the Settings page. Nothing in a request reaches the command
162
+ line: what to analyse comes from `config.toml`.
163
+ - One run at a time. Its output is in `~/.local/share/debrief/run.log`, replaced on each run,
164
+ with the OpenRouter key blanked.
165
+ - Ctrl-C stops a run too. If the server is killed outright, the next `debrief open` or the
166
+ next start stops the run it left behind.
167
+ - A stopped run loses little: labels and bundles are kept, so the next run goes on from there.
168
+
169
+ How they compare, measured on the prototype's data with no human-labeled set behind it:
170
+
171
+ - On 66 turns where the two disagreed, a blind reader sided with Jev 32 times and Haiku 17 on
172
+ the turn-level questions. Three definitions were then tightened.
173
+ - After that, on 155 ordinary turns, Haiku and Jev agree on 93% for "agent named a problem and
174
+ did not file it" (kappa 0.77) and 92% for "the agent could have found this itself" (kappa
175
+ 0.66), where Haiku says yes about 1.7 times as often as Jev, mostly at low confidence.
176
+
177
+ ## Limits in this version
178
+
179
+ - A local session is linked to a pull request only when its log shows one: the URL that
180
+ `gh pr create` printed, or a branch it pushed that is the head of a PR. On the author's
181
+ machine that linked 33 of the 53 sessions that pushed. Of the 20 left out, 12 pushed
182
+ straight to main or another trunk branch.
183
+ - A session that pushes straight to main gets no CI or review data, even when CI runs on
184
+ those commits. If you work alone and never open pull requests, the report will show no
185
+ CI for you. The same goes for a PR opened by hand from a branch pushed outside the session.
186
+ - A CI failure counts for a session when its commit was made while the session ran (give or
187
+ take ten minutes). Review comments count for every session linked to the PR.
188
+ - Sessions fetched from Entire still need `debrief github --repo owner/name`; `sync` does not
189
+ fetch their GitHub data.
190
+ - A session's project is the folder it ran in, or the project of the repo it opened a PR in.
191
+ A session run in a git worktree joins its repo's project when ingest saw the worktree
192
+ while it still existed, or when the log names the repo, as Codex logs do. A Claude Code
193
+ session in a worktree that was deleted before the first ingest, and that opened no PR,
194
+ shows up as a project of its own, named after the worktree folder.
195
+ - A picked project that has not been synced yet shows in the report with no labels.
196
+ - "How it works" describes the whole run; the project picker does not scope its numbers.
197
+ - Labels vary between runs: on a set of hard cases Haiku changed its answer on about 15% of
198
+ rows between two identical runs.
199
+ - Pi logs are parsed but only tested against a made-up log.
200
+
201
+ ## Develop
202
+
203
+ uv sync
204
+ uv run pytest
205
+ uv run ruff check .
@@ -0,0 +1,186 @@
1
+ # debrief
2
+
3
+ Review your coding-agent sessions: where you had to correct the agent, what it missed, and what
4
+ to change so it happens less.
5
+
6
+ debrief reads the session logs Claude Code and Codex already keep on your machine, labels each
7
+ of your turns, groups the labels into findings with evidence, and builds a local report site.
8
+
9
+ ## Install
10
+
11
+ With Homebrew on a Mac:
12
+
13
+ brew install mvwi/tap/debrief
14
+
15
+ With uv or pipx, on Python 3.13 or newer:
16
+
17
+ uv tool install debrief-cli
18
+ pipx install debrief-cli
19
+
20
+ The package on PyPI is `debrief-cli`; the command it installs is `debrief`. The PyPI package
21
+ named `debrief` is a different project, so `uvx debrief` and `pip install debrief` fetch the
22
+ wrong tool. To run debrief once without installing it:
23
+
24
+ uvx --from debrief-cli debrief open
25
+
26
+ From source:
27
+
28
+ git clone https://github.com/mvwi/debrief && cd debrief
29
+ uv tool install .
30
+
31
+ The default labeler runs through `claude -p` on your Claude subscription, so it needs a
32
+ logged-in `claude` CLI. Without one, pick OpenRouter and save a key on the Settings page of
33
+ `debrief open`. `gh` is optional: with it, `debrief sync` adds pull-request data.
34
+
35
+ ## Use
36
+
37
+ debrief sync --dry-run # ingest logs, then say how many model calls labeling would take
38
+ debrief sync # ingest, label, find patterns, build the report
39
+ debrief open # serve the report at http://127.0.0.1:8765 and open it
40
+
41
+ Useful flags for `sync`:
42
+
43
+ --project DIR add this project to the ones sync analyses
44
+ --since YYYY-MM-DD only logs and evidence from this date on
45
+ --import DIR also load a folder of JSONL logs (Claude Code, Codex or Pi format)
46
+ --include-headless also load scripted runs (see below)
47
+ --llm openrouter label and synthesize through OpenRouter, whatever config.toml says
48
+
49
+ A re-run only reads logs that changed and only labels turns that are new.
50
+
51
+ You pick which projects get analysed. A project is the folder a session ran in. The first
52
+ `debrief sync` reads your logs, lists the projects it found with their size, and stops:
53
+
54
+ debrief sync --project ~/Dev/myrepo # pick it (kept in config.toml), then analyse
55
+
56
+ Only picked projects are labeled, analysed and shown. Each gets its own findings and ideas,
57
+ and an idea names the project it lands in (`myrepo: CLAUDE.md`). The picker in the report's
58
+ side bar scopes every page to one project. Findings about how you prompt come from the picked
59
+ projects together. To drop a project:
60
+
61
+ debrief config --drop ~/Dev/myrepo # its findings stay in the database, hidden
62
+
63
+ Unticking it on the Projects page does the same.
64
+
65
+ `debrief <stage> --help` runs one stage on its own: `ingest`, `label`, `synthesize`,
66
+ `recommend`, `verify`, `export`, `prune`.
67
+
68
+ ## What gets loaded
69
+
70
+ - Claude Code logs in `~/.claude/projects` and Codex logs in `~/.codex/sessions`.
71
+ - Scripted runs are skipped by default: `claude -p`, `codex exec`, and sessions started through
72
+ an SDK or a wrapper app that have fewer than two turns from a person. On the author's machine
73
+ that was 1,038 of 1,274 logs.
74
+ - Sub-agent logs are skipped, so tool calls made inside a sub-agent are not counted.
75
+ - A resumed or forked session copies its history into the new log. Each turn is loaded once.
76
+
77
+ ## Where your data goes
78
+
79
+ - Everything debrief writes is under `~/.local/share/debrief` (set `DEBRIEF_HOME` to move it).
80
+ - Labeling and synthesis send transcript text to a model: by default Claude, through your own
81
+ `claude` CLI. With `--llm openrouter` it goes to OpenRouter and needs `OPENROUTER_API_KEY`.
82
+ - `debrief sync` asks GitHub about the pull requests your sessions produced, through your own
83
+ logged-in `gh` CLI and read-only. It sends repo names, PR numbers, branch names and commit
84
+ SHAs, and nothing from your transcripts. `--no-github`, or `[github] enabled = false` in
85
+ config.toml, turns it off; without `gh` it is skipped.
86
+ - The report holds your transcripts. `debrief open` serves it on 127.0.0.1 only. Token-shaped
87
+ strings (GitHub, Anthropic, OpenAI, AWS, Slack, Stripe, private keys and others) are replaced
88
+ with `[redacted]` in the report, but the redaction is pattern-based: read before you share.
89
+
90
+ ## Which labeler
91
+
92
+ | | Claude Haiku (default) | Jev (`--llm openrouter`) |
93
+ |---|---|---|
94
+ | Needs | a Claude subscription | an OpenRouter key |
95
+ | Sends transcripts to | Anthropic, via your CLI | OpenRouter |
96
+ | Confidence | the model's own estimate | token probabilities |
97
+ | 2,774 items (236 sessions) | 33 min, no extra charge | about 3 min, about $0.37 |
98
+
99
+ The Jev time and cost are scaled up from a 74-item run (4 s, $0.0098).
100
+
101
+ To pick the model for each stage, write `~/.local/share/debrief/config.toml`:
102
+
103
+ [label]
104
+ llm = "openrouter" # Jev: faster and closer to a careful reader, needs a key
105
+ [synthesize]
106
+ model = "claude-sonnet-5" # optional; each llm has a default
107
+
108
+ Stages are `label`, `synthesize`, `recommend` and `verify`. `debrief config` prints what each
109
+ will use. A flag beats an environment variable, which beats the file.
110
+
111
+ ### Settings page
112
+
113
+ `debrief open` has a Settings page that does the same without editing files. It picks the
114
+ provider and model for each stage, turns the GitHub lookups on or off, and saves an OpenRouter
115
+ key.
116
+
117
+ Saving needs the link `debrief open` prints, which carries a token for that run: someone else
118
+ on the same machine can reach the port but cannot change your settings. They can still read the
119
+ report, as they can read the files.
120
+
121
+ - Saving rewrites `config.toml`; comments you wrote in it are lost.
122
+ - The key goes in `~/.local/share/debrief/.env`, readable only by you. The page shows its last
123
+ four characters and never the key. `OPENROUTER_API_KEY` set in your shell wins over the saved one.
124
+ - The server takes these writes only from a page it served itself, on `127.0.0.1`.
125
+
126
+ ### Run from the page
127
+
128
+ `debrief open` can also run the analysis, so you need not go back to the terminal. With no
129
+ report yet it reads your local logs first (no model calls) and serves what it found.
130
+
131
+ The Projects page is where you do it: tick the projects to analyse (each tick is saved to
132
+ `config.toml` at once), ask for an estimate, then press "Check my data now". It shows the stage
133
+ and the count while the run goes, and has a Cancel button. When the run ends every page shows
134
+ the new report without a refresh. Underneath it uses:
135
+
136
+ GET /api/run state (idle, running, done, failed, cancelled), stage, done/total,
137
+ start and end times, exit code, last 30 lines of output
138
+ POST /api/run start `debrief sync`; 409 if a run or an estimate is going
139
+ DELETE /api/run stop the run and the `claude -p` calls it started
140
+ POST /api/estimate run `debrief sync --dry-run`, rebuild the pages, return the counts
141
+
142
+ - The writes need the same token as the Settings page. Nothing in a request reaches the command
143
+ line: what to analyse comes from `config.toml`.
144
+ - One run at a time. Its output is in `~/.local/share/debrief/run.log`, replaced on each run,
145
+ with the OpenRouter key blanked.
146
+ - Ctrl-C stops a run too. If the server is killed outright, the next `debrief open` or the
147
+ next start stops the run it left behind.
148
+ - A stopped run loses little: labels and bundles are kept, so the next run goes on from there.
149
+
150
+ How they compare, measured on the prototype's data with no human-labeled set behind it:
151
+
152
+ - On 66 turns where the two disagreed, a blind reader sided with Jev 32 times and Haiku 17 on
153
+ the turn-level questions. Three definitions were then tightened.
154
+ - After that, on 155 ordinary turns, Haiku and Jev agree on 93% for "agent named a problem and
155
+ did not file it" (kappa 0.77) and 92% for "the agent could have found this itself" (kappa
156
+ 0.66), where Haiku says yes about 1.7 times as often as Jev, mostly at low confidence.
157
+
158
+ ## Limits in this version
159
+
160
+ - A local session is linked to a pull request only when its log shows one: the URL that
161
+ `gh pr create` printed, or a branch it pushed that is the head of a PR. On the author's
162
+ machine that linked 33 of the 53 sessions that pushed. Of the 20 left out, 12 pushed
163
+ straight to main or another trunk branch.
164
+ - A session that pushes straight to main gets no CI or review data, even when CI runs on
165
+ those commits. If you work alone and never open pull requests, the report will show no
166
+ CI for you. The same goes for a PR opened by hand from a branch pushed outside the session.
167
+ - A CI failure counts for a session when its commit was made while the session ran (give or
168
+ take ten minutes). Review comments count for every session linked to the PR.
169
+ - Sessions fetched from Entire still need `debrief github --repo owner/name`; `sync` does not
170
+ fetch their GitHub data.
171
+ - A session's project is the folder it ran in, or the project of the repo it opened a PR in.
172
+ A session run in a git worktree joins its repo's project when ingest saw the worktree
173
+ while it still existed, or when the log names the repo, as Codex logs do. A Claude Code
174
+ session in a worktree that was deleted before the first ingest, and that opened no PR,
175
+ shows up as a project of its own, named after the worktree folder.
176
+ - A picked project that has not been synced yet shows in the report with no labels.
177
+ - "How it works" describes the whole run; the project picker does not scope its numbers.
178
+ - Labels vary between runs: on a set of hard cases Haiku changed its answer on about 15% of
179
+ rows between two identical runs.
180
+ - Pi logs are parsed but only tested against a made-up log.
181
+
182
+ ## Develop
183
+
184
+ uv sync
185
+ uv run pytest
186
+ uv run ruff check .
File without changes
@@ -0,0 +1,83 @@
1
+ """Build the debrief site as a Claude artifact in ARTIFACT_OUT.
2
+
3
+ The host wraps the page in its own html/head/body, so page.html holds only the title, the
4
+ Google Fonts links, the inlined CSS, the body markup and the inlined scripts. The exported
5
+ data/ is copied next to it. Run debrief.export_site first.
6
+
7
+ uv run python -m debrief.build_artifact
8
+ """
9
+
10
+ import argparse
11
+ import re
12
+ import shutil
13
+ import sys
14
+ from pathlib import Path
15
+
16
+ from debrief.paths import ARTIFACT_OUT as OUT
17
+ from debrief.paths import SITE_OUT
18
+ from debrief.paths import SITE_SRC as SITE
19
+
20
+ MAX_FILES = 255
21
+ MAX_FILE_BYTES = 16_000_000 # decimal, to stay on the safe side of the host limit
22
+ MAX_TOTAL_BYTES = 64_000_000
23
+
24
+
25
+ def one(pattern: str, text: str, what: str) -> str:
26
+ m = re.search(pattern, text, re.DOTALL | re.IGNORECASE)
27
+ if not m:
28
+ sys.exit(f"build_artifact: no {what} in site/index.html")
29
+ return m.group(1)
30
+
31
+
32
+ def inline_script(path: Path) -> str:
33
+ # "</script" inside JS would end the tag early; "<\/script" means the same thing in a JS string.
34
+ js = re.sub(r"</(script)", r"<\\/\1", path.read_text(), flags=re.IGNORECASE)
35
+ return f"<script>\n{js}\n</script>"
36
+
37
+
38
+ def build_page() -> str:
39
+ html = (SITE / "index.html").read_text()
40
+ head = one(r"<head>(.*?)</head>", html, "<head>")
41
+ body = one(r"<body[^>]*>(.*?)</body>", html, "<body>")
42
+ title = one(r"(<title>.*?</title>)", head, "<title>")
43
+ fonts = [tag for tag in re.findall(r"<link\b[^>]*>", head, re.IGNORECASE) if "fonts.g" in tag]
44
+ scripts = re.findall(r'<script src="([^"]+)"></script>', body)
45
+ if scripts != ["method.js", "app.js"]:
46
+ sys.exit(f"build_artifact: expected method.js then app.js, found {scripts}")
47
+ markup = re.sub(r"\s*<script\b[^>]*></script>", "", body).strip()
48
+ css = (SITE / "style.css").read_text()
49
+ parts = [title, *fonts, f"<style>\n{css}\n</style>", markup, *(inline_script(SITE / s) for s in scripts)]
50
+ return "\n".join(parts) + "\n"
51
+
52
+
53
+ def main(argv: list[str] | None = None) -> None:
54
+ argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter).parse_args(argv)
55
+ if not (SITE_OUT / "data" / "index.json").exists():
56
+ sys.exit(f"build_artifact: {SITE_OUT / 'data' / 'index.json'} missing; run debrief.export_site first")
57
+ if OUT.exists():
58
+ shutil.rmtree(OUT)
59
+ OUT.mkdir(parents=True)
60
+ (OUT / "page.html").write_text(build_page())
61
+ shutil.copytree(SITE_OUT / "data", OUT / "data")
62
+
63
+ files = sorted(p for p in OUT.rglob("*") if p.is_file())
64
+ sizes = {p: p.stat().st_size for p in files}
65
+ total = sum(sizes.values())
66
+ largest = max(sizes, key=sizes.get)
67
+ print(f"{len(files)} files, {total:,} bytes ({total / 1e6:.1f} MB)")
68
+ print(f"largest: {largest.relative_to(OUT)} at {sizes[largest]:,} bytes ({sizes[largest] / 1e6:.1f} MB)")
69
+
70
+ errors = []
71
+ if len(files) > MAX_FILES:
72
+ errors.append(f"{len(files)} files exceeds the {MAX_FILES}-file limit")
73
+ errors += [f"{p.relative_to(OUT)} is {n:,} bytes, over the {MAX_FILE_BYTES:,}-byte file limit"
74
+ for p, n in sizes.items() if n > MAX_FILE_BYTES]
75
+ if total > MAX_TOTAL_BYTES:
76
+ errors.append(f"{total:,} bytes exceeds the {MAX_TOTAL_BYTES:,}-byte total limit")
77
+ if errors:
78
+ sys.exit("build_artifact: over limits:\n " + "\n ".join(errors))
79
+ print(f"wrote {OUT}")
80
+
81
+
82
+ if __name__ == "__main__":
83
+ main()