Claude Code configuration
My personal ~/.claude, version controlled: CLAUDE.md, AGENTS.md and rules/ for instructions, the words under CLAUDE.md → "Vocabulary"; 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/; and workflow-bench/, the scripts and prompts of the 2026-09-30 bench of larv-review.
Goals
- Get the highest quality out of Claude Code while interrupting me the least, so development scales.
- Proven, stellar output quality: code, documentation and plans.
- Decide by the project's goals when confident; ask me when not, and never the same thing twice.
- The same rules in every project and every session.
- Add cost only where it meaningfully raises quality; otherwise work to lower cost.
- Delivery speed.
- Make my claude setup shareable between computers.
- Keep my claude setup and the transcripts of unattended runs, the bench's included, backed up.
- Leak nothing to the remote — no credentials, no transcripts, no memory files.
Audience
Me, on my own machines, which take tagged releases. Nobody else depends on it.
Install
Claude Code may already have created ~/.claude, where git clone refuses to run, so make the repository in place:
mkdir -p ~/.claude && cd ~/.claude
git init
git remote add origin ssh://git@gitea.larvit.se:21022/lilleman/claude-config.git
Then run Update's commands.
Have Python 3.11 or newer 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
Link loop-claude onto PATH: ln -s ~/.claude/bin/loop-claude ~/.local/bin/loop-claude. Run loop-claude only in a sandbox with no direct access to a production environment, such as a dedicated VM: every claude it starts, the interrupt included, skips every permission prompt.
Update
Move a machine that takes tagged releases to the latest tag. The move discards every uncommitted change to a file the latest tag tracks, such as a settings.json Claude Code wrote. List the uncommitted changes to files the checkout tracks, and the tag it is on:
cd ~/.claude
git fetch --tags origin
git status
To keep an uncommitted change, merge it per AGENTS.md → "Working rules" and cut a release ("Release") before moving: a machine gets only what a tag holds. Then move:
git checkout -f "$(git tag -l 'v*' --sort=-v:refname | head -n 1)"
Then do what CHANGELOG.md asks of each version since the old tag, such as a new step under Install.
Release
Rename ## Unreleased in CHANGELOG.md to the version, commit, tag that commit v<version>, and push both.
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.
judge-replay <model>replays loop-claude's judge on archived verdicts of the projects run on the model, and prints the lowest rung that, like each rung above it, returns them;judge-replay --helpstates the replay.larv-review <command>holds larv-review's mechanical rules: the paired ruling's base and vote count, each pass's round count, the scoring run's trigger, and the comprehension history's format and latest places;larv-review --helpstates them.loop-claude <task>runs a project's next chunk cycle after cycle;loop-claude --helpstates its contract.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.rank_todo.py [--check] [todo.md]scores and ranks a project'stodo.md;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.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 Bash, Edit, MultiEdit and Write call, andrule-hook --helpstates the rules and the override.score-outcomes [R S C]lists the finished items whose guessed R, S and C sit nearest the given scores, with what their chunks measured, and each score's median outcome;score-outcomes --helpstates the measures.stability-replay <model>replays archived stability reviews of 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, finds every 🔴 and 🟡 the project's rung finds again;stability-replay --helpstates the replay. Run it only in a sandbox, like loop-claude: each replayed reviewer has Bash and skips every permission prompt, and an archived prompt may name paths on the host.statusline.pyrenders Claude Code's status line;settings.json→statusLineruns it.subagent-rung [--plan] <model> <R+C>prints the Agent tool's model and effort for a subagent's task, picked by its R + C from the project's model, and with--plannever below the project's rung;subagent-rung --helpstates the rule.
Test on the host, with uv on PATH to fetch mypy and the Python version Install names (docs/decisions.md → bin/): python3 -m unittest discover -s bin -p 'test_*.py'
To mutation-test a changed module, copy bin/ to a scratch directory (cp -r bin "$scratch"): mutmut writes files beside its config. In the copy, name the module and its tests in a setup.cfg, as below for score_outcomes/outcomes.py. Leave out each test class that starts a tool's launcher through subprocess: a mutated module fails to load in a process mutmut did not start.
[mutmut]
source_paths=score_outcomes/outcomes.py
also_copy=.
pytest_add_cli_args_test_selection=score_outcomes/
pytest_add_cli_args=-k
not ScoreOutcomesTool
Then, in the copy: uvx --with pytest 'mutmut>=3,<4' run && uvx --with pytest 'mutmut>=3,<4' results, and uvx --with pytest 'mutmut>=3,<4' show <mutant> to see a mutant's change. The config keys are mutmut 3's.
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; rank_todo.py and statusline.py are tools of one file each, tested beside them, rule_hook imports rank_todo.py's check, score_outcomes imports reading_cost's record path, judge_replay imports loop_claude's judge. judge_replay and stability_replay share rung_replay/: the rung search, and the argument, candidate rungs and exits. It reads loop_claude's retry count and models file. The other non-test modules at bin/'s root, claude_code/ and transcript_archive/ serve more than one tool; model_routing/ holds the routing ladder, which loop-claude and subagent-rung read. routing_figures/ measures loop-claude's archive for loop-claude's routing calls. test_env.py serves the tests, and repo_checks/ tests the repo itself.
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