Files
claude-config/README.md
T

16 KiB

Claude Code configuration

My personal ~/.claude, version controlled: CLAUDE.md and rules/ for instructions, the words under CLAUDE.md → "Vocabulary"; .claude/rules/ for the working rules of 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; reviewer-merge-trials/, the 2026-11-09 trials of merging reviewers, with their method, results and scripts; and presentation/, a page that explains this setup to newcomers, with the script that prints it to PDF.

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: 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.
    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

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 and loop-inbox onto PATH: ln -s ~/.claude/bin/loop-claude ~/.local/bin/loop-claude and ln -s ~/.claude/bin/loop-inbox ~/.local/bin/loop-inbox. Every claude they start, the interactive ones included, skips every permission prompt.

Update

Move ~/.claude to the newest release:

~/code/claude-config/bin/deploy-release

It refuses while a file ~/.claude tracks has an uncommitted change, such as a hook Claude Code wrote into settings.json. Merge that into ~/code/claude-config on a branch of its own, through a PR, then cut a release. A model picked with /model is no such change.

For ~/.claude/settings.json, which Claude Code writes from any session, read the diff first: git -C ~/.claude diff HEAD -- settings.json. An empty diff means only the model or the key order changed, which deploy-release takes as no change. When the diff holds a credential, such as a token in env or mcpServers, move it out of the file, and commit only once it is gone: a token in env moves to the shell profile, and a server in mcpServers moves to ~/.claude.json with claude mcp add --scope user.

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.

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 and loop-inbox 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|ready|merge|clean opens a chunk's pull request as a draft, marks it ready and merges it, with gh on a GitHub origin and tea elsewhere; once it is merged, clean removes the chunk's worktree and branch and fast-forwards the main checkout. chunk-pr --help states the steps.
  • chunk-preflight finds the mechanical facts a chunk starts from, and with --worktree makes its worktree; loop-claude runs it with --worktree before it routes each chunk, and chunk-preflight --help lists the facts.
  • command-patterns [<version>] prints a table of the shell command patterns a release's archived chunks ran, such as tea pr create, for an audit of the release; command-patterns --help states its columns.
  • 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 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; the comprehension history's format, its latest places and its count of how often seats agree; and each reviewer's prompt header. larv-review --help states them.
  • loop-claude <task> runs a project's next chunk cycle after cycle; loop-claude --help states its contract.
  • loop-inbox shows the interrupts of every loop-claude on the machine, oldest first, takes each one's answer, /talk included, and lists every running loop with the todo.md items its chunk takes; loop-inbox --help states how.
  • 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. 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 Agent, Bash, Edit, MultiEdit, Read, Skill and Write call, and rule-hook --help states 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 --help states the slots, and the memory cap it gives a container that sets no limit.
  • 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, and code health's two counter-signals per chunk, misread findings and later fixes; score-outcomes --help states the report.
  • 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.
  • todo-item add … files an item in a project's todo.md, taking Next ID as the item's ID, and todo-item finish <ID> removes a finished item and adds the bullet passed with --changelog to CHANGELOG.md; both rank the file, and todo-item --help states the flags.

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 and failure.py. 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/, model_routing/, records/, release_plan/, review_rules/, rung_replay/ 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, for score_outcomes and routing_figures. It imports reading_cost's record path.
  • command_lines/ reads a shell command: its simple commands, and a docker call's subcommand and memory limits, for command_patterns, reading_cost, routing_figures, rule_hook and run_heavy.
  • chunk_pr imports deploy_release's forge calls, and forge_of as deploy_release does.
  • deploy_release imports chunk_preflight's forge_of, which tells a GitHub origin from a Gitea one, and release_plan's release_standing.
  • git_cli/ runs git for every tool (git_repo.py), and reads the git calls in a shell command (git_command.py).
  • judge_replay imports loop_claude's judge, verdicts, premises and records.
  • loop_claude runs chunk-preflight as a process of its own.
  • loop_effects/ holds Effects: the processes, terminal, clock and git a tool reaches, injected so its tests can script them. loop-claude, loop-inbox, both replay tools and reviewer-merge-trials' driver use it.
  • loop_state/ holds the files loop-claude and loop-inbox share: the question files (waiting/), the files a running loop lists itself in (running_loops.py, session_lock.py), their paths, and hand_over.py, which opens claude for /talk. A change to any of them changes both tools.
  • machine_load/ takes the machine's heavy slots, its shared lock files, for run_heavy, and reads the memory share that loop-claude waits for.
  • model_routing/ holds the routing ladder, which loop-claude, rule_hook, both replay tools and subagent-rung read.
  • rank_todo.py, settings_filter.py and statusline.py are tools of one file each, tested beside them.
  • records/ 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.
  • release_plan/ reads todo.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 in formula.py and its blocker order in blockers.py). plan_file.py reads, ranks, checks and writes a todo.md, for larv_review, rank_todo.py, rule_hook and todo_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 what judge_replay and review_replay share: the rung search, the argument reader, the candidate rungs and the exits. It reads loop_claude's retry count and models file, and finds that file through loop_state's paths.
  • test_env.py serves the tests.
  • transcript_archive/ stores loop-claude's transcripts. Its project_key.py names each project's archive folder, loop-claude session and models-file entry.

Test

Test on the host with uvx --python "$(command -v python3)" --with pytest-xdist==3.8.0 pytest==9.2.0 -n 4 bin. It needs uv on PATH, which fetches pytest, pytest-xdist and mypy. pytest-xdist runs the tests in four workers, one heavy slot's CPUs (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 merges nothing 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 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/results.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/results.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==9.2.0 'mutmut>=3,<4' run && uvx --with pytest==9.2.0 'mutmut>=3,<4' results, and uvx --with pytest==9.2.0 'mutmut>=3,<4' show <mutant> to see a mutant's change. The config keys are mutmut 3's.

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