Docs
Trace context waste to the rule that found it
RepoOps scores the active health findings for one repository and one local telemetry window. Start with the number, then use the rule, evidence, deduction, and suggested fix to decide what the number means.
For: the developer reviewing Claude Code usage in one repository, and the maintainer tuning the shared scoring weights
What it does, and why it helps
Context health reads the captured Claude Code aggregate for the selected repository over 7, 30, or 90 days. It runs every registered rule whose surface includes health. Each finding starts with its rule severity, title, body, evidence, and suggested fix. The score starts at 100 and subtracts the configured severity weight once for each finding, then clamps the result from 0 to 100.
The default deductions are 10 for Error, 5 for Warn, and 1 for Info. The tab lists each rule and its deduction, so the score is not a diagnosis by itself. It is a compact index into the findings. A green orb begins at 85, amber begins at 60, and red is below 60. Those colors report the arithmetic band, not whether the next session will go well.
The pain. Token totals can rise for several different reasons. A long task, repeated whole-file reads, low prompt-cache reuse, and an uncapped loop need different responses.
The point of view. Do not coach from the headline score alone. Read the rule and its evidence first, change the habit it names, then compare a later window measured on the same basis.
What gets easier. Triage. The tab puts the score, finding count, severity mix, source rule, measured evidence, fix hint, and exact deduction on one page.
When it helps. Use it after enough Claude Code sessions have been captured for a rule to meet its own evidence floor, or when the Context health line on Today sends you to the detail page.
Its limits. The score aggregates one repository across a selected window. It is not a live grade for one session, a team-wide hosted score, or proof that a suggested change will improve an outcome. Some rules stay silent until their sample floor is met.
Understand it in 30 seconds
Read the narration
- 0:00 A hundred-point score can look precise while hiding the habit behind it.
- 0:06 Treat the score as an index: inspect each deduction and its evidence before changing behavior.
- 0:13 RepoOps names the rule, its severity, the evidence and the fix.
- 0:17 The points come from this repository's local telemetry window.
- 0:23 Change one habit, then compare the next measured window before judging progress.
Synthetic example. Read the guide
Where to find it
Where to find it
- Desktop:
localhost:4000, then Memory in the sidebar, then Context health under All tools, in the Knowledge health group. - Hosted:
repoops.ai/team/context-health, from Memory in the sidebar, then Context health under All tools, in the Knowledge health group. - Keyboard: ⌘ K, then type “Context health”.
When to use it
Fresh input is high across several sessions
Situation. At least three captured sessions average 150000 or more fresh-input tokens, where fresh input is input plus cache creation.
What you do. Open Active findings, read the evidence for cc.context-health.context-bloat, and compare it with the suggested fix before changing how sessions begin.
What you see. The finding names the average fresh-input total and session count. With the default weights, its Warn severity subtracts 5 points and appears in Per-rule deductions.
What it establishes. You have a measured reason to test a narrower opening prompt, bounded reads, or shorter tool output. The score does not establish which of those changes caused a later difference.
Prompt-cache reuse is low
Situation. At least three sessions carry at least 100000 fresh-input tokens, and cache reads are less than half of fresh plus cached input.
What you do. Inspect cc.context-health.cache-read-low. Check the displayed cache-read and fresh totals before deciding whether frequent compaction, restarts, or topic changes fit the work.
What you see. The finding shows the cache-read share and the underlying totals. Its Warn severity contributes the configured Warn deduction once.
What it establishes. You can test one context habit and compare a later window. A low share can describe the work pattern, so the finding is a prompt to inspect rather than a verdict on the developer.
Before you start
- Supported versions
- RepoOps desktop v0.3.1, the release this guide was read against.
- Where it runs
- Local: Memory, then Context health under All tools. Hosted: /team/context-health, under All tools on Memory, is an authenticated pointer to the desktop and states that no team-wide score is available.
- Permissions
- Read access to the selected repository's local Claude Code telemetry. Saving severity weights writes config/health-weights.json beside the running server.
- Connections
- No model or external service connection. The read path aggregates local telemetry and runs deterministic rules.
- Plan
- Not provided. The route and scoring modules contain no product-plan gate.
Configure it
- Choose the repository and window.
Open Context health for the repository, then choose 7 days, 30 days, or 90 days from Window. The default is 30 days, and the API caps direct requests at 90.
- Read findings before changing weights.
Active findings shows the rule id, severity, evidence, and Suggested fix. Per-rule deductions shows exactly how each finding changed the score.
- Tune severity only when the cost of a finding differs for this install.
Severity weights apply to all repositories served by this running RepoOps checkout and also feed the CLAUDE.md scorecard. Enter values from 0 to 100, then press Save weights.
- Tune a rule at its rule source.
The health page links to the anti-pattern rule engine. Per-rule thresholds live under config/rules by rule id; changing them changes whether a finding fires, while severity weights change only its deduction.
| Setting | Where | A sensible choice | Why it matters |
|---|---|---|---|
sinceDays | Context health, Window | 30 days (the default); 7 and 90 days are the other tab choices | Sets the local telemetry window. The shared clamp limits direct API values to 90 days. |
error | Context health, Severity weights, Error | 10 (the default) | Points deducted for each Error finding. |
warn | Context health, Severity weights, Warn | 5 (the default) | Points deducted for each Warn finding. |
info | Context health, Severity weights, Info | 1 (the default) | Points deducted for each Info finding. |
cc.context-health.cache-read-low | config/rules/cc.context-health.cache-read-low.json | minSessions 3, minFreshInput 100000, minCacheShare 0.5 | The rule stays silent below the sample floors and fires only when cache-read share is under the configured share. |
cc.context-health.context-bloat | config/rules/cc.context-health.context-bloat.json | minSessions 3, avgFreshInputCap 150000 | The rule fires when average fresh input per session meets or exceeds the cap. |
What you should see
No active health finding
Configuration. A selected window whose telemetry does not make any registered health rule fire.
Expect. A score of 100, zero active findings, and no per-rule deduction. This can also occur when a rule lacks enough samples.
Verify. Check the session count and window before treating 100 as a broad claim. The score only covers rules that had enough input to evaluate.
Two Warn findings under default weights
Configuration. The context-bloat and cache-read-low rules both fire, with Warn left at 5.
Expect. A score of 90. Active findings shows both rules, and Per-rule deductions shows 5 points for each.
Verify. Match the score to the two deduction rows, then inspect the evidence and suggested fix on each finding.
Weights changed for the running install
Configuration. Enter new Error, Warn, and Info values, then press Save weights.
Expect. The route validates each value from 0 to 100, writes config/health-weights.json, clears the cached health and scorecard reads, and reloads the score.
Verify. The control reads Saved. and the visible score and deductions recompute. Open the CLAUDE.md scorecard to account for the same shared weights there.
Data and cost
- What is captured
- Context health reads the local Claude Code aggregate: session ids and times, token counts, model, working directory, tool-use counts, and derived session totals from daily JSONL files under .claude/brain/claude-code-usage. The health response carries totals, findings, weights, and deduction rows.
- Who can see it
- The score and findings stay on the local machine. The hosted Context health page does not receive or compute a team rollup; it points signed-in users back to the desktop and to separate hosted health pages.
- How long it is kept
- Not provided. The 7, 30, or 90-day choice limits the read window but does not delete the daily telemetry files.
- What leaves the machine
- Nothing leaves the machine for scoring. GET /api/health reads local files and runs local rules. Saving weights writes a local JSON file.
- What it costs
- No model call and no provider charge. The endpoint performs a bounded local aggregate and rule evaluation.
When the result differs
| Symptom | Likely cause | Next action |
|---|---|---|
| The page says it could not load health data. | The repository id is unknown or local aggregation threw an error. | Open Context health from the selected repository. If it still fails, inspect the API error returned by /api/health for that repo id. |
| The score is 100 with little or no session history. | No health rule fired. Several rules require a minimum sample before they can fire. | Check the selected window and captured session count. Treat the result as no active finding in the available data, not proof of healthy future sessions. |
| A direct request for more than 90 days returns 90 days. | clampSinceDays caps the read window at 90. | Use one of the tab's 7, 30, or 90-day choices. |
| Save weights is refused. | A value is not a finite number from 0 to 100, or the payload includes an unknown severity. | Enter values from 0 to 100 for Error, Warn, and Info, then save again. |
| The hosted page has no score. | The hosted route has no team-side producer for local context-health findings. | Open Context health in the desktop app for the repository. Use hosted Brain health for the separate team-wide brain signal. |
- Disable
- Not provided. public/health.html exposes no feature-specific disable control.
- Roll back
- Not provided. Re-enter the previous severity weights or restore config/health-weights.json outside RepoOps.
- Revoke access
- Not provided. Local scoring has no feature credential or external connection to revoke. Signing out controls access to the hosted pointer page.
- Delete
- Not provided. The score is derived from daily files under .claude/brain/claude-code-usage, and the feature exposes no telemetry purge or weight-delete action.
Related tasks
Maintenance evidence
- Feature id
context-health(spine leafcontext-health)- Owner
- Engineering-quality and coaching parity, Tier-1-b; Guide: LDG-0717
- Supported product version
- RepoOps v0.3.1
- Last verified
- 2026-09-15, read against origin/main at 52366bb6d; labels read from the served tab source; hosted pointer and current health rule registry also checked
- Example fixtures
- lib/rules/health-score.test.mjs; lib/rules/cc.context-health.test.mjs; lib/rules/index.test.mjs; lib/rules/cc.undelegated-reads.test.mjs; lib/rules/cc.session-fragmentation.test.mjs; lib/rules/cc.runaway-loop.test.mjs; lib/api-cache.test.mjs; website/app/docs-cut-3.test.ts
- Source references
lib/canonical-spine.json,lib/canonical-tabs.mjs,public/health.html,public/lib/repoops-tab.js,lib/routes/health.mjs,lib/rules/health-score.mjs,lib/rules/index.mjs,lib/rules/cc.context-health.cache-read-low.mjs,lib/rules/cc.context-health.context-bloat.mjs,lib/since-days.mjs,lib/cc-telemetry.mjs,lib/today.mjs,website/app/team/(home)/context-health/page.tsx- Documentation review
- Independent review requested on the slice pull request; not yet recorded.
- Video review
- Narrated story rendered and published 2026-09-26 (render ed106c0e2260, LDG-1014) with the breadcrumb Memory, which lists the feature under Moved here, checked against main at 7aab4cd82 with LDG-1014 part 1. Six frames, the captions and the transcript were reviewed by the authoring agent, not an independent reviewer; the audio was not listened to by a person. Narration is the provisional Windows voice until LDG-0721.
Last updated