2026-09-30 17:02:47 +02:00
2026-10-14 22:22:03 +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. Get the highest quality out of Claude Code while interrupting me the least, so development scales.
    1. Proven, stellar output quality: code, documentation and plans.
    2. Decide by the project's goals when confident; ask me when not, and never the same thing twice.
    3. The same rules in every project and every session.
    4. Add cost only where it meaningfully raises quality; otherwise work to lower cost.
    5. Delivery speed.
  2. Make my claude setup shareable between computers.
  3. Keep my claude setup and the transcripts of unattended runs, the bench's included, backed up.
  4. 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.

  • 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 --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.
  • 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 and Write call, and rule-hook --help states 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 --help states the measures.
  • statusline.py renders Claude Code's status line; settings.json → statusLine runs it.

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, and score_outcomes imports reading_cost's record path. The other non-test modules at bin/'s root, claude_code/ and transcript_archive/ serve more than one tool. 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%