repeat-o-scope 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.
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Kimmo Parviainen-Jalanko
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,255 @@
1
+ Metadata-Version: 2.4
2
+ Name: repeat-o-scope
3
+ Version: 0.1.0
4
+ Summary: Audits your Claude Code transcripts for wasted usage and repeats, and turns them into fixes you approve.
5
+ Keywords: claude-code,automation,productivity,transcripts
6
+ Author: Kimmo Parviainen-Jalanko
7
+ License-Expression: MIT
8
+ License-File: LICENSE
9
+ Classifier: Development Status :: 3 - Alpha
10
+ Classifier: Environment :: Console
11
+ Classifier: Intended Audience :: Developers
12
+ Classifier: Operating System :: OS Independent
13
+ Classifier: Programming Language :: Python :: 3
14
+ Classifier: Topic :: Software Development
15
+ Requires-Dist: fire>=0.7
16
+ Requires-Dist: httpx2>=2.16
17
+ Requires-Dist: model2vec>=0.4
18
+ Requires-Dist: platformdirs>=4
19
+ Requires-Dist: rich>=13
20
+ Requires-Dist: scikit-learn>=1.6
21
+ Requires-Dist: typesafe-sdk>=0.7.5
22
+ Requires-Python: >=3.12
23
+ Project-URL: Homepage, https://github.com/kimvais/repeat-o-scope
24
+ Project-URL: Issues, https://github.com/kimvais/repeat-o-scope/issues
25
+ Description-Content-Type: text/markdown
26
+
27
+ # repeat-o-scope
28
+
29
+ Logs your Claude Code work, finds the prompts you keep repeating, and helps automate them away.
30
+
31
+ Most Claude Code tokens go on wasted turns rather than on the work itself: a wrong guess, a retry, a re-read.
32
+ [Why, and the set-up that cuts them](https://github.com/kimvais/repeat-o-scope/blob/main/docs/why.md). repeat-o-scope finds those turns in your own transcripts.
33
+
34
+ ## Install
35
+
36
+ ```
37
+ uv tool install repeat-o-scope
38
+ repeat-o-scope install
39
+ ```
40
+
41
+ `install` copies the `/repeat-o-scope` skill to `~/.claude/skills/` and registers the worklog Stop hook in
42
+ `~/.claude/settings.json`. It replaces an old `worklog.ps1` Stop hook, backs `settings.json` up once to
43
+ `settings.json.repeat-o-scope.bak`, and refuses to touch a settings file it can't parse. Running it again
44
+ changes nothing. `repeat-o-scope uninstall` removes both.
45
+
46
+ The hook runs `repeat-o-scope-worklog` by name, so uv's tool directory must be on the `PATH` Claude Code sees.
47
+ If `repeat-o-scope` isn't found after installing, run `uv tool update-shell` and open a new terminal.
48
+
49
+ ## The skill
50
+
51
+ In Claude Code, run `/repeat-o-scope`, or ask where your usage goes or what you keep repeating. In one pass, the
52
+ skill:
53
+ 1. Runs `repeat-o-scope audit --format json --jev`: what was wasted, on what, what it cost, and your settings.
54
+ 2. Judges the findings with a Haiku subagent if no judge key is set (see [Judges](#judges)).
55
+ 3. Merges findings with one root cause into themes, and picks at most four by share of usage.
56
+ 4. Drafts a concrete fix for each: a CLAUDE.md line, a setting, a hook, a shell function, a script fix.
57
+ 5. Asks you once, applies only what you pick, and declines the rest so they don't come back.
58
+
59
+ ## `audit`
60
+
61
+ ```
62
+ repeat-o-scope audit # measure + the findings behind the waste + repeats + doctor, as JSON
63
+ ```
64
+
65
+ `audit` runs `measure`, groups the wasted calls of each kind by what they were about (the tool and its error,
66
+ the re-read file, the closing line a bare go-ahead answered), and gives every group its turns, tokens and
67
+ share of your usage, costliest first. Two alike wasted calls make a group; the rest of a kind is one group,
68
+ so the shares add up to the measured waste. Expired caches and long contexts have nothing to group: the
69
+ `doctor` checks, which `audit` includes, are what point at their fixes. `prompts` and `commands` findings come
70
+ along with counts only.
71
+
72
+ JSON is the default (`--format markdown` for people). `--jev` judges the groups, `decline` and `--all` work as
73
+ for the reports, and every run writes the measurement to `<user data dir>/baseline/<date>.json` for a later
74
+ before/after.
75
+
76
+ ## Reports
77
+
78
+ ```
79
+ repeat-o-scope prompts # prompts you keep typing
80
+ repeat-o-scope commands # `!` shell commands you keep running by hand
81
+ repeat-o-scope asks # Claude turn endings you answered with a bare "ship" / "go" / "yes"
82
+ repeat-o-scope fails # tool calls that keep failing, with denials listed apart
83
+ repeat-o-scope measure # turns wasted per kind, and their share of your usage
84
+ ```
85
+
86
+ Each report reads the transcripts under `~/.claude/projects` from the last 30 days (`--days`), and prints
87
+ markdown on stdout (`--top` groups, default 20). Progress logging goes to stderr.
88
+
89
+ - `--format json` prints every finding as JSON for the skill: an `id`, a `kind`, a `total`, the `variants`,
90
+ up to 3 redacted `examples`, and Jev's `label`.
91
+ - `repeat-o-scope decline <id>` leaves a finding from the last run out of later reports, matched on its
92
+ variants. `--all` shows declined findings again. That state lives in the local user data directory,
93
+ never in a synced folder.
94
+
95
+ The window is deliberately short. Claude Code deletes transcripts after 30 days anyway, and whatever you
96
+ automated after an earlier run should drop out instead of dominating.
97
+
98
+ How it works:
99
+ - Only what you typed counts. Harness plumbing, meta messages, subagents and scripted runs
100
+ (`entrypoint: sdk-cli`) are skipped. `fails` is the exception and includes subagents.
101
+ - Credentials are redacted before anything is grouped or printed.
102
+ - Texts are normalised: lowercase, with paths, URLs, `!`/`#` references, hashes and numbers replaced by
103
+ placeholders.
104
+ - They are embedded locally with `model2vec` (`minishlab/potion-base-8M`, about 30 MB, downloaded once) and
105
+ grouped with scikit-learn's HDBSCAN. Nothing leaves the machine unless you pass `--jev`.
106
+ - A group needs at least 4 occurrences.
107
+
108
+ ### `measure`
109
+
110
+ `measure` counts turns, where a turn is one API call, and charges each wasted turn to one kind:
111
+
112
+ - **Refused edits:** an Edit or Write of a file Claude had not read yet.
113
+ - **Re-reads:** reading the same file range again in one context. A read after an edit of that file, or after
114
+ compaction, doesn't count.
115
+ - **Failed calls:** any other tool error.
116
+ - **Denied tools:** calls refused by you, a hook or the permission classifier, the same ones `fails` lists
117
+ under Denied.
118
+ - **Bare go-aheads:** the turn that answers a bare "yes" / "ship" / "go", the same replies `asks` counts.
119
+ - **Expired cache:** the first call after a gap longer than the session's cache lifetime (5 minutes, or 1 hour
120
+ if most of its cache writes were 1-hour ones) writes the previous context to the cache again. It counts what
121
+ that rewrite cost above a warm cache read, on calls not charged to another kind.
122
+ - **Past half context:** the context a call carried above half its window, on calls not charged to another kind.
123
+
124
+ It prints a table for the terminal. `--format markdown` or `--format json` gives agents plain text. The
125
+ headline is the wasted share of your usage. Raw tokens are a secondary column, and `--price 3.0` adds €,
126
+ priced per million input tokens. Caveats:
127
+ - Your usage limit isn't in the transcripts, so the share is the share of what you used, not of the limit.
128
+ - Tokens are weighted by the call's model's API price ratios to an input token: output 5, 5-minute cache
129
+ writes 1.25, 1-hour cache writes 2, and cache reads 0.05 on Opus 5.5 and Sonnet 5.5, 0.025 on Fable and
130
+ Mythos 5.1 and 5.2, and 0.1 on older models.
131
+ - A session resumed under a new session id starts a new context, so its first rebuild isn't counted.
132
+ - Cowork keeps its sessions apart. On Windows, point `--root` at them:
133
+ `repeat-o-scope measure --root="$env:LOCALAPPDATA\Claude-Data\claude_<id>\local-agent-mode-sessions"`.
134
+ - Transcripts don't say whether a session ran with a 200k or 1M context window. Each session gets the
135
+ smallest one that fits its largest call.
136
+
137
+ ## Doctor
138
+
139
+ ```
140
+ repeat-o-scope doctor # your settings and CLAUDE.md against the checklist in docs/why.md
141
+ ```
142
+
143
+ `doctor` reads config, not transcripts, and says what to change, failing checks first:
144
+
145
+ - **Effort:** `effortLevel`, top-level or per model under `modelSettings`, is `low` or `medium`.
146
+ - **Skill overrides:** `skillOverrides` turns at least one skill `off`.
147
+ - **Enabled skills:** at most 30, counted from `~/.claude/skills`, `.claude/skills` and enabled plugins.
148
+ - **Status line:** `statusLine` runs a command.
149
+ - **Scope rule** and **read-once rule:** a `CLAUDE.md` (`~/.claude/`, the current directory or its `.claude/`)
150
+ has them, matched by their key phrases.
151
+ - **Idle compact:** `CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS` is at most 100000, so idle compact runs on ordinary
152
+ sessions during long breaks with the terminal open.
153
+ - **Auto-compact override:** no `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` below 50, unless the model is a 1M one
154
+ (`opus[1m]`). On 200k, 25 compacts at 45,000 tokens, below what a summary leaves.
155
+
156
+ The two compaction checks follow
157
+ [claude-code-usage-analysis](https://github.com/inevolin/claude-code-usage-analysis). They read `env` in
158
+ the settings files, then your environment.
159
+
160
+ It prints a table for the terminal; `--format markdown` or `--format json` gives agents plain text. It never
161
+ writes anything and never prints settings values it doesn't check. Caveats:
162
+ - It reads the user, project and local `settings.json`, local first. Managed settings are not read.
163
+ - Built-in and claude.ai skills aren't on disk, so the skill count is a lower bound.
164
+ - It checks that a status line exists, not that it shows context % and usage %.
165
+
166
+ ## Judges
167
+
168
+ Clustering can't tell a request for a go-ahead from a plain status line, or a real failure from a tool that
169
+ only wrote to stderr. `--jev` hands one example per group to a judge:
170
+
171
+ - `asks --jev` groups each closing line by kind: permission, choice, clarifying, review or report.
172
+ - `fails --jev` and `audit --jev` leave out failed-call groups that are only stderr noise.
173
+
174
+ It uses the first judge whose key is set and that answers a test question without an error:
175
+
176
+ | Judge | Keys |
177
+ |---|---|
178
+ | [Jev](https://docs.typesafe.ai) (TypeSafe System One) | `TYPESAFE_API_KEY` or `TYPESAFE_AI_API_KEY` |
179
+ | Gemini Decision 1 (Gemini Decisions API) | `GEMINI_API_KEY` |
180
+ | Clef (Cloudflare Workers AI) | `CLOUDFLARE_ACCOUNT_ID` and `CLOUDFLARE_API_KEY` |
181
+
182
+ The examples are already redacted, but they leave the machine, and each call costs money. With no judge,
183
+ `asks --jev` and `fails --jev` stop with an error, and `audit --jev` reports `"judge": null`; the skill then
184
+ asks a Haiku subagent the same questions.
185
+
186
+ ```powershell
187
+ $env:TYPESAFE_API_KEY = op item get TypeSafe --fields "api key" --reveal
188
+ repeat-o-scope asks --jev
189
+ ```
190
+
191
+ ## Worklog hook
192
+
193
+ A Claude Code `Stop` hook that appends one JSON line per stretch of work (a session's activity until a
194
+ 15-minute gap) to `<user data dir>/worklog/YYYY-MM-DD.jsonl` (on Windows
195
+ `%LOCALAPPDATA%\repeat-o-scope\worklog`). A stretch is re-appended with growing totals as it goes on, so
196
+ **readers keep the last line per `@id`**.
197
+
198
+ Each line records `cwd`, `repo`, `branch`, `started`, `last_stop`, `turns`, `tool_uses`, the files Claude
199
+ edited, your last 10 prompts (cut to 200 characters, credentials redacted), the transcript path, and the
200
+ rate limits (below).
201
+
202
+ `repeat-o-scope install` registers it. Set `REPEAT_O_SCOPE_LOG_DIR` to log somewhere else. The default
203
+ used to be `<Documents>/worklog`; it moved because Windows ransomware protection (Controlled Folder Access)
204
+ blocks python and pwsh from writing there. Per-session state lives in `~/.claude/hooks/worklog-state`.
205
+
206
+ ### Rate limits and extra usage
207
+
208
+ Transcripts don't record whether a turn went to extra usage. Claude Code passes the 5-hour and 7-day
209
+ limits only to the status line (`rate_limits`, claude.ai subscriptions only), so
210
+ [`statusline/statusline.ps1`](https://github.com/kimvais/repeat-o-scope/blob/main/statusline/statusline.ps1) writes them to
211
+ `~/.claude/hooks/worklog-state/<session_id>.rate-limits.json`, and the Stop hook copies them into the log:
212
+
213
+ - `rate_limits`: the status line's latest copy, as Claude Code gave it (`used_percentage`, `resets_at`).
214
+ - `rate_limit_peak`: the highest `used_percentage` per window during the stretch. A window at 100 means
215
+ the stretch went to extra usage, even if the window reset before the stretch ended.
216
+
217
+ Both are `null` without that status line. The copy is as fresh as the status line's last refresh, so the
218
+ last response of a stretch can show up only at the next stop.
219
+
220
+ To use the script as is, point `statusLine` in `~/.claude/settings.json` at it:
221
+ `pwsh -NoProfile -File <repo>/statusline/statusline.ps1`. Besides the limits, it shows the branch's issue and
222
+ MR (via `glab`), context use and the repo or worktree name.
223
+
224
+ ### Replacing `worklog.ps1`
225
+
226
+ This is a port of the PowerShell hook `worklog.ps1`. It reads the same state directory, so session
227
+ indexes (`s0494.1`, ...) carry on where the PowerShell hook stopped. `repeat-o-scope install` swaps the old
228
+ hook out, because running both would log every stretch twice.
229
+
230
+ Two differences from `worklog.ps1`:
231
+ - The JSON-LD vocabulary is `urn:repeat-o-scope:worklog#` instead of the old hook's own.
232
+ - Timestamps have 6 fractional digits instead of 7.
233
+
234
+ ## Development
235
+
236
+ ```
237
+ uv run pytest
238
+ ```
239
+
240
+ ## Releasing
241
+
242
+ Pushing a `v*` tag runs `.github/workflows/release.yml`. It checks that the tag matches the version in
243
+ `pyproject.toml`, runs the tests, builds, installs the wheel with `uv tool install` and runs
244
+ `repeat-o-scope install` against a scratch directory, and only then publishes to PyPI through trusted publishing
245
+ (no API token).
246
+
247
+ ```
248
+ uv version --bump minor # or patch; commit and merge that first
249
+ git tag "v$(uv version --short)"
250
+ git push origin "v$(uv version --short)"
251
+ ```
252
+
253
+ Once, before the first release: add a pending trusted publisher at
254
+ https://pypi.org/manage/account/publishing/ with project `repeat-o-scope`, owner `kimvais`, repository
255
+ `repeat-o-scope`, workflow `release.yml` and environment `pypi`.
@@ -0,0 +1,229 @@
1
+ # repeat-o-scope
2
+
3
+ Logs your Claude Code work, finds the prompts you keep repeating, and helps automate them away.
4
+
5
+ Most Claude Code tokens go on wasted turns rather than on the work itself: a wrong guess, a retry, a re-read.
6
+ [Why, and the set-up that cuts them](https://github.com/kimvais/repeat-o-scope/blob/main/docs/why.md). repeat-o-scope finds those turns in your own transcripts.
7
+
8
+ ## Install
9
+
10
+ ```
11
+ uv tool install repeat-o-scope
12
+ repeat-o-scope install
13
+ ```
14
+
15
+ `install` copies the `/repeat-o-scope` skill to `~/.claude/skills/` and registers the worklog Stop hook in
16
+ `~/.claude/settings.json`. It replaces an old `worklog.ps1` Stop hook, backs `settings.json` up once to
17
+ `settings.json.repeat-o-scope.bak`, and refuses to touch a settings file it can't parse. Running it again
18
+ changes nothing. `repeat-o-scope uninstall` removes both.
19
+
20
+ The hook runs `repeat-o-scope-worklog` by name, so uv's tool directory must be on the `PATH` Claude Code sees.
21
+ If `repeat-o-scope` isn't found after installing, run `uv tool update-shell` and open a new terminal.
22
+
23
+ ## The skill
24
+
25
+ In Claude Code, run `/repeat-o-scope`, or ask where your usage goes or what you keep repeating. In one pass, the
26
+ skill:
27
+ 1. Runs `repeat-o-scope audit --format json --jev`: what was wasted, on what, what it cost, and your settings.
28
+ 2. Judges the findings with a Haiku subagent if no judge key is set (see [Judges](#judges)).
29
+ 3. Merges findings with one root cause into themes, and picks at most four by share of usage.
30
+ 4. Drafts a concrete fix for each: a CLAUDE.md line, a setting, a hook, a shell function, a script fix.
31
+ 5. Asks you once, applies only what you pick, and declines the rest so they don't come back.
32
+
33
+ ## `audit`
34
+
35
+ ```
36
+ repeat-o-scope audit # measure + the findings behind the waste + repeats + doctor, as JSON
37
+ ```
38
+
39
+ `audit` runs `measure`, groups the wasted calls of each kind by what they were about (the tool and its error,
40
+ the re-read file, the closing line a bare go-ahead answered), and gives every group its turns, tokens and
41
+ share of your usage, costliest first. Two alike wasted calls make a group; the rest of a kind is one group,
42
+ so the shares add up to the measured waste. Expired caches and long contexts have nothing to group: the
43
+ `doctor` checks, which `audit` includes, are what point at their fixes. `prompts` and `commands` findings come
44
+ along with counts only.
45
+
46
+ JSON is the default (`--format markdown` for people). `--jev` judges the groups, `decline` and `--all` work as
47
+ for the reports, and every run writes the measurement to `<user data dir>/baseline/<date>.json` for a later
48
+ before/after.
49
+
50
+ ## Reports
51
+
52
+ ```
53
+ repeat-o-scope prompts # prompts you keep typing
54
+ repeat-o-scope commands # `!` shell commands you keep running by hand
55
+ repeat-o-scope asks # Claude turn endings you answered with a bare "ship" / "go" / "yes"
56
+ repeat-o-scope fails # tool calls that keep failing, with denials listed apart
57
+ repeat-o-scope measure # turns wasted per kind, and their share of your usage
58
+ ```
59
+
60
+ Each report reads the transcripts under `~/.claude/projects` from the last 30 days (`--days`), and prints
61
+ markdown on stdout (`--top` groups, default 20). Progress logging goes to stderr.
62
+
63
+ - `--format json` prints every finding as JSON for the skill: an `id`, a `kind`, a `total`, the `variants`,
64
+ up to 3 redacted `examples`, and Jev's `label`.
65
+ - `repeat-o-scope decline <id>` leaves a finding from the last run out of later reports, matched on its
66
+ variants. `--all` shows declined findings again. That state lives in the local user data directory,
67
+ never in a synced folder.
68
+
69
+ The window is deliberately short. Claude Code deletes transcripts after 30 days anyway, and whatever you
70
+ automated after an earlier run should drop out instead of dominating.
71
+
72
+ How it works:
73
+ - Only what you typed counts. Harness plumbing, meta messages, subagents and scripted runs
74
+ (`entrypoint: sdk-cli`) are skipped. `fails` is the exception and includes subagents.
75
+ - Credentials are redacted before anything is grouped or printed.
76
+ - Texts are normalised: lowercase, with paths, URLs, `!`/`#` references, hashes and numbers replaced by
77
+ placeholders.
78
+ - They are embedded locally with `model2vec` (`minishlab/potion-base-8M`, about 30 MB, downloaded once) and
79
+ grouped with scikit-learn's HDBSCAN. Nothing leaves the machine unless you pass `--jev`.
80
+ - A group needs at least 4 occurrences.
81
+
82
+ ### `measure`
83
+
84
+ `measure` counts turns, where a turn is one API call, and charges each wasted turn to one kind:
85
+
86
+ - **Refused edits:** an Edit or Write of a file Claude had not read yet.
87
+ - **Re-reads:** reading the same file range again in one context. A read after an edit of that file, or after
88
+ compaction, doesn't count.
89
+ - **Failed calls:** any other tool error.
90
+ - **Denied tools:** calls refused by you, a hook or the permission classifier, the same ones `fails` lists
91
+ under Denied.
92
+ - **Bare go-aheads:** the turn that answers a bare "yes" / "ship" / "go", the same replies `asks` counts.
93
+ - **Expired cache:** the first call after a gap longer than the session's cache lifetime (5 minutes, or 1 hour
94
+ if most of its cache writes were 1-hour ones) writes the previous context to the cache again. It counts what
95
+ that rewrite cost above a warm cache read, on calls not charged to another kind.
96
+ - **Past half context:** the context a call carried above half its window, on calls not charged to another kind.
97
+
98
+ It prints a table for the terminal. `--format markdown` or `--format json` gives agents plain text. The
99
+ headline is the wasted share of your usage. Raw tokens are a secondary column, and `--price 3.0` adds €,
100
+ priced per million input tokens. Caveats:
101
+ - Your usage limit isn't in the transcripts, so the share is the share of what you used, not of the limit.
102
+ - Tokens are weighted by the call's model's API price ratios to an input token: output 5, 5-minute cache
103
+ writes 1.25, 1-hour cache writes 2, and cache reads 0.05 on Opus 5.5 and Sonnet 5.5, 0.025 on Fable and
104
+ Mythos 5.1 and 5.2, and 0.1 on older models.
105
+ - A session resumed under a new session id starts a new context, so its first rebuild isn't counted.
106
+ - Cowork keeps its sessions apart. On Windows, point `--root` at them:
107
+ `repeat-o-scope measure --root="$env:LOCALAPPDATA\Claude-Data\claude_<id>\local-agent-mode-sessions"`.
108
+ - Transcripts don't say whether a session ran with a 200k or 1M context window. Each session gets the
109
+ smallest one that fits its largest call.
110
+
111
+ ## Doctor
112
+
113
+ ```
114
+ repeat-o-scope doctor # your settings and CLAUDE.md against the checklist in docs/why.md
115
+ ```
116
+
117
+ `doctor` reads config, not transcripts, and says what to change, failing checks first:
118
+
119
+ - **Effort:** `effortLevel`, top-level or per model under `modelSettings`, is `low` or `medium`.
120
+ - **Skill overrides:** `skillOverrides` turns at least one skill `off`.
121
+ - **Enabled skills:** at most 30, counted from `~/.claude/skills`, `.claude/skills` and enabled plugins.
122
+ - **Status line:** `statusLine` runs a command.
123
+ - **Scope rule** and **read-once rule:** a `CLAUDE.md` (`~/.claude/`, the current directory or its `.claude/`)
124
+ has them, matched by their key phrases.
125
+ - **Idle compact:** `CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS` is at most 100000, so idle compact runs on ordinary
126
+ sessions during long breaks with the terminal open.
127
+ - **Auto-compact override:** no `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` below 50, unless the model is a 1M one
128
+ (`opus[1m]`). On 200k, 25 compacts at 45,000 tokens, below what a summary leaves.
129
+
130
+ The two compaction checks follow
131
+ [claude-code-usage-analysis](https://github.com/inevolin/claude-code-usage-analysis). They read `env` in
132
+ the settings files, then your environment.
133
+
134
+ It prints a table for the terminal; `--format markdown` or `--format json` gives agents plain text. It never
135
+ writes anything and never prints settings values it doesn't check. Caveats:
136
+ - It reads the user, project and local `settings.json`, local first. Managed settings are not read.
137
+ - Built-in and claude.ai skills aren't on disk, so the skill count is a lower bound.
138
+ - It checks that a status line exists, not that it shows context % and usage %.
139
+
140
+ ## Judges
141
+
142
+ Clustering can't tell a request for a go-ahead from a plain status line, or a real failure from a tool that
143
+ only wrote to stderr. `--jev` hands one example per group to a judge:
144
+
145
+ - `asks --jev` groups each closing line by kind: permission, choice, clarifying, review or report.
146
+ - `fails --jev` and `audit --jev` leave out failed-call groups that are only stderr noise.
147
+
148
+ It uses the first judge whose key is set and that answers a test question without an error:
149
+
150
+ | Judge | Keys |
151
+ |---|---|
152
+ | [Jev](https://docs.typesafe.ai) (TypeSafe System One) | `TYPESAFE_API_KEY` or `TYPESAFE_AI_API_KEY` |
153
+ | Gemini Decision 1 (Gemini Decisions API) | `GEMINI_API_KEY` |
154
+ | Clef (Cloudflare Workers AI) | `CLOUDFLARE_ACCOUNT_ID` and `CLOUDFLARE_API_KEY` |
155
+
156
+ The examples are already redacted, but they leave the machine, and each call costs money. With no judge,
157
+ `asks --jev` and `fails --jev` stop with an error, and `audit --jev` reports `"judge": null`; the skill then
158
+ asks a Haiku subagent the same questions.
159
+
160
+ ```powershell
161
+ $env:TYPESAFE_API_KEY = op item get TypeSafe --fields "api key" --reveal
162
+ repeat-o-scope asks --jev
163
+ ```
164
+
165
+ ## Worklog hook
166
+
167
+ A Claude Code `Stop` hook that appends one JSON line per stretch of work (a session's activity until a
168
+ 15-minute gap) to `<user data dir>/worklog/YYYY-MM-DD.jsonl` (on Windows
169
+ `%LOCALAPPDATA%\repeat-o-scope\worklog`). A stretch is re-appended with growing totals as it goes on, so
170
+ **readers keep the last line per `@id`**.
171
+
172
+ Each line records `cwd`, `repo`, `branch`, `started`, `last_stop`, `turns`, `tool_uses`, the files Claude
173
+ edited, your last 10 prompts (cut to 200 characters, credentials redacted), the transcript path, and the
174
+ rate limits (below).
175
+
176
+ `repeat-o-scope install` registers it. Set `REPEAT_O_SCOPE_LOG_DIR` to log somewhere else. The default
177
+ used to be `<Documents>/worklog`; it moved because Windows ransomware protection (Controlled Folder Access)
178
+ blocks python and pwsh from writing there. Per-session state lives in `~/.claude/hooks/worklog-state`.
179
+
180
+ ### Rate limits and extra usage
181
+
182
+ Transcripts don't record whether a turn went to extra usage. Claude Code passes the 5-hour and 7-day
183
+ limits only to the status line (`rate_limits`, claude.ai subscriptions only), so
184
+ [`statusline/statusline.ps1`](https://github.com/kimvais/repeat-o-scope/blob/main/statusline/statusline.ps1) writes them to
185
+ `~/.claude/hooks/worklog-state/<session_id>.rate-limits.json`, and the Stop hook copies them into the log:
186
+
187
+ - `rate_limits`: the status line's latest copy, as Claude Code gave it (`used_percentage`, `resets_at`).
188
+ - `rate_limit_peak`: the highest `used_percentage` per window during the stretch. A window at 100 means
189
+ the stretch went to extra usage, even if the window reset before the stretch ended.
190
+
191
+ Both are `null` without that status line. The copy is as fresh as the status line's last refresh, so the
192
+ last response of a stretch can show up only at the next stop.
193
+
194
+ To use the script as is, point `statusLine` in `~/.claude/settings.json` at it:
195
+ `pwsh -NoProfile -File <repo>/statusline/statusline.ps1`. Besides the limits, it shows the branch's issue and
196
+ MR (via `glab`), context use and the repo or worktree name.
197
+
198
+ ### Replacing `worklog.ps1`
199
+
200
+ This is a port of the PowerShell hook `worklog.ps1`. It reads the same state directory, so session
201
+ indexes (`s0494.1`, ...) carry on where the PowerShell hook stopped. `repeat-o-scope install` swaps the old
202
+ hook out, because running both would log every stretch twice.
203
+
204
+ Two differences from `worklog.ps1`:
205
+ - The JSON-LD vocabulary is `urn:repeat-o-scope:worklog#` instead of the old hook's own.
206
+ - Timestamps have 6 fractional digits instead of 7.
207
+
208
+ ## Development
209
+
210
+ ```
211
+ uv run pytest
212
+ ```
213
+
214
+ ## Releasing
215
+
216
+ Pushing a `v*` tag runs `.github/workflows/release.yml`. It checks that the tag matches the version in
217
+ `pyproject.toml`, runs the tests, builds, installs the wheel with `uv tool install` and runs
218
+ `repeat-o-scope install` against a scratch directory, and only then publishes to PyPI through trusted publishing
219
+ (no API token).
220
+
221
+ ```
222
+ uv version --bump minor # or patch; commit and merge that first
223
+ git tag "v$(uv version --short)"
224
+ git push origin "v$(uv version --short)"
225
+ ```
226
+
227
+ Once, before the first release: add a pending trusted publisher at
228
+ https://pypi.org/manage/account/publishing/ with project `repeat-o-scope`, owner `kimvais`, repository
229
+ `repeat-o-scope`, workflow `release.yml` and environment `pypi`.
@@ -0,0 +1,49 @@
1
+ [project]
2
+ name = "repeat-o-scope"
3
+ version = "0.1.0"
4
+ description = "Audits your Claude Code transcripts for wasted usage and repeats, and turns them into fixes you approve."
5
+ readme = "README.md"
6
+ license = "MIT"
7
+ license-files = ["LICENSE"]
8
+ keywords = [
9
+ "claude-code",
10
+ "automation",
11
+ "productivity",
12
+ "transcripts",
13
+ ]
14
+ classifiers = [
15
+ "Development Status :: 3 - Alpha",
16
+ "Environment :: Console",
17
+ "Intended Audience :: Developers",
18
+ "Operating System :: OS Independent",
19
+ "Programming Language :: Python :: 3",
20
+ "Topic :: Software Development",
21
+ ]
22
+ requires-python = ">=3.12"
23
+ dependencies = [
24
+ "fire>=0.7",
25
+ "httpx2>=2.16",
26
+ "model2vec>=0.4",
27
+ "platformdirs>=4",
28
+ "rich>=13",
29
+ "scikit-learn>=1.6",
30
+ "typesafe-sdk>=0.7.5",
31
+ ]
32
+
33
+ [[project.authors]]
34
+ name = "Kimmo Parviainen-Jalanko"
35
+
36
+ [project.urls]
37
+ Homepage = "https://github.com/kimvais/repeat-o-scope"
38
+ Issues = "https://github.com/kimvais/repeat-o-scope/issues"
39
+
40
+ [project.scripts]
41
+ repeat-o-scope = "repeat_o_scope.cli:main"
42
+ repeat-o-scope-worklog = "repeat_o_scope.worklog:main"
43
+
44
+ [dependency-groups]
45
+ dev = ["pytest>=8"]
46
+
47
+ [build-system]
48
+ requires = ["uv_build>=0.9,<0.14"]
49
+ build-backend = "uv_build"
@@ -0,0 +1,42 @@
1
+ [project]
2
+ name = "repeat-o-scope"
3
+ version = "0.1.0"
4
+ description = "Audits your Claude Code transcripts for wasted usage and repeats, and turns them into fixes you approve."
5
+ readme = "README.md"
6
+ license = "MIT"
7
+ license-files = ["LICENSE"]
8
+ authors = [{ name = "Kimmo Parviainen-Jalanko" }]
9
+ keywords = ["claude-code", "automation", "productivity", "transcripts"]
10
+ classifiers = [
11
+ "Development Status :: 3 - Alpha",
12
+ "Environment :: Console",
13
+ "Intended Audience :: Developers",
14
+ "Operating System :: OS Independent",
15
+ "Programming Language :: Python :: 3",
16
+ "Topic :: Software Development",
17
+ ]
18
+ requires-python = ">=3.12"
19
+ dependencies = [
20
+ "fire>=0.7",
21
+ "httpx2>=2.16",
22
+ "model2vec>=0.4",
23
+ "platformdirs>=4",
24
+ "rich>=13",
25
+ "scikit-learn>=1.6",
26
+ "typesafe-sdk>=0.7.5",
27
+ ]
28
+
29
+ [project.urls]
30
+ Homepage = "https://github.com/kimvais/repeat-o-scope"
31
+ Issues = "https://github.com/kimvais/repeat-o-scope/issues"
32
+
33
+ [project.scripts]
34
+ repeat-o-scope = "repeat_o_scope.cli:main"
35
+ repeat-o-scope-worklog = "repeat_o_scope.worklog:main"
36
+
37
+ [dependency-groups]
38
+ dev = ["pytest>=8"]
39
+
40
+ [build-system]
41
+ requires = ["uv_build>=0.9,<0.14"]
42
+ build-backend = "uv_build"
File without changes