2026-09-30 17:02:47 +02:00
2026-10-22 00:27:19 +02:00

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

  1. 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 buy nothing if the output gets worse.
    1. 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.
    2. 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.
    3. Maintain: The same rules in every project and every session.
    4. Achieve: Add cost only where it meaningfully raises quality; otherwise work to lower cost.
      • Signal: tokens per finished chunk fall.
      • Counter-signal: review rounds or unfinished verdicts per chunk rise.
      • Why: a cheaper run that needs more rounds costs more.
    5. 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.
  2. Maintain: Make my claude setup shareable between computers.
  3. Maintain: Keep my claude setup and the transcripts of unattended runs, the bench's included, backed up.
  4. Maintain: 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, skipping git add settings.json: the new repository tracks no file yet.

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

Have git store settings.json without "model", so a model you pick with /model stays on this machine and never reaches a commit:

git config filter.settings.clean bin/settings_filter.py

Then pick a model with /model.

After a pick, git status may list settings.json, and a git pull that changes the file refuses to run. git add settings.json stages no change and clears both. Once it is staged, such a pull goes through and drops the model: pick it again.

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 interactive ones 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 hook Claude Code wrote into settings.json. Git counts a model pick as such a change until git add settings.json, so stage it first. List the uncommitted changes to files the checkout tracks, and the tag it is on:

cd ~/.claude
git add settings.json
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, where the tag changed settings.json, pick the model again with /model, and 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.

  • chunk-preflight finds the mechanical facts a chunk starts from and makes its worktree; loop-claude runs it before it routes each chunk, and chunk-preflight --help lists the facts.
  • 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 --help states 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 the comprehension history's format and latest places, and its count of how often seats agree; larv-review --help states them.
  • loop-claude <task> runs a project's next chunk cycle after cycle; loop-claude --help states 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 --help states the metrics and the scores.
  • rank_todo.py [--check] [todo.md] scores and ranks a project's todo.md; rank_todo.py --help states the format.
  • reading-cost [--reset] [record] appends a figure for each chunk loop-claude finished to a project's docs/reading-cost.md, and says whether the figures rise; reading-cost --help states 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, finds every 🔴 and 🟡 the project's rung finds again; review-replay --help states the replay. Run it only in a sandbox, like loop-claude: 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 → hooks runs it before each Bash, Edit, MultiEdit, Write and Agent call, and rule-hook --help states the rules and the override.
  • score-outcomes [L E I S] lists the finished items whose guessed scores sit nearest the given ones, and the shipped items the project's docs/score-anchors.md names for each level of L, E and I, each with what its chunk measured; then the median outcome at each guessed R and S, and how well L, E and I each order the chunks by review rounds and 🔴 findings; score-outcomes --help states the measures.
  • settings_filter.py is git's clean filter for settings.json: it drops "model" and sorts the keys. .gitattributes sets the filter settings on settings.json, and Install's git config line makes this script that filter.
  • statusline.py renders Claude Code's status line; settings.json → statusLine runs 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 --plan never below the project's rung; subagent-rung --help states 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'. Test the bench's git wrapper with python3 -m unittest discover -s workflow-bench -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, settings_filter.py and statusline.py are tools of one file each, tested beside them, rule_hook imports rank_todo.py's check, larv_review imports rank_todo.py's ranking, score_outcomes imports reading_cost's record path, judge_replay imports loop_claude's judge, and loop_claude runs chunk-preflight as a process of its own. judge_replay and review_replay share rung_replay/: the rung search, the argument reader, the candidate rungs and the exits. rung_replay/ 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, rule_hook, both replay tools 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
S
Description
Authored half of ~/.claude: instructions, agents, skills, principles, settings
Readme 53 MiB
Languages
Python 97.6%
HTML 2.3%