Reorder only when Krypton would win
Before a request, krypton order asks the server to check whether Krypton's file order would have reused more of a prompt cache than yours. If it would not, it does nothing: your request goes out exactly as you built it.
keep.The idea
Providers cache the longest identical prefix of a request, so files that rarely change belong at the front. Prompt caching shows that this helps a lot on some repositories and can hurt on others, for example after a refactor. A tool that always reorders would sometimes make a request worse. krypton order is built so that it cannot do that on evidence: it tests the order against your history first.
Using it
$ krypton order . --subdir src --ext .py,.ts --files request.txt --model gpt-4o --post
# request.txt: the files in this request, one per line, in your current order
The client reads git on your machine and sends the server only file names, token counts, and which files each recent commit touched: no source, no commit messages, no authors. The server decides and answers.
| Option | What it does |
|---|---|
REPO | A git repository. Its history is the evidence. |
--subdir DIR | The folder whose files go in the prompt. Default: the repository root. |
--ext .py,.ts | Which file suffixes count. Default .py. |
--files FILE | The files in this request, one per line, in your order. - reads standard input. Without it, all matching files in alphabetical order stand in for your order. |
--model NAME, --tokenizer, --tokens-from FILE | How file sizes are counted: in the tokens of the model the prompt is for. See Token counts. |
--post | Send the request and print the decision (without it, the request itself is printed). |
--json | Print the full decision as JSON, for an agent harness or a tool. |
The exit code is 0 whenever the server answered; read the action field. It is 1 when it could not be asked or refused the request, and 2 for a usage error, with a message saying what to do.
How it decides
Krypton tries several orders: stable files first, token-weighted, least recently changed first, alphabetical and reverse alphabetical. For each past change that touched files in the request, it builds each order from the commits before that change only, and measures how much of the prompt each order, yours and Krypton's, would have kept in a cache when that change landed. Each order is judged on a change it could not have seen. The answer is keep unless all of these hold:
- Enough past changes touched the files in this request: enough evidence.
- Krypton's order is different from yours.
- On average it would have kept clearly more of the prompt.
- It was ahead in more changes than it was behind, among the changes where the two orders differ.
Uncommitted files go last, since they are the ones in flux. Ordering never changes a score.
The answer
# when Krypton would not win (illustrative numbers)
KEEP: only 5 past changes touched these files: too little history
12 files; backtest over 5 past changes: yours kept 41.2% of the prompt, the best order (stable-first) 44.0%
orders tried: stable-first 44.0%, least-recent 43.1%, alphabetical 41.2%, token-weighted 40.9%, reverse-alphabetical 12.5%
send the request unchanged.
# when it would (illustrative numbers)
REORDER: Krypton's order would have kept +13.4% more of the prompt, ahead in 9 of 11 differing changes
send the files in this order:
src/config.py
src/models.py
...
With --json:
{
"action": "keep", // or "reorder"
"reason": "...",
"strategy": "stable-first", // the order that kept the most
"tried": [{ "strategy": "stable-first", "kept": 0.44 }, "..."],
"order": ["..."], // your order when keep, Krypton's when reorder
"backtest": { "changes": 5, "differing": 3, "wins": 1, "losses": 2,
"gain": 0.028, "baseline_kept": 0.412, "krypton_kept": 0.44 }
}
When the answer is keep, order is your own order, so a caller can always send order as is.
Token counts come from the model you name (see Token counts); without a model they are a stated estimate, and the command says so on standard error.
What we learned
Tested on history it had not seen, the guard reordered when it would help and kept your order when it would not. It is deliberately cautious: when it hesitates it keeps, so it sometimes misses a gain, because a missed gain costs nothing and a bad reorder does. The test, step by step.
What it keeps
On your machine, only if you name a Claude model, token counts from Anthropic's counter are cached by content hash in .krypton/tokens.json (numbers, no file names or source), so a second run asks for nothing. If you name a Claude model, each file's text goes to Anthropic to be counted, with your own API key; it never goes to Krypton.
Limits
- It needs a git repository with history for the files in the request. With too little, the honest answer is
keep. - It judges a file order, not a prompt. How much a reordering saves also depends on where your provider's cache breakpoints sit; with a single breakpoint at the end of the prompt no order helped in our tests.
- It is a command with JSON output. An agent harness that knows the model can pass it with
--model; Krypton cannot see which model your agent calls.