skrrt

CLI reference

Seven commands. skrrt COMMAND --help prints the same information; skrrt --version prints the version.

Install

sh
git clone https://github.com/jcpsimmons/skrrt && cd skrrt
uv venv
uv pip install -e ".[hf]"          # transformers backend
uv pip install -e ".[llamacpp]"    # GGUF backend; also run llamacpp/build.sh once

Python 3.10 or newer.

Naming a neuron, giving a dose

L14 N8949 is layer 14, neuron 8949. In a mixture-of-experts model there is an expert in the middle: L11 E14 N370. Quote it on the command line, because of the spaces.

A dose is signed and measured in residual norms (see dose). Write a negative one with an equals sign so it is not read as a flag: --dose=-1.5.

skrrt hunt

Rank, screen, confirm and report: the whole pipeline.

usage
skrrt hunt --model MODEL --persona PERSONA
           [--backend auto|hf|llamacpp|mock] [--backend-arg KEY=VALUE]
           [--judge auto|jev|self] [--out DIR] [--layers A-B]
           [--per-layer 8] [--screen-doses 1,2]
           [--doses 0.5,0.75,1,1.5,2,3] [--finalists 10] [--controls 4]
           [--max-tokens 100] [--seed 0] [--force]
--model MODEL
A Hugging Face model id or path, a .gguf file, or mock. Required.
--persona PERSONA
A built-in name or the path to a YAML file. Required.
--backend auto|hf|llamacpp|mock default auto
How the model is run. See Backends.
--backend-arg KEY=VALUE
Passed to the backend's constructor.
--judge auto|jev|self default auto
Who scores the replies. See Judges.
--out DIR default runs/<model>-<persona>/
The run directory.
--layers A-B default all
Layers to screen, inclusive.
--per-layer N default 8
Candidates per layer in the screen.
--screen-doses 1,2
Doses tried in the screen.
--doses 0.5,0.75,1,1.5,2,3
The dose sweep in the confirm stage.
--finalists N default 10
How many screened neurons go on to confirm.
--controls N default 4
Random control neurons per finalist layer.
--max-tokens N default 100
Reply length in the confirm stage. Screen replies are shorter (60 tokens).
--seed N default 0
Seed for the random choices, such as which control neurons are drawn.
--force
Redo every stage even if its output exists.
examples
skrrt hunt --model Qwen/Qwen3.5-4B --persona evil
skrrt hunt --model Qwen/Qwen3.5-4B --persona surfer.yaml --judge self --layers 8-20

With the defaults, a 36-layer model needs about 3,600 short generations for the screen and between 1,000 and 3,600 for the confirm stage, depending on how many layers the finalists come from.

skrrt personas

Lists the built-in personas.

sh
skrrt personas

skrrt new-persona

Writes NAME.yaml from the template, for you to edit. See Writing your own.

usage
skrrt new-persona NAME

skrrt write-replies

Fills a persona file's replies by answering its training prompts under its system text. Then the judge checks the replies, and skrrt warns when fewer than half are in persona.

usage
skrrt write-replies FILE.yaml [--model MODEL] [--writer WRITER]
                    [--backend auto|hf|llamacpp|mock] [--backend-arg KEY=VALUE]
                    [--judge auto|jev|self] [--max-tokens N] [--force]
--writer WRITER default target
target is the model itself. Anything else is taken as an OpenRouter chat model id and needs OPENROUTER_API_KEY.
--model MODEL
The target model. Needed for --writer target and for the self judge.
--judge auto|jev|self
Who checks the written replies.
--max-tokens N
Length limit for each reply.
--force
Replace replies that are already in the file. Without it, a file that has replies is left alone.
--backend, --backend-arg
As for hunt.

skrrt steer

Generate with one or more neurons pushed. With a prompt it prints one reply. Without one it starts an interactive loop.

usage
skrrt steer --model MODEL --neuron "L11 E14 N370" --dose DOSE
            [--persona PERSONA] [--max-tokens N] [--baseline]
            [--backend auto|hf|llamacpp|mock] [--backend-arg KEY=VALUE]
            [PROMPT]
--neuron "L11 E14 N370", --dose DOSE
The neuron and its signed dose. To push several neurons, repeat the pair: one --dose for each --neuron.
--baseline
Also print the unsteered reply, for comparison.
--persona PERSONA
Measure the residual stream's typical size on this persona's training prompts. Only matters if the persona has its own.
--max-tokens N
Length limit for the reply.
--model MODEL
A Hugging Face model id or path, a .gguf file, or mock.
--backend auto|hf|llamacpp|mock default auto
See Backends.
--backend-arg KEY=VALUE
Passed to the backend's constructor.
examples
skrrt steer --model M.gguf --neuron "L11 E14 N370" --dose 0.75 --baseline "How do I boil an egg?"
skrrt steer --model M.gguf --neuron "L10 E30 N1011" --dose=-1.5      # interactive
skrrt steer --model Qwen/Qwen3.5-4B --neuron "L14 N8949" --dose 1 --neuron "L13 N7956" --dose=-1

skrrt report

Rebuilds report.md and report.json from a finished run. It needs no model and generates nothing.

usage
skrrt report RUN_DIR

skrrt export-cvec

llama.cpp only: saves the push as a control-vector GGUF. See Serving a steered model.

usage
skrrt export-cvec --model M.gguf --neuron "L11 E14 N370" --dose DOSE -o FILE.gguf
                  [--persona PERSONA] [--backend-arg KEY=VALUE]
--model M.gguf
A .gguf file.
--neuron, --dose
As for steer; repeat the pair for several neurons.
-o FILE.gguf, --output FILE.gguf
Where to write the control vector.
--persona PERSONA
Measure the residual stream's typical size on this persona's training prompts.

The run directory

Each hunt writes to runs/<model>-<persona>/:

filewhat
run.jsonthe settings of the last invocation
rank.json, cos.npzstage 1: calibration, top neurons per layer, every cosine
screen.gen.jsonl, screen.judge.jsonlstage 2 raw rows: generations and judge results
screen.jsonstage 2 result: every screened neuron with its score
confirm.gen.jsonl, confirm.judge.jsonlstage 3 raw rows
confirm.jsonstage 3 result: finalists and controls
report.md, report.jsonstage 4

Resuming. Run the same skrrt hunt command again. A stage whose result exists and was made with the same settings is skipped. Inside a stage, generations and judge results already on disk are reused, so a crashed run picks up where it stopped.

Changing settings. A stage reruns by itself when its settings change: new doses, a different judge, another prompt set. You do not need --force for that. --force redoes everything regardless.

Environment

OPENROUTER_API_KEY
Used by the Jev judge and by write-replies --writer <model id>. Not needed with --judge self.
JEV_MODEL
Pins a Jev snapshot, for example typesafe/jev-1.14. Default: the latest.
cli.html