Run claude-code-config

This repo has no server, no GUI, and no build step. Its "running app" is three surfaces:

1. The hook scripts in scripts/hooks/ — the harness executes these at runtime with a JSON payload on stdin; exit 0 = allow, exit 2 = block, and the block reason must go to stderr.
2. The generator CLI, scripts/generate.py, which owns the generated regions in README.md, docs/architecture.md, and settings.json.
3. The installers, scripts/setup-global.sh and scripts/setup-project.sh.

All three are driven by one script: .claude/skills/run-claude-code-config/drive.sh.

Paths below are relative to the repo root.

Prerequisites

Already present on a normal dev box; the driver skips or fails loudly if not.

python3 --version        # 3.14.7 here; generate.py + the hook JSON parser need it
bash --version           # 5.3.15 (macOS ships bash 3.2 — hooks run under `bash`, not `sh`)
ruff --version           # 0.16.1 — format-on-edit.sh shells out to it
shellcheck --version     # pre-commit runs it at --severity=warning
pre-commit --version

There is no npm install and no node_modules/ in this repo.

Run (agent path) — start here

The driver runs everything under a throwaway HOME, because four hooks write into $HOME/.claude/ and the installers symlink into it. A driver run can never mutate your real config.

bash .claude/skills/run-claude-code-config/drive.sh check     # the 3 validation gates
bash .claude/skills/run-claude-code-config/drive.sh hooks     # fire all 10 hooks, assert exits + side effects
bash .claude/skills/run-claude-code-config/drive.sh install   # sandboxed setup-global.sh + setup-project.sh
bash .claude/skills/run-claude-code-config/drive.sh all       # all of the above

A clean all run reports:

== Summary
  pass=32 fail=0 skip=1

The one skip is notify-attention.sh (fires a real desktop banner). Opt in with DRIVE_NOTIFY=1. Add DRIVE_KEEP=1 to keep the sandbox directory and inspect what the hooks wrote.

Direct invocation — fire one hook

Most PRs here touch a single hook or a single generator target. To poke one hook in isolation, with its output and exit code shown and HOME still sandboxed:

bash .claude/skills/run-claude-code-config/drive.sh hook settings-drift-check.sh '{"source":"startup"}'
bash .claude/skills/run-claude-code-config/drive.sh hook format-on-edit.sh '{"tool_input":{"file_path":"/tmp/x.py"}}'

Or call a hook directly — the contract is just JSON on stdin:

printf '{"tool_name":"Bash","tool_input":{"command":"ls -la"}}' | bash scripts/hooks/dangerous-cmd-check.sh; echo "exit=$?"

Read Gotcha 1 before you try that with an actually-dangerous command.

Generator, one target at a time

python3 scripts/generate.py --check              # verify only; exit 1 if stale
python3 scripts/generate.py                      # rewrite stale destinations
python3 scripts/generate.py --only readme         # single target: architecture | readme | settings-hooks
python3 scripts/generate.py --root /path/to/copy # operate on a scratch copy

Run (human path)

Installing the config for real — these write to your actual ~/.claude, so don't run them just to "check it works"; that's what drive.sh install is for.

scripts/setup-global.sh          # symlinks agents/ skills/ rules/ into ~/.claude, mirrors settings.json
scripts/setup-project.sh python  # per-project .claude/ in the CWD

Or as a plugin: /plugin marketplace add edjchapman/claude-code-config, then /plugin install claude-code-config.

Test

The three gates CI runs, in order of speed:

python3 scripts/generate.py --check       # ~1s
python3 -m unittest discover -s tests     # 40 tests, ~3s
pre-commit run --all-files                # 19 checks, ~40s

Gotchas

1. This repo's own hook blocks your attempt to test it. If the config is installed in your session, dangerous-cmd-check.sh is live — and it inspects the command string of every Bash call, including one that merely carries a dangerous pattern as test data. Putting a literal root-wipe inside a JSON payload on a Bash command line gets the whole tool call killed before it runs, with PreToolUse:Bash hook error: BLOCKED: dangerous command pattern detected. The fix, which drive.sh uses: assemble the fixture from pieces (printf 'rm -r%s /' 'f') so the literal never appears contiguously in any command line. Same reason the driver was created with the Write tool rather than a Bash heredoc.
2. Four hooks write into $HOME/.claude/ — always sandbox HOME. log-tool-failure.sh → logs/tool-failures.jsonl, pre-compact-state.sh → cache/, post-compact-restore.sh reads and deletes from cache/, session-end.sh → debug/session-log.csv. Running these bare pollutes your real logs. HOME=$(mktemp -d) is enough; tilde expansion follows $HOME, so even setup-global.sh lands entirely in the sandbox.
3. A naive sandbox makes settings-drift-check.sh a false pass. It begins [ -L ~/.claude/agents ] || exit 0 — global-mode detection. In an empty sandbox it exits 0 immediately without running any logic. drive.sh plants a .claude/agents symlink and a settings.json copy in the sandbox so the hook actually executes.
4. prettier is not installed and there is no node_modules/. So format-on-edit.sh silently no-ops on .md, .json, .ts, .css — it only really formats .py, via ruff. This is easy to misread as "the hook is broken", and easy to miss because pre-commit's prettier check does pass: pre-commit vendors its own prettier in an isolated env that the hook cannot see.
5. shellcheck runs at --severity=warning. SC2088 (tilde inside a quoted string) fails the gate; SC2015 (A && B || C) is info and is filtered out. Any new shell script — including this driver — must pass. Check with shellcheck --severity=warning <file>, not bare shellcheck.
6. PreCompact and PostCompact are a stateful pair keyed by session_id. pre-compact-state.sh writes ~/.claude/cache/precompact-<id>.md; post-compact-restore.sh prints it and then removes it. Running restore twice is a silent no-op with exit 0 — not a bug. Fire them in order with a matching session_id or you're testing nothing.
7. hooks/hooks.json is the source of truth; the hooks key in settings.json is generated (ADR-0001). Hand-editing settings.json gets reverted by pre-commit and fails generate.py --check in CI. Edit hooks/hooks.json.
8. The login shell is zsh, but the scripts are bash. Two traps this causes when driving things by hand: PIPESTATUS is bash-only (zsh spells it pipestatus, so echo "EXIT=${PIPESTATUS[0]}" prints empty), and an unmatched glob like .claude/skills/*/SKILL.md is a hard error in zsh rather than passing through — probe with find instead.
9. .claude/ is in .prettierignore and skills/*/SKILL.md is what the generator globs. So this skill is neither reflowed by prettier nor picked up by the README/architecture catalogs — adding it needs no regeneration. It is still linted by markdownlint.

Troubleshooting