Krypton
File ordering

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.

Replays your historyOnly file names and numbers leave your machine.
Tries several ordersStable first, token-weighted, least recent, alphabetical, reverse.
Changes only on a clear winOtherwise your order goes out untouched.
The rule. Krypton never intervenes on a guess. It replays your repository's own history, and only a clear, repeated win changes the order. In every other case the answer is 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.

OptionWhat it does
REPOA git repository. Its history is the evidence.
--subdir DIRThe folder whose files go in the prompt. Default: the repository root.
--ext .py,.tsWhich file suffixes count. Default .py.
--files FILEThe 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 FILEHow file sizes are counted: in the tokens of the model the prompt is for. See Token counts.
--postSend the request and print the decision (without it, the request itself is printed).
--jsonPrint 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:

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