Claude Code Toolkit

A small, opinionated toolkit that turns Claude Code into a teammate that follows good engineering practices by default — instead of producing slop you have to clean up after.

Three layers:

Layer	When it runs	What it does
Hooks	Automatically, every tool call	Cheap deterministic guardrails — block edits to .env/keys/lockfiles, auto-format edited files, block rm -rf / and force-push to main, print a 3-line digest at session end
Skills	When you invoke them	/my-ship-it (pre-commit gate), /my-tidy (scoped cleanup), /my-council (5-advisor decision tool)
Subagents	Delegated by the main agent	my-code-reviewer (Opus), my-refactor-surgeon, my-test-writer — each role-locked with a restricted tool set

Everything is global — drops into ~/.claude/ once, works in every repo.

---

Install

git clone https://github.com/<you>/claude-code-toolkit.git
cd claude-code-toolkit
bash install.sh

The installer copies skills, agents, and hooks into ~/.claude/, appends the Code-Quality-Defaults block to ~/.claude/CLAUDE.md (if not already there), and registers the four hooks in ~/.claude/settings.json (creating it if missing). Existing files are backed up to ~/.claude/.toolkit-backup-<timestamp>/.

Restart Claude Code after install.

Requirements

• Claude Code (any recent version with hooks support).
• jq — brew install jq. Used by all four hooks to parse the tool-call payload.
• Optional formatters (auto-detected by post-edit-format.sh): prettier, ruff, black, gofmt, rustfmt, shfmt.

---

What you get

Skills

/my-ship-it — Pre-commit gate. Runs your project's lint + tests in parallel, sends the diff to my-code-reviewer, drafts a Conventional Commits message, hands you the exact git commit command. Never commits or pushes for you.

/my-ship-it

/my-tidy [path] — Scoped cleanup. Removes unused imports, unreferenced functions, dead branches, narration comments. Shows the diff first; only applies on apply confirmation; reverts if tests break. Refuses vague scope.

/my-tidy src/auth.py
/my-tidy src/

/my-council <question> — Five advisors (Contrarian, First Principles Thinker, Expansionist, Outsider, Executor) debate your decision in parallel. Their answers are anonymized and peer-reviewed by 5 more agents asking "what did all five miss?". You get a chairman verdict, an HTML report, and a markdown transcript under ./council/.

/my-council should I niche down or broaden? Context: ...

Use it for decisions where being wrong is expensive. Skip it for trivia.

Subagents

The main agent calls these — you usually don't invoke them directly.

• my-code-reviewer (Opus, no Edit/Write) — Reviews diffs against the Code-Quality-Defaults rubric. Returns Blockers / Smells / Nits with file:line cites and a verdict (APPROVE / REQUEST CHANGES / NEEDS DISCUSSION).
• my-refactor-surgeon (Sonnet) — Behavior-preserving refactors only. Runs tests before and after, pastes both outputs, reverts itself if anything fails.
• my-test-writer (Sonnet) — Characterization tests pinning current behavior. Auto-detects pytest / jest / vitest / go test / cargo test / rspec.

Hooks (silent guardrails)

Hook	Event	Job
pre-edit-guard.sh	PreToolUse (Edit/Write)	Blocks edits to .env*, *.pem, *.key, lockfiles. Override with CLAUDE_ALLOW_LOCKFILE_EDIT=1
post-edit-format.sh	PostToolUse (Edit/Write)	Runs prettier / ruff / black / gofmt / rustfmt / shfmt on the edited file if installed. Skips generated files
pre-bash-safety.sh	PreToolUse (Bash)	Blocks rm -rf /, rm -rf ~, fork bombs, --no-verify, force-push to protected branches, hard resets (override: CLAUDE_ALLOW_DESTRUCTIVE_GIT=1)
stop-summary.sh	Stop	Prints a 3-line digest at session end (files touched, +/-, new files) plus a code-map drift line if a graphify map exists

CLAUDE.md defaults

The installer appends a short Code quality defaults section to ~/.claude/CLAUDE.md. The skills and subagents reference it as the single source of truth. See docs/CLAUDE-snippet.md for the exact text.

---

How they work together

edit code  →  /my-ship-it  →  (lint+test in parallel)  →  my-code-reviewer  →  commit msg drafted
                                                            ↓ if untested
                                                         my-test-writer  →  my-refactor-surgeon

/my-tidy <path>  →  diff preview  →  apply  →  tests pass  →  done

/my-council <decision>  →  5 advisors in parallel  →  anonymized peer review  →  verdict + HTML report

Plus the four hooks always on in the background.

---

Uninstall

bash install.sh --uninstall

Removes the skills, agents, hooks, and the hook block from settings.json. The Code-Quality-Defaults block in CLAUDE.md stays — you can delete it manually if you want.

---

Customising

Everything is plain markdown and bash. Open the file, change the rules.

• Add formatters in hooks/post-edit-format.sh.
• Tighten or relax the protected-branch list in hooks/pre-bash-safety.sh.
• Change the reviewer's rubric in ~/.claude/CLAUDE.md after install.
• Bump or swap models in the subagents' frontmatter (model: opus ↔ sonnet).

---

License

MIT.