A drop-in Claude Code configuration for any project. One repo, any stack. Production-level orchestration, token-optimized, customizable per project through a layered setup wizard.
The toolkit turns Claude Code from a general-purpose assistant into a project-aware system that:
- Knows your stack, commands, and conventions
- Spawns the right specialist agents only when paths need them
- Enforces safety guardrails and auto-formatting invisibly
- Stays within a per-review token budget so you don't exhaust your plan
- Adapts to how you want to work (three presets, three autonomy levels)
- Idea of the repo
- Quick start
- Architecture
- The setup wizard
- Presets
- Autonomy levels
- Orchestrator
- Agents
- Skills (slash commands)
- Hooks
- Path-scoped rules
- Token optimization
- Customization
- Typical workflows
- Self-improvement loop
Claude Code is powerful, but out of the box it has no memory of your project, no specialists, no safety nets, and no way to route work. You repeat yourself every session ("use 2 spaces", "run pytest not jest", "don't delete that"), review is ad-hoc, tokens are burned on repeated context, and hooks / agents stay dormant because nothing orchestrates them.
This toolkit fixes all of that with one drop-in directory and a setup wizard.
After /init, your project has:
- A CLAUDE.md that Claude reads on every session (commands, conventions, architecture)
- Specialist agents that get spawned automatically when paths need them
- Hooks that auto-format, block dangerous commands, and route requests invisibly
- Path-scoped rules that load only when you edit matching files
- A tunable budget so reviews never blow through your token plan
It is stack-agnostic. Agents never hardcode commands or frameworks — they read CLAUDE.md. The same code-reviewer works for TypeScript, Python, Go, Rust, or SQL. When your stack changes, you regenerate config from reality (/reconfigure).
# 1. Clone the toolkit
git clone https://github.com/elgarra/claude-code-toolkit.git
# 2. Copy the toolkit directories into your project's .claude/
mkdir -p your-project/.claude
cp -r claude-code-toolkit/agents your-project/.claude/agents
cp -r claude-code-toolkit/skills your-project/.claude/skills
cp -r claude-code-toolkit/hooks your-project/.claude/hooks
cp -r claude-code-toolkit/templates your-project/.claude/templates
cp claude-code-toolkit/agent-base.md your-project/.claude/agent-base.md
cp claude-code-toolkit/AGENTS.md your-project/AGENTS.md
# 3. Open Claude Code inside your project and run:
/init/init scans your stack, shows a summary, and asks a few questions (preset, autonomy, extras). It generates a tailored CLAUDE.md, settings.json, path-scoped rules, and copies only the agents/skills you enabled.
git clone https://github.com/elgarra/claude-code-toolkit.git
# In Claude Code, inside the toolkit dir:
/create fastapi my-api/create scaffolds the project (source, tests, Docker, CI), writes .scaffold-meta.json so /init skips detection, then invokes /init and asks only the high-signal questions.
Stacks: typescript-node, fastapi, django, dbt, airflow, pyspark.
Always loaded ──── CLAUDE.md ─────────────── Project conventions, commands, architecture (~80 lines)
│
Only when matching ─ .claude/rules/ ───────── Path-scoped (load only when editing matching files)
│
Invisible ────────── .claude/hooks/ ────────── Auto-format, pre-bash guardrails, orchestrator
│
You invoke ───────── .claude/skills/ ───────── /self-heal, /review-changes, /research, /reconfigure
│
Spawned on demand ── .claude/agents/ ───────── Specialist workers; each reads agent-base.md first
│
Coordination ─────── AGENTS.md ──────────────── When and how agents are spawned
│
Shared rules ──────── agent-base.md ─────────── Authority, output format, discipline (one file, 16 agents reuse)
│
Config ────────────── .claude/settings.json ── Preset, autonomy, enabled agents, triggers, hooks wiring
Session start: Claude reads CLAUDE.md automatically. It knows your test command, architecture, and conventions. No prompting needed.
File edit: The post-edit hook auto-formats. If the file matches a path rule, that rule's conventions load into context. If the path matches an orchestrator trigger, the user-prompt-submit hook injects a hint suggesting relevant review agents on the next message.
/review-changes: Reads your preset, builds the agent panel (base + triggered), estimates token cost, degrades if over budget, spawns agents in parallel, synthesizes findings.
/self-heal: Runs tests → reads failures → minimal fix → retests. Max 3 attempts, then escalates with a diagnosis.
/init uses a layered wizard — you see a summary and can accept defaults or customize. It never bombs you with 15 questions upfront.
Step 1: DETECT — scan for build files, frameworks, data tools
Step 2: SHOW SUMMARY — "I detected X, Y, Z. Is this correct? [y/c/e]"
y → accept defaults (balanced preset, medium autonomy) and generate
c → customize through 8 sections
e → edit detection (fix a mis-detected field)
Step 3 (customize path): 8 sections
1. Preset — quality-first / balanced / budget-first
2. Autonomy — high / medium / low
3. Auto-review — on every edit / only /review-changes / critical paths only
4. Agents — toggle each of 16, defaults per preset
5. Skills — toggle each, defaults per stack
6. Hooks — format on/off, guardrails strict/loose/off, orchestrator on/off
7. CLAUDE.md content — non-obvious commands, conventions, don't-touch
8. Orchestrator — classification mode, activation, budget, triggers
Step 4: GENERATE — CLAUDE.md, settings.json, enabled agents/skills, hooks, path rules
Step 5: SMOKE TEST — run detected test command once
Step 6: NEXT STEPS — short list of first commands to try
/init is one-shot. Once you're configured, use /reconfigure to change any single section. It never re-detects your stack, never overwrites CLAUDE.md edits you made manually, and handles cascading changes (e.g. switching autonomy to high auto-switches orchestrator activation to auto-spawn).
Presets are ready-made defaults for the agent panel, models, and triggers. You pick one at /init; it becomes toolkit.preset in settings.
| Preset | /review-changes base |
Model mix | Best for |
|---|---|---|---|
| quality-first | code + test + security + performance (4) | Sonnet on all review agents | PRs to prod, critical code |
| balanced (default) | code + test (2) + triggers | Sonnet on subtle logic, Haiku on mechanical | Day-to-day |
| budget-first | code + test (2), minimal triggers | Haiku where viable, Sonnet only on security/data | Side projects, limited budget |
Regardless of preset, path triggers add more agents when needed (e.g. editing auth/ always pulls in security-reviewer). Use /review-changes --deep to spawn the full panel on demand.
Autonomy decides how proactive Claude is between your messages. Chosen at /init or via /reconfigure.
| Level | Hooks | Review | Destructive | Edits |
|---|---|---|---|---|
| high | format + guardrails | auto-spawn after edits | confirms | edits without confirming |
| medium (default) | format + guardrails | suggests agents | confirms | proposes plan, then edits |
| low | format only | manual-only | blocks | asks before every edit |
Autonomy is orthogonal to preset — you can have quality-first + low (deep reviews, zero autonomy) or budget-first + high (minimal reviews, full autonomy).
The orchestrator decides when to spawn which agent. It is two layers:
Runs before every user message. Reads recently edited paths (from the transcript) and compares them to toolkit.orchestrator.triggers. Matching triggers inject a short hint into the next message:
## Orchestrator hint
Suggested review agents (user will confirm before you spawn):
- security-reviewer
- performance-reviewer
Triggered by:
- security-on-api (matched src/api/login.ts)
The hook respects autonomy:
high+auto-spawn: the hint tells Claude to spawn after completing the task.medium+suggest: the hint is advisory; Claude asks before spawning.low+manual-only: the hook does nothing.
Reads preset + triggers, builds the panel, checks budget, spawns in parallel. Use --deep to force the full panel. Use --paths <glob> to scope.
| Trigger | Paths | Agents |
|---|---|---|
security-on-auth |
auth/**, security/**, *password*, *secret* |
security-reviewer |
security-on-api |
api/**, routes/**, controllers/** |
security-reviewer, performance-reviewer |
data-on-sql |
*.sql, models/**, dbt/** |
data-reviewer |
pipeline-on-dag |
dags/**, pipelines/**, flows/** |
pipeline-reviewer |
schema-on-migration |
migrations/**, schema/** |
schema-auditor |
devx-on-config |
package.json, pyproject.toml, Dockerfile, .github/workflows/** |
devx-auditor |
ux-on-frontend |
*.tsx, *.jsx, components/**, pages/** |
ux-reviewer |
Edit these at any time with /reconfigure orchestrator.
16 agents total. Each one:
- Is 40-60 lines (slim, domain-specific scope only)
- References
agent-base.mdfor shared rules (authority, output format, discipline) - Is read-only by default (only
evaluator-optimizercan edit) - Has a turn budget (8-25) to prevent token blow-ups
| Agent | Purpose | Turns |
|---|---|---|
code-reviewer |
rule compliance, edge cases, maintainability | 8 |
test-runner |
execute tests, diagnose failures, classify errors | 10 |
security-reviewer |
OWASP Top 10, injection, auth, secrets | 10 |
performance-reviewer |
async bottlenecks, N+1, hot paths, I/O | 10 |
tech-researcher |
external research (docs, communities, releases) | 25 |
devx-auditor |
doc drift, README / setup / Makefile accuracy | 12 |
evaluator-optimizer |
metrics-driven tuning — can edit files | 15 |
ux-reviewer |
user-facing clarity, flow, states, accessibility | 10 |
agentx-auditor |
curates CLAUDE.md — merge vs append | 10 |
toolkit-auditor |
meta-audit of the toolkit itself | 15 |
| Agent | Purpose | Turns |
|---|---|---|
data-reviewer |
SQL quality, layer conventions, joins, NULLs, idempotency | 12 |
data-quality-checker |
test coverage audit (PK, not_null, freshness, relationships) | 10 |
query-optimizer |
warehouse-specific perf (BigQuery / Snowflake / Redshift / Postgres) | 10 |
schema-auditor |
schema drift + full blast radius trace | 12 |
pipeline-reviewer |
DAG reliability (Airflow / Dagster / Prefect) | 12 |
lineage-analyzer |
dependency graph, blast radius, pattern violations | 12 |
| Skill | Purpose |
|---|---|
/create <stack> [name] |
Scaffold a new project with full toolkit |
/init |
Setup wizard for an existing project |
/reconfigure [section] |
Change config without re-scanning |
/welcome |
Show what's configured in this project |
/status |
Current toolkit state |
/self-heal |
Run tests → fail → diagnose → fix → retest (max 3) |
/review-changes [--deep] [--paths <glob>] |
Multi-agent review, preset-aware |
/research <topic> |
Pre-implementation external research |
/scaffold <feature> |
Generate new files matching project patterns |
/audit-guidance |
Check if CLAUDE.md still matches reality |
/toolkit-audit |
Full toolkit health check |
/toolkit-improve |
Interactive toolkit improvement from user friction |
Data skills (included when detected):
| Skill | Purpose |
|---|---|
/pipeline-heal |
Self-heal pipeline failures — reads logs, classifies, fixes |
/quality-check |
Data quality audit across models |
/review-models |
Multi-agent SQL model review |
/backfill |
Safe incremental backfill with validation |
/schema-change |
Handle schema drift with full impact analysis |
Three hooks ship with the toolkit. All are configured in .claude/settings.json by /init.
Runs after every Edit / Write. Dispatches by file extension to the right formatter:
.ts/.tsx/.js→ prettier / eslint / biome.py→ ruff / black.sql→ sqlfluff / sqlfmt.go→ gofmt / goimports.rs→ rustfmt
/init uncomments only the formatters actually installed in your project.
Three layers:
- Blocked (always):
rm -rf /, fork bombs,dd if=,chmod -R 777 /, piping curl into sh - Warned:
git push --forceon main/master,--forceflags - Data-specific (opt-in):
DROP DATABASE,--target prod,--full-refresh
Strict / loose / off at /reconfigure hooks.
Reads recently-edited paths from the transcript, matches against orchestrator.triggers, injects a short routing hint. Respects autonomy (auto-spawn / suggest / manual-only). Never blocks; fails silently if config is missing.
Instead of cramming every convention into CLAUDE.md, specific conventions live in .claude/rules/*.md. Each rule declares which paths it applies to:
---
paths: ["**/api/**", "**/routes/**", "**/controllers/**"]
---
# API Conventions
- Validate all input at the boundary.
- Return structured errors with a stable shape.
- Every user-scoped endpoint verifies ownership, not just authentication.
...These files load into Claude's context only when editing files that match the glob. That is the single biggest win against token waste — a 200-line convention file that loads on every turn becomes a 30-line file that loads only when relevant.
/init generates these based on what your project actually has:
api.mdif API / routes / controllers paths existtests.mdif test dirs existsql.mdif SQL or dbt presentfrontend.mdif.tsx/.jsx/ componentspipelines.mdif DAG / flows present
This toolkit is designed for the reality that Claude Code plans have usage limits. The optimization is 4 layers:
Target ≤ 80 lines. Everything else goes to path-scoped rules. A ~60% reduction in every-turn base cost.
Every agent used to repeat authority hierarchy, output format, and discipline — ~50 lines duplicated 16 times. Now those live in agent-base.md (40 lines), referenced by every agent.
- Agents are 40-60 lines instead of 80-180.
- Shared rules edited in one place, not 16.
- ~800 lines of duplicated content eliminated.
/review-changes spawned 4 agents on every change by default. Now the base panel is 2 (code + test) and triggers add more only when paths match. Typical review drops from ~80-110k tokens to ~20-30k.
Downgrade to Haiku where reasoning demands are low (test-runner, ux-reviewer surface, devx-auditor). Keep Sonnet for security / performance / data reasoning. Same tokens, but Haiku "weighs" less against usage limits.
| Component | Before | After | Reduction |
|---|---|---|---|
| Per-turn base context | ~9k | ~3.5k | ~60% |
/review-changes typical |
80-110k | 20-30k | ~75% |
| Plan-weighted (Haiku mix) | baseline | ~40-60% less | meaningful |
Rough estimates. Actual depends on diff size and project.
/reconfigure preset
Rebuilds agent panel + orchestrator triggers from the new preset. CLAUDE.md and your custom triggers are preserved.
/reconfigure agents
Toggle any of the 16 on or off. Copies or removes files from .claude/agents/ and updates settings.
/reconfigure orchestrator
Walks you through adding a paths → agents rule. Written to toolkit.orchestrator.triggers in settings.
mkdir .claude/agents/my-agent
Create AGENT.md:
---
name: my-agent
description: "When to spawn and what it does."
tools: Read, Grep, Glob
model: sonnet
maxTurns: 10
---
Follow `agent-base.md`. This file only contains my-agent specifics.
## Scope
...
## Output additions
...# .claude/rules/my-rule.md
---
paths: ["src/domain/**"]
---
# Domain Conventions
Specific rules that apply only to this area.
1. You: "add pagination to the /users endpoint"
2. Claude proposes a plan → you approve
3. Claude edits the endpoint + tests
4. post-edit hook auto-formats
5. orchestrator hook detects api/** match → suggests security-reviewer
6. You: "/review-changes"
7. Review spawns code + test + security (triggered) in parallel
8. Critical finding: missing ownership check → Claude fixes → re-runs test-runner
9. You commit
1. You: "users report login 500 errors"
2. Claude reads the logs, traces the issue, fixes the bug
3. post-edit hook formats
4. orchestrator sees auth/** match → auto-spawns security-reviewer (autonomy=high)
5. test-runner verifies
6. Claude reports summary + proposes commit message
1. /create fastapi user-service
2. Scaffolds source + tests + Docker + CI
3. Writes .scaffold-meta.json
4. Auto-invokes /init → skips detection, shows summary
5. You: accept defaults
6. CLAUDE.md + settings + rules generated
7. Initial commit created
8. You: cd user-service && uvicorn main:app
1. You: "add is_active column to users source"
2. Claude updates sources.yml
3. /schema-change auto-invokes
4. Spawns schema-auditor + lineage-analyzer in parallel
5. Impact report: 3 staging models, 7 intermediate, 2 marts affected
6. Fix order: staging first → test → intermediate → test → marts → test
7. data-quality-checker verifies test coverage on the new column
The toolkit audits itself.
- Use daily. Notice friction — wrong command in CLAUDE.md, agent missing the right category, hook triggering on the wrong files.
/toolkit-improve— describe the friction;toolkit-auditoranalyzes and proposes specific fixes./toolkit-auditmonthly — full health check: Is CLAUDE.md under 100 lines? Are hooks configured correctly? Any broken references between agents and missing tools?agentx-auditorruns after new conventions. It decides whether a new lesson deserves a CLAUDE.md rule, and keeps the file concise (merge over append).
Why one repo instead of separate SWE/data toolkits?
Agents are stack-agnostic. /init enables the right ones based on what it detects. TypeScript project gets 10 agents, dbt project gets 16. No separate toolkit to maintain.
Why generate instead of template?
Templates go stale. /init scans your real project and generates config from reality.
Why path-scoped rules?
Every byte of CLAUDE.md loads every turn. Rules that only apply when editing api/** should load only when editing api/**.
Why are agents read-only?
Safety. A code-reviewer that can edit is a code-reviewer that can break things. Only evaluator-optimizer edits, and only with explicit metrics and baselines.
Why presets? Defaults for six coupled decisions (base panel, model mix, triggers, budget, activation, autonomy). You pick the preset that matches how you want to work, then customize inside it.
Why per-review token budget? Because plans have limits. A review that burns through a daily budget in one invocation is a bad review.
Why not cloud-specific config? Cloud is a property of the project, not the toolkit. CLAUDE.md captures the warehouse + CLIs; agents adapt.
- Agent architecture patterns originally from Cnsfeir — authority hierarchy, read-only by default, structured output, deep operational discipline.
- Hooks automation patterns from Ruflo.
- Coordination concepts from Paperclip.
- Built on Claude Code native features.
MIT