Krypton
Review

A person approves what the agent could not simplify

An agent refactoring toward a better score sometimes gets stuck: three tries later a function is barely better. Krypton keeps a log of every try, says which functions are stuck, and puts any earlier try back. Your coding agent turns that into a small page on your own computer where you approve the best try or send it back, before anything goes to GitHub.

Every try is loggedEach run's score and files are kept on your machine.
You decide, or it doesAsk me opens a local review page; Auto keeps the best run.
Before GitHubNothing is pushed until the stuck functions are settled.

Set it up once

The first time you run the Krypton image in a repository, it maps the whole codebase and shows its score today, then asks four things: the target score each ticket's code must reach (it suggests one a step above today's score), how many tries the agent gets on a function before it counts as stuck, whether a stuck function should ask you or be approved automatically, and whether to set up the pull request gate on GitHub. Answer in the terminal, or pick the browser and it prints a one-time link to a local settings dashboard where you click them instead.

Krypton suggests the target from today's score: a step above it, so a codebase that scores 56 gets 70. Only new tickets are held to it, so the code they touch gets cleaner one ticket at a time while old code never blocks anyone. Run setup again as the score climbs and the suggestion climbs with it; it never drops below a target you saved.

For the gate, setup writes .github/workflows/krypton.yml with the rule you pick: never worse (a pull request fails only if it lowers the purity score) or target (the files a pull request changes must reach your target; the rest of the codebase is never judged). Commit the file to turn the gate on. Run setup again to change the gate or the target and it rewrites that file, so the old rule never lingers; commit it again. If you edit the workflow by hand, delete its # Written by `krypton setup` line and setup will leave it alone.

docker run -it --rm -p 127.0.0.1:7777:7777 -v "$PWD:/repo" krypton   # terminal or local dashboard
krypton setup --page                                                  # straight to the dashboard link
krypton setup --mode manual|auto --target 70 --runs 3 --gate target  # no questions

You can change these later in the terminal (krypton setup) or on the review page your agent builds, which has a small Settings panel styled by your themes.md. The answer is kept in .krypton/settings.json, which git never sees. krypton review --auto or --manual overrides it for one run.

The review step

  1. Log each run. The agent runs krypton scan . --log --ticket "what it is fixing" before it starts (run 0) and after each change. Each run records the purity score and how far over the limit every function is, under its real name, in .krypton/runs.jsonl, and saves the state of the files as a patch.
  2. Ask what is stuck. krypton review --json lists the functions that, after the start and three runs, are still over the limit and never got more than 10% better than where they started, with the score at every run and the best run.
  3. Show a person. The agent builds one local page from that data and your themes.md. For each stuck function you choose Approve best or Send back.
  4. Carry on. Approved: krypton restore --run N puts the best run's files back and the agent continues to push and open the pull request. Sent back: the agent tries that function again.

Nothing in this step leaves your machine.

Commands

scan --log

krypton scan . --log --ticket "fix discount rounding"

Scores as usual, then adds the run to the log and saves its attempt. --ticket names the piece of work; the first run of a ticket is run 0. It needs a git repository with a first commit and must be run from the repository's top folder. The .krypton/ folder ignores itself (it holds a .gitignore of its own), so the log and the saved code cannot be committed by accident.

review

krypton review [REPO] [--ticket TEXT] [--json] [--auto|--manual]

Without --json it prints a short summary. With it:

{
  "ticket": "fix discount rounding",
  "runs": [ {"run": 0, "purity": 71}, {"run": 1, "purity": 72}, ... ],
  "purity": { "start": 71, "now": 72, "if_approved": 74 },
  "restore_run": 2,
  "needs_review": true,
  "improved": 12,
  "stuck": [ { "file": "checkout.py", "function": "apply_discount",
               "ratings": [46.0, 45.0, 43.0, 44.0], "best_run": 2, "best": 43.0 } ],
  "note": null
}

A score is how many times the limit a function is at (1× is the most a function may have). restore_run is the run with the highest purity, and if_approved is the purity at that run.

restore

krypton restore --run N [REPO] [--ticket TEXT] [--dry-run] [--force]

Puts the files back to how they were at run N. It refuses if the files have changed since the last logged run, so nothing unsaved is lost; --force skips that check after saving what is there to .krypton/attempts/before-restore.patch. --dry-run lists the files it would change and touches nothing. If a patch does not apply cleanly, everything is put back and the reason is printed. No commits or branches are made.

comment (the scorecard) and scan --summary

krypton scan . --summary head.json
krypton comment base.json head.json [--line FILE] [--fail-if-worse] [--target N [--changed changed.json]]

--summary writes the run's scores to a file and does not fail on a flagged review. comment prints the pull request scorecard as markdown, and --line writes the gate line. With --target, a third summary of only the changed files (krypton scan . --base BASE --summary changed.json) must score at least N; without --changed, no source file changed and there is nothing to hold to the target.

The review page

Krypton does not build the page and does not read themes.md. The agent you already use builds it, following agent/review-brief.md: the same outline every time (the ticket, purity now and if you approve, one card per stuck function with its scores and two buttons, and a footer), styled the way themes.md describes in your own words. See the preview.

On GitHub

krypton setup writes this workflow for you. Install the Krypton app on the repository (github.com/apps/kr-ypton, read-only code access plus pull request comments and commit statuses) and the comment and the gate line come from Krypton, with its crystal, the way a product's own bot does; without it they come from github-actions and work the same. The comment opens with Krypton's lavender card, drawn from the numbers alone. The action in this repository's root scores a pull request against its base and puts one line in its checks. It also keeps one comment on the pull request with the scorecard, the purity before and after in lavender, and edits that same comment on every push instead of adding another, so the conversation never fills up. Turn the comment off with with: { comment: "false" }.

name: Krypton
on:
  pull_request:
permissions:
  contents: read
  statuses: write
  pull-requests: write
  id-token: write
jobs:
  structure:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 0 }
      - uses: pinklamb/Krypton@main

The line is green unless you turn on a rule. Never worse: add with: { fail-on-worse: "true" } to the action step, and a pull request fails if the score went down. Target: add with: { target: "70" }, and a pull request fails if the files it changed score below 70; the line then reads, for example, Purity ▲ 56% → 57% (+1) · changed code 64% (target 70).

The action logs in to Krypton as your repository with the run's own GitHub identity (id-token: write), so there is no secret to store. statuses: write lets it set the line, and pull-requests: write lets it keep its one comment up to date; without it the comment is skipped with a warning and the gate still works.

The scorecard in the run summary looks like this:

### Krypton · ▲ 71% → 74% (+3)

| | Before | After |
|---|---|---|
| Purity | 71% | 74% |
| Over the limit | 14 | 12 |

**2 functions got worse**
- `billing.py · apply_discount` 40× → 44×
- `auth.ts · refresh_session` under the limit → 2×

Limits