run-claude-code-config
/run-claude-code-config
Run, launch, drive, smoke-test, or verify this claude-code-config repo — fire its hook scripts with real payloads, run the generator and validation gates, and test the global/project installers in a sandbox. Use when asked to run the app, check a change works for real, exercise a hook, or verify an install.
- Author
- edjchapman ↗
- Repository
- claude-code-config ↗
- Licence
- MIT
- Last repository change
- 23.10.2026
Assessment and security
- Files in this package
- 2
- Scripts
- 1
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 23.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
- 1 scripts in this package. Review them before installing, as Claude may execute them.
Scripts: drive.sh
What it does and when to use it
Run, launch, drive, smoke-test, or verify this claude-code-config repo — fire its hook scripts with real payloads, run the generator and validation gates, and test the global/project installers in a sandbox. Use when asked to run the app, check a change works for real, exercise a hook, or verify an install.
Original author description
Run, launch, drive, smoke-test, or verify this claude-code-config repo — fire its hook scripts with real payloads, run the generator and validation gates, and test the global/project installers in a sandbox. Use when asked to run the app, check a change works for real, exercise a hook, or verify an install.
How it works
- Prerequisites
- Run (agent path) — start here
- Run (human path)
- Test
- Gotchas
- Troubleshooting
SKILL.md preview
---
name: run-claude-code-config
description: Run, launch, drive, smoke-test, or verify this claude-code-config repo — fire its hook scripts with real payloads, run the generator and validation gates, and test the global/project installers in a sandbox. Use when asked to run the app, check a change works for real, exercise a hook, or verify an install.
---
# 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.
```bash
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
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
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:
```bash
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
```bash
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.
```bash
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:
```bash
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
| Symptom | Cause / fix |
| --- | --- |
| `PreToolUse:Bash hook error: BLOCKED: dangerous command pattern detected` while testing | Gotcha 1 — your test fixture tripped the live hook. Assemble the string from pieces, or put it in a file written by a non-Bash tool. |
| `drive.sh hooks` → `FAIL file not reformatted — is ruff on PATH?` | `ruff` missing. `command -v ruff`; it lives at `~/.local/bin/ruff` here. The hook also accepts a `.venv/bin/ruff` at the git root. |
| `shellcheck` clean by hand but pre-commit fails | You ran bare `shellcheck`. The gate is `--severity=warning`. |
| `sed: can't read s\|...\|: No such file or directory` | BSD `sed -i ''` arg parsing under zsh. Use `perl -pi -e 's{a}{b}g' file`. |
| `generate.py --check` exits 1 naming a stale file | Run `python3 scripts/generate.py` (no `--check`) to rewrite, then re-check. |
| A hook "does nothing" and exits 0 | Expected for most hooks on an unmatched payload — they read a specific dotted key (e.g. `tool_input.file_path`) and exit 0 when it's absent. Confirm your payload shape against the hook's header comment. |
| Real `~/.claude` changed after a test run | You ran an installer directly instead of `drive.sh install`. Compare with `ls -la ~/.claude \| md5`. |
Files in this package (2)
- SKILL.md 9 KB
- drive.sh 11 KB
Versions
The database has no other skills named run-claude-code-config.
Database snapshot: 13.11.2026 · package version 52d262d78e90 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100run-claude-dev-env
Build, install, run, and test the claude-dev-env installer. Use when asked to run claude-dev-env, install the Claude Code config into ~/.claude, drive the installer, smoke-test it against a sandbox, or run its test suite. - 100run-cq
Build, run, test, and smoke-drive cq — the SQL-over-Claude-Code-transcripts CLI (Rust + DuckDB). Use when asked to build cq, run it, try a subcommand, verify a change works end-to-end, or run its tests. - 100verify
Drive the oldwinter/skills library end to end: run the repo gates, install a named skill from this working tree with the real skills CLI into an isolated workspace, and prove the installed bundle, lock file, and discovery output. Use when a change touches a SKILL.md, the README… - 100self-verify-beacon-in-sandbox
Verify a Beacon change end to end by running a real Claude Code session inside a disposable Linux cloud sandbox and checking that Beacon captured what the agent actually did. Use when asked to verify, validate, test, or prove that a Beacon change works for real rather than just… - 100nvim-install
Install Neovim and stand up the nvim-fredrik config in the Claude Code web sandbox (the cloud environment), where no Neovim exists. Use this before testing any Neovim config change in a web session, e.g. checking out a PR branch that touches nvim-fredrik and observing its… - 100setup-issue-loop
Install issue-loop into a target repository, collect and validate its config, check the tracker, intake, runner, and app-control skill, hand off the two automations, and run the thread-safety test. Use for first install or any config change.