Krypton
Documentation

How Krypton works

Your source stays homeYour machine parses the code. The server gets its structure, with every name swapped for a keyed hash.
Every change is checkedA change fails only if it makes the code worse, so old code never blocks anyone.
Cheaper promptsStable files first: up to 35% cheaper in our tests. Your result depends on your history.

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.

  1. Get KryptonKrypton comes as a ready-made Docker image, so there is nothing to build or clone.
    $ docker pull ghcr.io/pinklamb/krypton:latest
    Prefer to build it yourself? Clone it anywhere (not inside your project), build it, and point the command below at it with KRYPTON_IMAGE=krypton: git clone https://github.com/pinklamb/Krypton.git then docker build -t krypton Krypton/client.
  2. Add the krypton commandPaste one of these into your terminal so krypton works in any folder. On macOS, Linux and Git Bash (add it to ~/.bashrc or ~/.zshrc to keep it):
    krypton() {
      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"
    }
    In PowerShell (add it to your $PROFILE to keep 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.' } }
    }
    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. krypton update does the same any time.
  3. Set it up in your projectGo to your project's folder (cd your-project) and run krypton. 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.
  4. Turn on the pull request gateIf you chose a gate, setup wrote .github/workflows/krypton.yml in 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
  5. ScanEvery .py .js .jsx .mjs .cjs .ts .tsx .mts .cts file is read, skipping whatever .gitignore and .kryptonignore exclude, and node_modules, dist, .git and 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 . --full adds 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

ParseEach file becomes a syntax tree on your machine.
WalkOne pass records every decision and how deep it sits.
Rate and flagEach function and file gets a rating; heavy ones are flagged with a reason.
AdviseNames the deepest decision and the block worth pulling out.

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.

Names are keyedEach name is sent as a keyed hash (HMAC-SHA256). The key is made fresh for every scan, stays in memory on your machine and is thrown away afterwards, so nobody can test a guess against the hashes or link one request to another. Everything that is and is not sent.

When the agent gets stuck

  1. Log each runkrypton scan . --log --ticket "what it is fixing" before the work and after each change.
  2. Ask what is stuckkrypton review --json lists the functions that never got 10% better within your max tries.
  3. You decide, or it doesAsk me: your agent builds a local review page styled by themes.md. Auto: Krypton keeps the best run.
  4. Carry onkrypton restore --run N puts 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.

What it cannot doKrypton does not know which model wrote a change, and it does not rank models. You supply the label; the comparison is yours.

The whole client

CommandWhat it does
krypton or krypton setupMap 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 REPOScore a folder; --base REF only what changed, --names real names back, --log records the run.
krypton reviewList the functions that are stuck.
krypton restore --run NPut the files back to how they were at run N.
krypton order REPOPick the file order that keeps the most of a prompt cache, or keep yours.
krypton login, krypton logoutLog in with GitHub (the server scores only for logged-in users and GitHub Actions runs).
krypton commentWrite the pull request scorecard and the gate line.
krypton wire FILEPrint the exact request instead of sending it.

Go deeper