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.
- repeat_o_scope-0.1.0/LICENSE +21 -0
- repeat_o_scope-0.1.0/PKG-INFO +255 -0
- repeat_o_scope-0.1.0/README.md +229 -0
- repeat_o_scope-0.1.0/pyproject.toml +49 -0
- repeat_o_scope-0.1.0/pyproject.toml.orig +42 -0
- repeat_o_scope-0.1.0/src/repeat_o_scope/__init__.py +0 -0
- repeat_o_scope-0.1.0/src/repeat_o_scope/audit.py +136 -0
- repeat_o_scope-0.1.0/src/repeat_o_scope/cli.py +248 -0
- repeat_o_scope-0.1.0/src/repeat_o_scope/cluster.py +76 -0
- repeat_o_scope-0.1.0/src/repeat_o_scope/declined.py +70 -0
- repeat_o_scope-0.1.0/src/repeat_o_scope/doctor.py +211 -0
- repeat_o_scope-0.1.0/src/repeat_o_scope/findings.py +71 -0
- repeat_o_scope-0.1.0/src/repeat_o_scope/install.py +103 -0
- repeat_o_scope-0.1.0/src/repeat_o_scope/judge.py +67 -0
- repeat_o_scope-0.1.0/src/repeat_o_scope/judges.py +218 -0
- repeat_o_scope-0.1.0/src/repeat_o_scope/redaction.py +16 -0
- repeat_o_scope-0.1.0/src/repeat_o_scope/render.py +259 -0
- repeat_o_scope-0.1.0/src/repeat_o_scope/skill/SKILL.md +84 -0
- repeat_o_scope-0.1.0/src/repeat_o_scope/transcripts.py +190 -0
- repeat_o_scope-0.1.0/src/repeat_o_scope/waste.py +262 -0
- repeat_o_scope-0.1.0/src/repeat_o_scope/worklog.py +233 -0
|
@@ -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
|