Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,8 @@ and states its assumption that the unpriced requests resemble the priced ones.
through the recommendations and offers to apply each one, editing a settings
file only after showing the change and getting a yes. Machine-readable output
for other tools, such as quest's session export, lives in other commands and
never shapes `doctor`.
never shapes `doctor`. A change to `doctor`'s questions reruns
`assets/demo/walk.tape`, since no check runs it.

- Never edit a transcript, and never print or keep prompt or reply text.
- The README is for someone deciding whether to run the tool. Per-check
Expand Down
2 changes: 1 addition & 1 deletion CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

PRs into `main` land by squash through GitHub's merge queue, which tests
each entry against the current `main` with the required `Check` job
(`nix develop --command just check`, plus the macOS and Windows tests, or
(`just check` in the Nix dev shell, plus the macOS and Windows tests, or
only `quest check` when nothing outside `quest/` and the agent docs changed). A
branch only behind `main` needs no merge; merge `main` only when the PR
conflicts or the queue refuses its head.
Expand Down
4 changes: 2 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ That is 1,190,393 Claude Code, Codex and T3 Code requests at public API
prices. The savings are what `token-max doctor --defaults` finds for a user
with no settings files on the same history: every change it would make, 8%
of the spend. Most of it is a 1h subagent cache; the rest is a 1h main-agent
cache on usage credits, auto memory and unused skills and tools.
cache on usage credits, auto memory and unused or costly skills and tools.

- **Subagents: a 1h prompt cache cost ~17% less than the default 5m**, ~$3,940/mo
of those savings. Every Claude Code user's subagents get 5m. The setting is
Expand Down Expand Up @@ -114,7 +114,7 @@ token-max doctor --help
| Tools, skills and MCP servers | What each cost to send with every request, and how often it was used |
| Instruction files | What each CLAUDE.md or AGENTS.md cost, beside the provider's size guidance |
| Fast mode | What the premium cost; recommended off |
| Main-session effort | What each model and effort cost, beside the provider's guidance; `max` recommended down to `xhigh`, `low` worth considering raising |
| Main-session effort | What each model and effort cost, beside the provider's guidance; `max` recommended down to `xhigh` (or `high` where a model lacks it), `low` worth considering raising |
| Auto memory | What loading, reading and writing it cost, and how often it was used; worth considering off |
| Prompt suggestions, recaps, check-ins | What each background feature cost, where it can be estimated |
| Bash timeout cap | Whether long foreground waits let the cache expire |
Expand Down
5 changes: 5 additions & 0 deletions assets/demo/walk.tape
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,11 @@ Show
Type "token-max doctor"
Sleep 500ms
Enter
Sleep 2s
# How the profile pays: usage credits, so its main agent's default cache is 5m.
Type "a"
Sleep 300ms
Enter
Sleep 4s
Type "y"
Sleep 300ms
Expand Down
42 changes: 21 additions & 21 deletions docs/reference.md
Original file line number Diff line number Diff line change
Expand Up @@ -48,12 +48,12 @@ once, as a diff. A change whose saving was not measured, such as raising an
effort, comes after the measured ones and says so.

A change saving $5/mo or more is its own question. A smaller one joins a group
of its kind and reason: never used, no use recorded where the window cannot
rule one out, over `--max-cost-per-use` per use, or a redundant copy of a
Codex catalog skill whose most-used copy stays, such as never-used skills
or MCP servers over $1 per use. Each reason is its own group, so one yes never
covers a feature in use. A group is one question ranked by its combined saving,
which names every member and takes `y` for all, `n` for none or `o` to go
of its kind and reason, such as never-used skills or MCP servers over $1 per
use. The reasons are never used, no use recorded where the window cannot rule
one out, over `--max-cost-per-use` per use, and a redundant copy of a Codex
catalog skill whose most-used copy stays. Each reason is its own group, so a yes to
never-used features never also removes one in use. A group is one question ranked by its combined saving,
which names every member and takes `y` for all, `n` for none, `q` to quit or `o` to go
through them one at a time; a group of one is asked as that change. Features
whose savings were not measured, such as Codex catalog skills, are grouped the
same way after the measured questions. A group saving under $1/mo in total,
Expand Down Expand Up @@ -299,7 +299,7 @@ changes it, and the list ends with the source:
| --- | --- |
| Main-agent prompt cache TTL, while unset | Claude Code [requests 1h](https://code.claude.com/docs/en/prompt-caching#which-ttl-each-request-gets) for the main conversation on a Claude plan within its included usage, and 5m once usage credits or an API key pay for it. When `doctor` asked how the profile pays, the line shows that default, such as `1h (default)`, and prices against it alone. Otherwise token-max can't tell which applies, so the line shows `unset` and names both. When the replay picks a winner, setting it is the cheaper choice either way, so the line recommends `unset -> 1h` (or `5m`) and `doctor` offers to set it; it shows the replay's gap as "saves up to", saved only while the other default would apply. |
| Claude fast mode | A Claude plan [pays fast mode only from usage credits](https://code.claude.com/docs/en/fast-mode#requirements), at its API rates, even with plan usage left. |
| Codex fast mode | A ChatGPT plan [counts Fast at 2.5x and Ultrafast at 8x](https://learn.chatgpt.com/docs/pricing) standard against included usage, and 2x and 6x on credits. The API premium priced is 2x for Fast on GPT-6 and GPT-5.6 and 6x for Ultrafast, so included usage can draw faster than it shows. |
| Codex fast mode | A ChatGPT plan [counts Fast at 2.5x and Ultrafast at 8x](https://learn.chatgpt.com/docs/pricing) standard against included usage, and 2x and 6x on credits. The API premium priced is the [documented API rate](semantics.md#speed-controls-and-premiums), which can be lower, so included usage can draw faster than it shows. |
| Prompt suggestions | Claude Code [skips them](https://code.claude.com/docs/en/costs#background-token-usage) while a plan is near its usage limit, which the estimate, run on every eligible turn, cannot see. |
| Fable weekly use | Anthropic [caps Fable models](https://support.claude.com/en/articles/15424964-claude-fable-models-on-your-plan) at up to half the weekly usage limit on Max, Ultra and Team and seat-based Enterprise premium seats, drawing it faster than other models, runs them on usage credits on Pro and Team and seat-based Enterprise standard seats, and bills them at API rates on usage-based Enterprise. The line shows weekly API-price spend and no share of the cap, as [Fable weekly use](#fable-weekly-use) explains. |
| Codex compaction window and keepalive pings | ChatGPT credits [charge cache writes as ordinary input](https://learn.chatgpt.com/docs/pricing), while API prices from GPT-5.6 on charge 1.25x for a 30-minute write, so a replay that trades writes for reads can come out differently on credits. |
Expand Down Expand Up @@ -386,11 +386,12 @@ The kinds of claim are:
keepalive pings, background generation, tool output caps, and every tool,
skill and MCP server, with subagent types and context no setting turns off.
- **Official**: the provider's own guidance beside what the transcripts show:
CLAUDE.md length and the AGENTS.md byte budget, MCP tool loading, and
Fable's weekly use beside the plan rule. A Claude
CLAUDE.md length and the AGENTS.md byte budget, MCP tool loading,
main-session effort, and Fable's weekly use beside the plan rule. A Claude
subagent type's evidence also cites Anthropic's model guide.
- **Opinion**: the maintainer's preference, beside whatever was measured: fast
mode off and auto memory off.
mode off, auto memory off, raising a `low` effort, and lowering a Codex
`max` effort.

The lines come in two groups. **Changes** come first: every line recommended
(red, exit 1) or worth considering (yellow, exit 0), ranked together by what
Expand Down Expand Up @@ -705,8 +706,7 @@ the verdict in its color, the saving green, and labels dim. `NO_COLOR`
disables color, and `--plain` also disables decorative Unicode, and either
puts the verdict word back in place of the dot. Evidence cards keep their
verdict words and only add color, and each names its claim. Redirected output
is plain, and progress appears only on interactive stderr. SIGINT or SIGTERM ends
with exit 2 and no success report.
is plain, and progress appears only on interactive stderr.
Unicode decorations require a UTF-8 locale. Progress is one line that shows each
phase in turn, never an invented percent, and clears itself before the report.

Expand All @@ -718,9 +718,10 @@ as the session export below.

IDs in the report are opaque hashes. Shared histories are read once, and a
request whose profile is ambiguous counts once on the line its profiles share
(see [Profiles](#profiles)). Independent check savings must not be summed; the
walk's running total and the [savings against the defaults](#savings-against-the-defaults)
are the only sums, and each says that overlapping settings may save less.
(see [Profiles](#profiles)). Independent check savings must not be summed;
every total the report gives, such as the walk's running total or the
[savings against the defaults](#savings-against-the-defaults), says that
overlapping changes may save less.

## Session export

Expand Down Expand Up @@ -988,7 +989,7 @@ connection that then runs the audit:
runs the first installed `token-max` whose `--version` matches, on the
non-interactive `PATH`, then in the release installers' directory (the
first of `$XDG_BIN_HOME`, `$XDG_DATA_HOME/../bin` and `~/.local/bin`),
then in `~/.cargo/bin`. With neither, the destination downloads the
then in `$CARGO_HOME/bin` (default `~/.cargo/bin`). With neither, the destination downloads the
release from GitHub and checks it against its published checksum, which
needs `curl`, `tar` and `xz` there. Matching the version is not matching
the build, so a destination whose build differs from this one fails,
Expand Down Expand Up @@ -1021,9 +1022,8 @@ too small. Any failed
host, connection or stream before the reports are printed fails the whole run
with exit 2 and no report, and Ctrl-C then stops every destination. After
the reports, a failure during the walk, a Ctrl-C during its questions, or a
Ctrl-C after the yes that leaves a host unwritten also exits 2, as
[On SSH hosts](#on-ssh-hosts) describes. On a terminal, `doctor` walks through every
host's changes and writes each on its own host, as
Ctrl-C after the yes that leaves a host unwritten also exits 2. On a terminal,
`doctor` walks through every host's changes and writes each on its own host, as
[On SSH hosts](#on-ssh-hosts) describes. Each host's percents
are of that host's own spend, and the total's of the hosts' spend together.

Expand Down Expand Up @@ -1052,8 +1052,8 @@ activity, and their metadata does not establish whether they are keepalive pings
The maintainer's cost preference is fast mode off for both harnesses. The
`fast-mode` check names the current effective local preference, its owner and
the standard-speed replacement: Claude `fastMode: false`, or Codex
`service_tier = "default"`. Use `/fast off` for an active session. No settings
are edited. A justified current premium preference causes exit 1 even without
`service_tier = "default"`, which `doctor` offers to make when the profile's
own file owns the setting. Use `/fast off` for an active session. A justified current premium preference causes exit 1 even without
historical usage or prices. Standard current settings never receive a change
because of historical premium sessions.

Expand Down
2 changes: 1 addition & 1 deletion docs/releasing.md
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,7 @@ Each release carries, per target, `token-max-<target>.tar.xz` (a
`token-max-<target>/` directory holding the binary, README and LICENSE) or,
on Windows, a flat `token-max-<target>.zip`, each with a `.sha256` file;
`token-max-installer.sh` and `token-max-installer.ps1`, which install into
the first of `$XDG_BIN_HOME`, `$XDG_DATA_HOME/../bin` and `~/.local/bin`; `source.tar.gz`; and `sha256.sum` over the archives. Every
the first of `$XDG_BIN_HOME`, `$XDG_DATA_HOME/../bin` and `~/.local/bin`; `source.tar.gz` with its `.sha256`; and `sha256.sum` over the archives. Every
asset gets a GitHub build provenance attestation, which
`gh attestation verify <file> --repo kixel-ai/token-max` checks.
`[package.metadata.binstall]` in `Cargo.toml` points `cargo binstall` at the
Expand Down
9 changes: 5 additions & 4 deletions docs/results.md
Original file line number Diff line number Diff line change
Expand Up @@ -48,10 +48,11 @@ Against the maintainer's current settings, the changes doctor still offers save
~$781/mo. Their settings already save ~$4,452/mo against the defaults, as each
report's "Compared with defaults" line gives it: the 1h caches the plan
profiles set, less the small cost of the 1h subagent cache on the usage
credits profiles.
credits profiles. Each figure adds up changes measured one at a time against
a different baseline, so together they need not equal the ~$5,653/mo above.

doctor asked how each Claude profile pays, and each answer came from the
profile's account (`oauthAccount.billingType` in its `.claude.json`): every
doctor asked how each Claude profile pays, and the maintainer answered from
the profile's account (`oauthAccount.billingType` in its `.claude.json`): every
machine's `~/.claude` is on a plan, and the usage credits profiles, plus an
archived profile with no account, were answered as API. Every offered change
was declined, and no settings file changed.
Expand All @@ -71,7 +72,7 @@ The plan profiles' subagent line is now priced, so its ~$3,940/mo is in the
savings above. The previous snapshot left it out as "not enough evidence": T3
Code shares those profiles' histories, and doctor could not tell whether a T3
session ran under the profile's setting. It now reads the shared settings file
for the controls T3 leaves alone. [How context is priced](reference.md#how-context-is-priced)
for the controls T3 leaves alone. [T3 Code](reference.md#t3-code)
describes the rule. On the usage credits profiles, whose main agent gets 5m
unless set, 1h is the ~$518/mo in the savings; on their few subagent requests
5m was cheaper, by ~$3.63 over the window.
Expand Down
Loading
Loading