How Krypton works
Get started
You need Docker (Docker Desktop on macOS and Windows, Docker Engine on Linux) and git. Krypton runs inside Docker, so there is nothing else to install: no Rust, no Python, no clone.
- Get KryptonKrypton comes as a ready-made Docker image, so there is nothing to build or clone.
Prefer to build it yourself? Clone it anywhere (not inside your project), build it, and point the command below at it with$ docker pull ghcr.io/pinklamb/krypton:latestKRYPTON_IMAGE=krypton:git clone https://github.com/pinklamb/Krypton.gitthendocker build -t krypton Krypton/client. - Add the krypton commandPaste one of these into your terminal so
kryptonworks in any folder. On macOS, Linux and Git Bash (add it to~/.bashrcor~/.zshrcto keep it):
In PowerShell (add it to yourkrypton() { local image="${KRYPTON_IMAGE:-ghcr.io/pinklamb/krypton:latest}" here="$PWD" status if [ "$1" = update ]; then docker pull "$image"; return; fi command -v cygpath >/dev/null && here="$(cygpath -w "$PWD")" MSYS_NO_PATHCONV=1 docker run --rm $([ -t 0 ] && echo -it) $([ $# -eq 0 ] || [ "$1" = setup ] && echo -p 127.0.0.1:7777:7777) -v krypton-home:/krypton-home -v "$here:/repo" "$image" "$@" status=$? if [ "$status" -eq 75 ]; then docker pull "$image" && echo "Krypton is up to date."; return; fi return "$status" }$PROFILEto keep it):
When a new version is out, Krypton says so after a scan or setup (at most once a day, only at a terminal, never in CI) and asks Update now?; answer yes and the command pulls it.function krypton { $image = if ($env:KRYPTON_IMAGE) { $env:KRYPTON_IMAGE } else { 'ghcr.io/pinklamb/krypton:latest' } if ($args.Count -gt 0 -and $args[0] -eq 'update') { docker pull $image; return } $tty = @(); if (-not [Console]::IsInputRedirected) { $tty = @('-it') } $port = @(); if ($args.Count -eq 0 -or $args[0] -eq 'setup') { $port = @('-p', '127.0.0.1:7777:7777') } docker run --rm @tty @port -v krypton-home:/krypton-home -v "${PWD}:/repo" $image @args if ($LASTEXITCODE -eq 75) { docker pull $image; if ($LASTEXITCODE -eq 0) { 'Krypton is up to date.' } } }krypton updatedoes the same any time. - Set it up in your projectGo to your project's folder (
cd your-project) and runkrypton. It logs you in with GitHub (a short code you approve on github.com), maps your codebase and shows its score today, then suggests a target score a step above it (change it if you like), and asks for max tries, what happens when the agent is stuck, and whether to write the GitHub pull request gate for you. Answer in the terminal, or open the link it prints and click your settings on a local dashboard.$ krypton - Turn on the pull request gateIf you chose a gate, setup wrote
.github/workflows/krypton.ymlin your project. Commit and push it; from the next pull request on, its checks show one Krypton gate line. Your settings stay in.krypton/, which git never sees.$ git add .github/workflows/krypton.yml $ git commit -m "Add the Krypton gate" $ git push - ScanEvery
.py .js .jsx .mjs .cjs .ts .tsx .mts .ctsfile is read, skipping whatever.gitignoreand.kryptonignoreexclude, andnode_modules,dist,.gitand the like. At a terminal you see the trees being built, then the purity score from 0 to 100 (higher is lighter) and the most tangled functions;krypton scan . --fulladds every hint, and that full review is what an agent or CI reads anyway. Example values:$ krypton scan . /\ / \ Purity 38/100 / \ █████████░░░░░░░░░░░░░░░ \ / 1,150 functions over the limit, in 65 files. \ / 196 files scored in 158 ms \/ Most tangled 107× summarize tools/ak_summary.py 92.8× branch_row tools/ladder_summary.py 56.3× issue17 tools/stress_issues_e.py
Score only what changed
krypton scan . --base origin/main scores just this branch's lines, so old code never blames the agent.
Exit codes
0 fine, 1 the review failed or something could not be read, 2 a usage error.
Put it in your agent's loop
Paste this into CLAUDE.md, AGENTS.md or your tool's rules file:
## Code structure (Krypton)
- After editing source files, run: `krypton scan . --base HEAD --names`
- If a function you wrote is flagged, refactor it before finishing:
early returns, small named helpers, one job per function.
- Do not pack code onto fewer lines or split one function into trivial wrappers.
- Re-run Krypton after refactoring and report the purity score.
What happens to a file
Hints are advice only and never change a score.
Krypton counts every decision in a function (an if, a loop, a case, a catch, a boolean operator, a ternary) and where it sits: three decisions stacked inside each other are harder to follow than three side by side. It also counts effective size (packing lines does not help), coupling (a file wired to many others) and trivial wrappers (splitting code into tiny functions just to pass lowers the score). It measures structure, not correctness, so run your tests too.
What the server receives
Stays on your machine
- The source text
- Names in readable form, and the table from hash back to name
- Every string, number and comment
Sent to the server
- The tree: node kinds, positions, nesting
- Each name as a keyed hash
- Per line: length and where the visible characters are
- File path, language and size
krypton wire cart.py prints the exact request before anything is sent. The answer names each function by its hash; with --names your machine puts the real names back.
When the agent gets stuck
- Log each run
krypton scan . --log --ticket "what it is fixing"before the work and after each change. - Ask what is stuck
krypton review --jsonlists the functions that never got 10% better within your max tries. - You decide, or it doesAsk me: your agent builds a local review page styled by
themes.md. Auto: Krypton keeps the best run. - Carry on
krypton restore --run Nputs the best run back, then the agent opens the pull request.
The review guide has the settings, the commands and the GitHub Action.
See which model writes your best code
Krypton sits outside the model path, so it measures a change the same way whether it came from Claude, GPT, Gemini or a local model. Score around every change, note which model did the work, and compare purity with what each one cost you. The choice is back in your hands, not a vendor’s benchmark.
The whole client
| Command | What it does |
|---|---|
krypton or krypton setup | Map the codebase, choose target, max tries, ask me or auto, and the pull request gate (it writes the workflow), in the terminal or a local dashboard. |
krypton scan REPO | Score a folder; --base REF only what changed, --names real names back, --log records the run. |
krypton review | List the functions that are stuck. |
krypton restore --run N | Put the files back to how they were at run N. |
krypton order REPO | Pick the file order that keeps the most of a prompt cache, or keep yours. |
krypton login, krypton logout | Log in with GitHub (the server scores only for logged-in users and GitHub Actions runs). |
krypton comment | Write the pull request scorecard and the gate line. |
krypton wire FILE | Print the exact request instead of sending it. |
Go deeper
Review and setup
Target, max tries, ask me or auto.
Prompt caching
Measured results across 20 repositories.
File ordering
How krypton order decides.
Integrations
Agents, CI, Docker.
Commands
Every option.
API
Endpoints, responses, errors.
Wire format
Every field of the request.
Privacy
What is sent and what is kept.