Commit graph

7 commits

Author SHA1 Message Date
Resham Joshi
d965273b59
feat(optimize): flag an autoCompactWindow that blocks idle compaction (#1870)
* feat(optimize): flag an autoCompactWindow that blocks idle compaction

* fix(optimize): render a finding without a dollar figure cleanly and gate the idle-compaction rule on the one-hour cache

* fix(optimize): group headers without a figure when the group has none
2026-11-05 05:28:08 +01:00
Resham Joshi
b18d42d0b4
feat(optimize): flag one-hour cache writes the next request never needed (#1860)
* fix(optimize): price findings from the calls they point at

Every finding's dollar figure was its token estimate times one blended
rate: 70% of the period's spend over all input-side tokens. That rate is
close to a cache-read price, so it misprices anything that is not a cache
read. Schema findings already weight cache reads at 0.1, so their reads
were discounted twice; findings whose tokens include output were priced
as input.

A finding can now carry savingsUSD, computed from the calls it names.
Every surface reads it through findingUSD: the CLI and TUI optimize
views, the JSON report (and so the desktop Optimize page), the menubar
payload and MCP get_savings, and the --apply list. classTotals sums it,
scaled to the apply-able share for fix findings. Findings without it keep
tokensSaved times the blended rate, and any token whose session or model
has no price still falls back to that rate.

Measured now:
- low-worth-sessions: each session's real cost times its recovery fraction
- retry-heavy-capabilities: the retry turns' real cost times the fraction
- redundant-rereads, build-folder-reads: the reads at the input rate of
  their session's most-called model
- warmup-heavy: the excess cache writes at the session model's write rate
- mcp-low-coverage, mcp-project-scope: each call's charged schema tokens
  at that call model's cache-write or cache-read rate
- unused-mcp, mcp-deferral-off, mcp-alwaysload-hygiene,
  mcp-defer-threshold: the per-session schema at the input rate of the
  sessions charged

Still on the blended rate, because no calls can be named: read-edit-ratio
(reads that never happened), context-heavy-sessions, cost-outliers,
low-cache-hit-sessions, claude-md-too-long, bash-output-cap,
recurring-context and the unused agents, skills and commands.

* feat(optimize): flag one-hour cache writes the next request never needed

A one-hour prompt-cache write is billed at 1.6 times the five-minute
rate and only earns that back when the same model's cache is next used
after a pause of more than five minutes but less than an hour. Reads
refresh either TTL, so a write is judged by the first such pause after
it, not just by the very next call.

The new one-hour-cache-unused nudge walks each session per model in
time order, prices the 60% premium on every one-hour write that never
reached such a pause from the call's own model and tier, and fires at
one dollar or more. Unpriced models and five-minute writes add nothing.

* test(optimize): pin one-hour writes that later hits kept warm

Every cache hit refreshes the TTL, so a one-hour write followed by more
than an hour of steady activity and then a twenty-minute pause still
needed the hour. The detector already judges the length of the first
pause over five minutes, not its distance from the write; this test
pins that. A pause that itself runs past the hour still counts as
wasted, because the one-hour entry expires inside it either way.

Also lists one-hour-cache-unused among the measured findings.
2026-11-05 00:10:23 +01:00
Resham Joshi
f54345a5c3
README: tell the story first, keep the manual in docs (#1527)
Some checks are pending
CI / semgrep (push) Waiting to run
Tests / test (22) (push) Waiting to run
Tests / test (22.13.0) (push) Waiting to run
Tests / test (24) (push) Waiting to run
Tests / test (26) (push) Waiting to run
Tests / test-platforms (macos-latest) (push) Waiting to run
Tests / test-platforms (windows-latest) (push) Waiting to run
Tests / desktop (push) Waiting to run
* docs: move the README reference manual into docs/

* assets: designed README images and their sources

* README: tell the story first, keep the manual in docs
2026-09-22 16:28:27 +02:00
iamtoruk
b249ba1ffe Merge remote-tracking branch 'origin/main' into feat/optimize-recurring-context
# Conflicts:
#	CHANGELOG.md
2026-08-18 03:31:16 -07:00
iamtoruk
f8bc9b2594 docs: cover what happens after optimize --apply
docs/optimize.md gains an "After you apply" section (the four verdicts,
--auto-revert, what is never auto-reverted); README and CHANGELOG follow.
2026-08-18 03:15:12 -07:00
iamtoruk
8d8848d805 optimize: detect recurring context pasted at the start of sessions
Groups sessions by their opening block (whitespace/ANSI-normalized, hashed
over the first 2 KB) and flags a block of at least 1.5 KB that opens five or
more sessions. Class nudge: CodeBurn will not move the user's own text into
CLAUDE.md, so the fix asks Claude to give the block a permanent home. Only
the repeats count as savings, sized from the block's bytes because provider
usage is per API call and cannot isolate the paste. The opener comes from
the session scan that already runs, so nothing extra is read.
2026-08-18 03:13:40 -07:00
iamtoruk
6267c49c25 docs: document optimize classes, provenance, and what --apply writes
Adds docs/optimize.md (what optimize scans, the three classes, the exact
files --apply may touch plus undo, measured vs estimated, the health
grade bands, the --yes CLAUDE.md guardrail), links it from the README
waste section, and corrects the detector count in docs/architecture.md
(14 -> 19).
2026-08-18 02:27:01 -07:00