Claude Code configuration
My personal ~/.claude, version controlled: CLAUDE.md and rules/ for instructions, the words under CLAUDE.md → "Vocabulary"; .claude/rules/ for the rules that load in this repo alone; agents/ and skills/; principles/ and skills/larv-review/standards/ for what the reviewer agents hold projects to; docs/ for decisions and the comprehension history; settings.json for the harness and .claude/settings.json for the harness inside this repo; CHANGELOG.md and todo.md; the tools in bin/; workflow-bench/, the scripts and prompts of the 2026-09-30 bench of larv-review and of the 2026-11-12 bench of the advisor tool; reviewer-merge-trials/, the 2026-11-09 trials of merging reviewers, with their method, results and scripts; judge-field-trials/, the 2026-11-11 trials of which facts code could read in place of loop-claude's judge, with their results and scripts; stability-skip-count/, the 2026-11-12 count of archived stability rounds, with its script, from which larv-review took when to skip a stability round 2; and presentation/, a page that explains this setup to newcomers, with the script that prints it to PDF.
Goals
- Achieve: Get the highest quality out of Claude Code while interrupting me the least, so development scales.
- Signal: interrupts of me per finished chunk fall.
- Counter-signal: findings that a later change fixes, per finished chunk, rise.
- Why: fewer asks don't buy anything if the output gets worse.
- Achieve: Proven, stellar output quality: code, documentation and plans.
- Signal: 🔴 and 🟡 findings that review raises per chunk fall.
- Counter-signal: later changes that fix a chunk's code rise.
- Why: review findings show the first draft's quality, later fixes show what review missed.
- Achieve: Decide by the project's goals when confident; ask me when not, and never the same thing twice.
- Signal: asks that a goal or decision already settled fall to zero.
- Counter-signal: decisions I reverse rise.
- Why: guessing instead of asking saves an interrupt only if the guess holds.
- Maintain: The same workflow in every project and every session; each project's config supplies its premises, principles, plan and records.
- Achieve: Keep lowering cost, except where that would cut quality meaningfully.
- Signal: tokens per finished chunk fall.
- Counter-signal: reading cost, the new input tokens a chunk reads before its first commit, rises; or review rounds or unfinished verdicts per chunk rise.
- Why: a cheaper chunk that leaves the project harder to read moves the cost to every later chunk, whose changes need more reading and grow likelier to break what nobody saw; and a chunk that needs more rounds costs more.
- Achieve: Delivery speed.
- Signal: hours from a chunk's start to its merge fall.
- Counter-signal: 🔴 findings per chunk rise.
- Why: speed bought by skipping review shows up as defects.
- Achieve: Plug into a project without changing what its owners keep: its repo layout, tracker, wiki and conventions.
- Signal: the changes a project's owners must make before the loop runs in it fall.
- Counter-signal: defects where a backend loses or misreads a plan item, a premise or a record rise.
- Why: fitting in isn't worth anything if the loop then works from wrong facts.
- Maintain: Make my claude setup shareable between computers.
- Maintain: Keep my claude setup and the transcripts of unattended runs, the bench's included, backed up.
- Maintain: Don't leak anything: no credentials, transcripts or memory files to this repo's remote, and no client's code, transcripts or credentials to another client or to this repo.
Audience
Me, on my own machines and on those I use for the clients I consult for, which take tagged releases. Client teams read what the loop writes in their Jira, Confluence and pull requests, so it must read as written for them.
Install
Take this checkout only onto a machine that is a sandbox with no direct access to a production environment, such as a dedicated VM: settings.json runs Claude Code in auto mode with the dangerous-mode prompt skipped.
Each machine holds two checkouts. ~/.claude is the one Claude Code reads, and it holds only a release: deploy-release moves it from tag to tag. Develop in a clone under ~/code, where loop-claude runs this repo's chunks like any project's.
Claude Code may already have created ~/.claude, where git clone refuses to run, so make the repository in place, then clone it for development:
mkdir -p ~/.claude && cd ~/.claude
git init
git remote add origin ssh://git@gitea.larvit.se:21022/lilleman/claude-config.git
git fetch --tags origin
git checkout -f "$(git tag -l 'v*' --sort=-v:refname | head -n 1)"
git clone ssh://git@gitea.larvit.se:21022/lilleman/claude-config.git ~/code/claude-config
Have the latest stable Python, today 3.14, as python3 on PATH, and for Rust projects rust-analyzer on PATH, which the rust-analyzer-lsp plugin needs. Install every plugin settings.json enables:
claude plugin marketplace add anthropics/claude-plugins-official
claude plugin install claude-security@claude-plugins-official
claude plugin install code-review@claude-plugins-official
claude plugin install rust-analyzer-lsp@claude-plugins-official
Have git store settings.json without "model", so a model you pick with /model stays on this machine and never reaches a commit. Run this in each checkout, ~/.claude and ~/code/claude-config:
git config filter.settings.clean bin/settings_filter.py
Then pick a model with /model.
Link loop-claude onto PATH: ln -s ~/.claude/bin/loop-claude ~/.local/bin/loop-claude. Every claude it starts, the interactive ones included, skips every permission prompt.
To get loop-claude's questions and stops as Mattermost DMs from a bot, write the server, the bot's token and your username into ~/.claude-projects/<key>.env, in the keys ~/.claude/bin/mattermost-dm --help names, run chmod 600 on it, and add env-file = "~/.claude-projects/<key>.env" to the project's config, as Install → "Set up a project" describes. Without that setting, loop-claude sends no DM for the project; ~/.claude/.env is no longer read.
Set up a project
Each project the loop runs in has a folder, ~/.claude-projects/<key>/, where <key> is the project's name, and a config in it, config.toml. The folder is a git repo of its own, so the config has a history and a client's files never enter this repo. The loop commits each change it makes to a file there, such as the plan, in that repo, titled as its commits in the checkout. A project is a whole git checkout, never a subfolder of one.
The config names the project's main checkout and the path of every file the loop keeps for it. No setting has a default: project-config fails and names each setting a config leaves out. A path is checkout:<path> inside the checkout, folder:<path> inside the config's folder, or one that starts with / or ~/. Every tool reads and writes each file at the path its setting gives, and chunk-preflight and todo-item print those paths for the agents. Five of the settings name the project's records: decisions, score-anchors, comprehension-history, reading-cost and changelog. Keep each file's name, such as todo.md: the rules for a file load by its name. A project of your own keeps every file but the principles in its checkout:
checkout = "~/code/log"
plan = "checkout:todo.md"
working-rules = "checkout:AGENTS.md"
decisions = "checkout:docs/decisions.md"
score-anchors = "checkout:docs/score-anchors.md"
comprehension-history = "checkout:docs/comprehension-history.md"
reading-cost = "checkout:docs/reading-cost.md"
changelog = "checkout:CHANGELOG.md"
goals-and-audience = "checkout:README.md"
principles = "~/.claude/principles"
A project may also set env-file, the file of KEY=value credentials its tools read, such as env-file = "~/.claude-projects/log.env". It is a path that starts with / or ~/, outside the checkout and the config's folder, so that no git remote receives it. A tool that needs a key fails and names each one the file lacks. No failure message, prompt, log line or archived loop output holds a token from the file. rule-hook refuses a Read or a Grep of the file and a Bash command that names it or searches a folder holding it with ag, grep -r or rg, unless the tool skips the file as hidden or ignored, so a worker doesn't read it in passing; rule-hook --help says which calls it checks. A project without the setting has no credentials, and never reads another project's. project-config env-file prints the path.
For a client's project, use one sandbox VM per client, so that one client's code, transcripts and credentials never share a machine with another's. What the client's repo should not hold lives in the config's folder, at paths written as folder:<path>, as project-config --help shows: the plan, the working rules in an AGENTS.md I write for the agents, the records, and the goals and audience, as goals-and-audience = "folder:goals.md". Name that file goals.md, so the rules for goals and audience load when an agent writes it. A file outside the checkout has no commits in the checkout's history, so four things are not supported for it yet. score-outcomes and loop-claude's routing figures count a project's chunks only where todo.md, docs/comprehension-history.md and docs/reading-cost.md are at those paths in the checkout; otherwise each says so, and the loop goes on. For a plan or a comprehension history outside the checkout, larv-review says it cannot tell whether a scoring run is owed, and for such a history it cannot find a paired ruling's base. For a plan outside the checkout, chunk-preflight and loop-claude don't see a release whose last item has shipped, and say that its release review and its cut are yours to call. And rule-hook checks a plan outside the checkout on every call, not only when it changed.
mkdir -p ~/.claude-projects/acme && cd ~/.claude-projects/acme
git init
$EDITOR config.toml
git add config.toml && git commit -m "Add the config"
cd ~/code/acme-billing && ~/.claude/bin/project-config
The last line prints each setting's path once the config is complete.
Update
Move ~/.claude to the newest release:
~/code/claude-config/bin/deploy-release
It prints CHANGELOG.md's section for each version it moved past: do what each asks, such as a new step under Install. deploy-release --help says what else it checks.
It refuses while a file ~/.claude tracks has an uncommitted change, such as a hook Claude Code wrote into settings.json; a model picked with /model is no such change. Read the change first, as in git -C ~/.claude diff HEAD -- settings.json. When it holds a credential, such as a token in env or mcpServers, move that out of the file: a token in env to the shell profile, a server in mcpServers to ~/.claude.json with claude mcp add --scope user. Then carry the change into ~/code/claude-config on a branch of its own, merge it through a PR, and cut a release.
Release
Once the next release holds no item in todo.md and its release review has landed, cut it from ~/code/claude-config:
bin/deploy-release --cut
It renames ## Unreleased in CHANGELOG.md to the version and merges that through a pull request, since nobody can push to main. Then it tags the merged commit v<version>, pushes the tag, and moves this machine's ~/.claude to it. Where a step fails it stops with the reason, and a rerun continues where it stopped. deploy-release --help lists the steps. Each other machine takes the release with Update.
Tools
Install puts only loop-claude on PATH; call the others by their path, such as ~/.claude/bin/metric-bench, from the project's checkout. Those under ~/.claude are the release's; test a change to one from ~/code/claude-config/bin.
chunk-pr open|sync|ready|merge|cleanopens a chunk's pull request as a draft, brings its branch level with origin's default branch, marks it ready and merges it once its checks pass, withghon a GitHub origin andteaelsewhere; once it is merged,cleanremoves the chunk's worktree and branch and fast-forwards the main checkout.chunk-pr --helpstates the steps.chunk-preflightfinds the mechanical facts a chunk starts from, and with--worktreemakes its worktree;loop-clauderuns it with--worktreebefore it routes each chunk, andchunk-preflight --helplists the facts.command-patterns [<version>] [--calls <file>]prints a table of the shell command patterns a release's archived chunks ran, such astea pr create, for an audit of the release, and with--calls <file>saves each call as a JSON line;command-patterns --helpstates the columns and the line's keys.deploy-release [--cut] [<checkout>]moves~/.claude, or the checkout named, to the newest release, as Update says; with--cut, run in the development clone, it first cuts the next release, as Release says.judge-replay <model>replays loop-claude's judge on archived verdicts of the projects run on the model, and prints what each rung a review climbs to misses, and the lowest rung below them that, like each candidate above it, returns them;judge-replay --helpstates the replay.larv-review <command>holds larv-review's mechanical rules: the chunk's review folder, the paired ruling's base and vote count, each pass's round count, the scoring run's trigger and setup; the comprehension history's format, its latest places and its count of how often seats agree; and each reviewer's prompt header.larv-review --helpstates them.settings.json→hooksrunslarv-review reviewer-contextas each subagent starts. A reviewer underagents/whose frontmatter hasomitClaudeMd: truestarts withoutCLAUDE.md, and the command hands it that file's "Shared goal", "Prose" and "Vocabulary" sections.loop-claude <task>runs a project's next chunk cycle after cycle;loop-claude --helpstates its contract.mattermost-dm [<message>]sends a message, or else stdin, from the Mattermost bot to the human; the project'senv-filenames the server, the bot's token and the human, andmattermost-dm --helpnames its keys.loop-claude --helpsays when loop-claude sends one.metric-bench [history]benches cheap static metrics of a project's Python against the places its comprehension history names as hardest;metric-bench --helpstates the metrics and the scores.mutate-changes [--base <ref>] [--prefix <shell text>] [--jobs <n>]mutation-tests the lines a branch changes and prints each mutant its tests don't kill;mutate-changes --helpsays which tool it runs for each language.project-config [<setting>]prints the paths a project's config sets, or the one asked for, and fails naming each setting the config leaves out; Install → "Set up a project" shows a config.project-record open <record>prints the path of a file holding one of a project's records, for an agent to read and edit, andproject-record save <record>stores the edit; for a record kept as a file, that file is the record.rank_todo.py [--check] [todo.md]scores and ranks a project'stodo.md, by default the one its config names;rank_todo.py --helpstates the format.reading-cost [--reset] [record]appends a figure for each chunkloop-claudefinished to a project'sdocs/reading-cost.md, and says whether the figures rise;reading-cost --helpstates the measure.review-replay <pass> <model>replays a review pass's archived rounds from the projects run on the model, on the code each reviewed, and prints the lowest rung below the project's that, like each rung above it, qualifies: it finds no less of the 🔴 and 🟡 findings than two replays on the project's rung find, within a margin, and misses no 🔴 that both found.review-replay --helpstates the replay. With--omit-claude-mdit tests instead whether the pass's reviewer may start withoutCLAUDE.md: it replays each round three times as archived and once without the instruction files, and prints whether the reviewer passes: whether the last replay missed no more findings than the most an unchanged replay missed, with each count and each finding it missed. Each replayed reviewer skips every permission prompt, stability-reviewer has Bash, and an archived prompt may name paths on the host.rule-hook [overrides]blocks a tool call that breaks a rule a program can check, unless the call overrides the rule;settings.json→hooksruns it before each Agent, Bash, Edit, Grep, MultiEdit, Read, Skill and Write call, andrule-hook --helpstates the rules and the override.run-heavy <command>runs a heavy command once it holds one of the machine's heavy slots, one per 4 CPUs, which every session shares;run-heavy --helpstates the slots, and the memory cap it gives a container that sets no limit.run-tests [<pytest args>...]runs this repo's test suite, as Test says.score-outcomes [L E I S]shows what each finished item's chunk measured beside the scores the item was guessed at, to score a new item by. Per chunk it also shows code health's two counter-signals, misread findings and later fixes, and how many of the human's answers reversed a worker's choice;score-outcomes --helpstates the report.settings_filter.pyis git's clean filter forsettings.json: it drops"model"and sorts the keys..gitattributessets the filtersettingsonsettings.json, and Install'sgit configline makes this script that filter.statusline.pyrenders Claude Code's status line;settings.json→statusLineruns it.subagent-rung [--plan] <model> <L>prints the Agent tool's model and effort for a subagent's task, picked by its L from the project's model, and with--plannever below the project's rung;subagent-rung --helpstates the rule.todo-item add …files an item in a project'stodo.md, takingNext IDas the item's ID, andtodo-item finish <ID>removes a finished item and adds the bullet passed with--changelogtoCHANGELOG.md; both rank the file.todo-item show <ID>prints an item's row and detail.todo-item --helpstates the flags.wait-for <file> [<pattern>] [--timeout <seconds>]waits until a file a background job writes holds a line matching the pattern, and prints it.
bin/ is the import root: each launcher puts it on sys.path, so a module imports another by its path under bin/, such as from claude_code.entries import parse_entry. Each tool's package holds its tests. Beside the packages, bin/'s root holds only the launchers, the tools of one file with their tests, test_env.py, failure.py and setup.cfg. failure.py's Failure, which modules across bin/ return for a failed step, belongs to no single package. branch_chunks/, claude_code/, command_lines/, git_cli/, loop_effects/, loop_state/, machine_load/, mattermost_dm/, model_routing/, record_store/, release_plan/, review_rules/, rung_replay/, text_files/ and transcript_archive/ serve more than one tool.
branch_chunks/cuts a default branch into chunks and finds, for each, the items it shipped and the later chunks that fixed its code, forscore_outcomesandrouting_figures. It importsreading_cost's record path.command_lines/reads a shell command: its simple commands, and a docker call's subcommand and memory limits, forcommand_patterns,reading_cost,routing_figures,rule_hookandrun_heavy.chunk_primportsdeploy_release's forge calls, andforge_ofasdeploy_releasedoes.deploy_releaseimportschunk_preflight'sforge_of, which tells a GitHub origin from a Gitea one, andrelease_plan'srelease_standing.git_cli/runs git for every tool (git_repo.py), and reads the git calls in a shell command (git_command.py).judge_replayimportsloop_claude's judge, verdicts, premises and records.loop_clauderunschunk-preflightas a process of its own.loop_effects/holdsEffects: the processes, terminal, clock and git a tool reaches, injected so its tests can script them. loop-claude, both replay tools andreviewer-merge-trials' driver use it.loop_state/holds where loop-claude keeps its files (paths.py), whichrung_replayreads too.machine_load/takes the machine's heavy slots, its shared lock files, forrun_heavy, and reads the memory share that loop-claude waits for. It also givesmutate_changesa slot's CPU count.mattermost_dm/sends the human a Mattermost DM, formattermost-dmand for loop-claude throughloop_effects.model_routing/holds the routing ladder, which loop-claude,rule_hook, both replay tools andsubagent-rungread, and the list prices, whichrouting_figuresandtranscript_archiveread.rank_todo.py,settings_filter.pyandstatusline.pyare tools of one file each, tested beside them.record_store/reads and writes a project's records, each through the store the project's config names (stores.py).contract.pyholds the tests every backend must pass, andfakes.pya store in memory that the tests of other tools use.release_plan/readstodo.md's items table and release versions, says which release is next and whether it is ready to cut (release_standing.py), and ranks the plan (ranking.py, with its score formula informula.pyand its blocker order inblockers.py).goals_file.pyreads the goals file's sections, goals and goal weights, for the ranking and forloop_claude's premises, andcitations.pyholdstodo.mdanddocs/decisions.mdto each other.plan_file.pyreads, ranks, checks and writes atodo.md, forlarv_review,rank_todo.py,rule_hookandtodo_item.repo_checks/tests the repo itself.review_rules/holds the larv-review rules that several tools apply: its passes, its review folder, its round commit titles and the comprehension history's format.routing_figures/measures loop-claude's archive, and each of its projects' default branches, for loop-claude's routing calls.rung_replay/holds whatjudge_replayandreview_replayshare: the parallel replay runner, the argument reader, the candidate rungs and the exits, andjudge_replay's rung search. It readsloop_claude's retry count and models file, and finds that file throughloop_state's paths.test_env.pyserves the tests.text_files/reads a Markdown file's##sections, quotes a passage and joins names into a list, stamps times in UTC, and replaces a file in one step, private where it is new.transcript_archive/stores loop-claude's transcripts. Itsproject_key.pynames each project's archive folder, loop-claude session and models-file entry.
Test
Test on the host with bin/run-tests, which runs pytest through uvx, pinned in bin/run_tests/main.py. It prints each failing test with its error and pytest's summary line, and saves the whole output to a file whose path it prints. It passes on any test paths or pytest options it is given, such as bin/run-tests bin/chunk_pr -x. It needs uv on PATH, which fetches pytest, pytest-xdist and mypy. pytest-xdist runs the tests in one worker per CPU of a heavy slot (docs/decisions.md → bin/: the tools support only the latest stable Python, …). python3 -m unittest discover -s bin -p 'test_*.py' runs the same tests one at a time. Test the bench's scripts with python3 -m unittest discover -s workflow-bench -p 'test_*.py'.
CI runs ci.sh on every pull request, and main doesn't merge anything until it passes. The script runs the same tests on the committed HEAD in a pinned Python container; run it under run-heavy to reproduce a CI failure, with Docker on PATH.
To mutation-test the lines a branch changes, run ~/.claude/bin/run-heavy ~/.claude/bin/mutate-changes --prefix 'uvx --python "$(command -v python3)" --with pytest==9.2.0 --from "mutmut>=3,<4"' in its checkout.
Tracking a new file
.gitignore is an allowlist. Track a file by negating it and its parent directories, then confirm with git check-ignore -v <path>:
!docs/
!docs/*.md