Claude Code Config

Reusable agents, commands, and permission templates for Claude Code.

Why This Exists

Claude Code stores configuration in ~/.claude/ (global) and .claude/ (per-project). Managing this across multiple projects and machines becomes tedious:

Agents need to be copied to each project
Commands are duplicated everywhere
Permission templates drift between projects
New machines require manual setup

This repo solves that by providing:

A single source of truth for your Claude Code configuration
Symlinks so updates propagate everywhere automatically
Composable templates for different project types
Hooks for auto-formatting, safety checks, and notifications
Skills for passive domain knowledge activation
Rules for path-scoped code style enforcement
Setup scripts that work on any machine

Quick Start

# 1. Clone (or fork if you want to customize)
git clone https://github.com/edjchapman/claude-code-config.git ~/claude-code-config

# 2. Set up global config
~/Development/claude-code-config/scripts/setup-global.sh

# 3. Set up a project (from your project directory)
cd ~/my-django-project
~/Development/claude-code-config/scripts/setup-project.sh django

# 4. Start using Claude Code - agents and commands are now available
claude

Tip: Add an alias for easier use:

# Add to ~/.bashrc or ~/.zshrc
alias claude-setup='~/Development/claude-code-config/scripts/setup-project.sh'

# Then use it like:
claude-setup django react

What Gets Created

Global setup (setup-global.sh) creates symlinks in ~/.claude/:

~/.claude/
├── agents            -> ~/Development/claude-code-config/agents
├── commands          -> ~/Development/claude-code-config/commands
├── skills            -> ~/Development/claude-code-config/skills
├── rules             -> ~/Development/claude-code-config/rules
└── settings.json     -> ~/Development/claude-code-config/settings.json

Project setup (setup-project.sh) creates in your project:

your-project/
├── .mcp.json (MCP server config, if applicable)
└── .claude/
    ├── agents              -> ~/Development/claude-code-config/agents
    ├── commands            -> ~/Development/claude-code-config/commands
    ├── skills              -> ~/Development/claude-code-config/skills
    ├── rules               -> ~/Development/claude-code-config/rules
    ├── settings.json       -> ~/Development/claude-code-config/settings.json
    └── settings.local.json (generated from templates)

Understanding Settings Files

settings.json (symlinked): Plugin enablement, hooks configuration, and model selection
settings.local.json (generated): Permissions - what bash commands and tools Claude can use in your project

How It Works

Everything in this repo falls into two categories:

	Active (you invoke)	Passive (auto-activates)
What	Specialist agents, Commands, CLI scripts	Skills, Rules, Hooks
How	`@name`, `/name`, or shell command	Triggered by file patterns or lifecycle events
Example	`@bug-resolver`, `/commit`, `daily-report.sh`	`testing-patterns` skill activates on `test_*.py`

Active tools — you choose when to use them:

Specialist agents (@bug-resolver, @test-engineer, etc.) provide deep expertise in a single domain
Commands (/commit, /pr, /standup, etc.) run focused, single-purpose workflows
CLI scripts (review-changes.sh, daily-report.sh, etc.) run headless — no interactive session needed

Code review and spec-writing are now handled by bundled plugins rather than custom artifacts:

/review (bundled) and pr-review-toolkit:review-pr for code review
feature-dev:code-architect for implementation blueprints
/security-review (bundled) for security audits

Passive tools — they activate automatically when relevant:

Skills inject domain knowledge when you touch matching files (e.g., django-patterns activates on models.py)
Rules enforce code style on matching file types (e.g., python-style on *.py)
Hooks run at lifecycle events (e.g., auto-format on file save, safety checks before commands)

Which Should I Use?

"I want to..." Lookup

I want to...	Use	Why
Quick review before committing	`/review` (bundled)	Fast diff review, no agent overhead
Deep code review	`pr-review-toolkit:code-reviewer`	Thorough pre-merge audit via plugin
Inline code review	`feature-dev:code-reviewer`	Confidence-filtered high-priority issues
Bundle PR comments for analysis	`@pr-review-bundler`	Gathers PR metadata, reviews, comments into one markdown file
Write or fix tests	`@test-engineer`	Creates unit and integration tests
Run a security audit	`/security-review` (bundled)	Security review of pending changes
Deeper security audit	`@security-auditor`	OWASP, dependency vulnerabilities, secrets
Plan a feature before coding	`feature-dev:code-architect`	Implementation blueprint via plugin
Analyze test coverage gaps	`/coverage-report`	Delegates to `@test-engineer`
Create a good commit message	`/commit`	Analyzes staged changes, follows conventions
Create a pull request	`/pr`	Auto-generates PR description from commits
Check what I've been doing	`/standup`	Summarizes last 24h across Git, Jira, Notion
Weekly summary for manager	`/eow-review`	Full week review across all sources
Prepare for backlog refinement	`/refinement`	Technical analysis of tickets with code context
Debug CI/CD failures	`@ci-debugger`	Investigates pipeline failures, flaky tests
Optimize slow queries/endpoints	`@performance-engineer`	Profiling, bottleneck analysis, optimization
Plan a database migration	`@migration-engineer`	Zero-downtime migration strategies
Review dependencies	`/deps`	Audit vulnerabilities, outdated packages
Write documentation	`@documentation-writer`	README, API docs, ADRs, onboarding guides
Headless review (no session)	`review-changes.sh`	Runs in CI or as a shell alias

Understanding the Layers

Some tools overlap intentionally at different levels of depth:

Code review depth:     /review  →  feature-dev:code-reviewer  →  pr-review-toolkit:code-reviewer  →  /ultrareview
                       (uncommitted diff)  (inline, filtered)     (pre-merge audit)                  (multi-agent cloud)

Reporting scopes:      daily-report.sh  →  /standup  →  /eow-review
                       (headless)          (24h)        (full week)

Fork or Clone?

Approach	When to Use
Clone	You want to use as-is, or contribute improvements back
Fork	You want to customize agents/commands for your own workflow

If you fork, you can still pull updates from upstream:

git remote add upstream https://github.com/edjchapman/claude-code-config.git
git fetch upstream
git merge upstream/main

Available Templates

Use one or combine multiple:

~/Development/claude-code-config/scripts/setup-project.sh python          # Python project
~/Development/claude-code-config/scripts/setup-project.sh django          # Django
~/Development/claude-code-config/scripts/setup-project.sh django react    # Full-stack
~/Development/claude-code-config/scripts/setup-project.sh go              # Go project
~/Development/claude-code-config/scripts/setup-project.sh node            # Node.js
~/Development/claude-code-config/scripts/setup-project.sh terraform       # Infrastructure
~/Development/claude-code-config/scripts/setup-project.sh all             # ALL templates

Template	What It Allows
`all`	All templates below combined
`base`	Git, GitHub CLI, file operations, WebSearch (always included)
`python`	pytest, mypy, ruff, black, isort, flake8, pylint, bandit, pre-commit, pip, uv, poetry
`django`	Django manage.py commands (test with --no-input --parallel=8), docker compose, make, uv run (flake8, basedpyright)
`react`	npm, yarn, pnpm, vitest, playwright, TypeScript, eslint, prettier
`node`	npm, yarn, pnpm, vitest, jest, mocha, eslint, prettier, tsc, bun
`nextjs`	Next.js dev/build/lint, Vercel CLI, npm/yarn/pnpm, vitest, playwright
`fastapi`	uvicorn, alembic, pytest, ruff, mypy, uv, poetry, docker compose
`go`	go build/test/run, golangci-lint, staticcheck, dlv, mockgen, wire
`docker`	Docker build, compose, buildx, system commands
`java`	Gradle, Maven, Java compilation (javac, jar)
`kubernetes`	kubectl, helm, kustomize, kubectx, stern
`rust`	cargo, rustc, rustup, rustfmt, clippy
`terraform`	terraform fmt/validate/plan/init

Available Agents

Invoke with @agent-name in Claude Code:

Agent	What It Does	Model
`@bug-resolver`	Systematic debugging, root cause analysis	opus
`@ci-debugger`	CI/CD failure investigation, flaky tests	sonnet
`@database-architect`	Schema design, migration planning, query optimization	opus
`@dependency-manager`	Dependency audit, outdated packages, license checks	sonnet
`@devops-engineer`	Infrastructure, CI/CD pipelines, containers	opus
`@documentation-writer`	README, API docs, ADRs, onboarding guides	sonnet
`@e2e-playwright-engineer`	Create and debug Playwright E2E tests	sonnet
`@git-helper`	Complex git: rebase, conflicts, recovery	sonnet
`@migration-engineer`	Database migrations, framework upgrades, zero-downtime	opus
`@performance-engineer`	Profiling, bottleneck analysis, optimization	opus
`@pr-review-bundler`	Bundle PR reviews into markdown	sonnet
`@refactoring-engineer`	Systematic, safe refactoring	opus
`@security-auditor`	Security audit, OWASP, dependency vulnerabilities	opus
`@test-engineer`	Create unit and integration tests	sonnet

Not in this repo (provided by enabled plugins): general code review (pr-review-toolkit:code-reviewer, feature-dev:code-reviewer), spec/architecture writing (feature-dev:code-architect), code simplification (code-simplifier plugin). Custom versions of these were retired in favour of the plugin implementations.

Model notes:

Opus = complex reasoning, security reviews, planning (higher cost)
Sonnet = pattern-based tasks, faster, lower cost

Available Commands

Invoke with /command in Claude Code:

Command	What It Does	Delegates To
`/commit`	Analyze staged changes, generate commit message	--
`/pr`	Create PR with auto-generated description	--
`/standup`	Summarize last 24h of git activity	--
`/tdd`	TDD workflow: write failing test, implement, refactor	--
`/hotfix`	Guided hotfix: branch from main, minimal fix, targeted tests, PR	--
`/deps`	Dependency audit: vulnerabilities, outdated packages, update plan	--
`/adr`	Create Architecture Decision Record (Nygard format)	--
`/coverage-report`	Analyze test coverage and identify gaps	`@test-engineer`
`/refinement`	Prepare technical analysis for backlog refinement	Explore sub-agent
`/eow-review`	Prepare end-of-week review notes	--
`/later`	Create a personal backlog item (learn, research, do, read)	--

Provided by the harness (not in this repo): /review, /security-review, /init, /ultrareview, /less-permission-prompts. Custom commands/review.md and commands/security-scan.md were retired in favour of the bundled versions.

Common Workflows

Here's how the pieces compose for everyday tasks:

Implement a Feature

feature-dev:code-architect          # 1. Implementation blueprint via plugin
  (you write the code)              # 2. Implement
@test-engineer                      # 3. Write tests
/review                             # 4. Quick diff check
/commit → /pr                       # 5. Ship it

Fix a Bug

@bug-resolver                       # Investigate root cause
  (you fix the code)                # Apply the fix
/review → /commit                   # Quick check and commit

Daily Development Cycle

/standup                            # Generate standup notes
  (you work)                        # Write code
/review                             # Before committing: quick diff check
/commit → /pr                       # Commit and open PR

Review a PR

pr-review-toolkit:review-pr         # Bundled plugin: full PR analysis
  ... or for a deeper audit:
/ultrareview                        # Multi-agent cloud review (billed)
  ... or headless:
review-pr.sh 142                    # CLI: runs without an interactive session

End-of-Week Reporting

/standup                            # Daily: last 24h activity
/eow-review                        # Weekly: full week summary across Git, GitHub, Jira, Notion
daily-report.sh                     # Headless: auto-generate daily summary

CLI Scripts

Headless Claude Code scripts for automation. Add aliases to your shell profile for quick access:

alias cr='~/Development/claude-code-config/scripts/cli/review-changes.sh'
alias cpr='~/Development/claude-code-config/scripts/cli/review-pr.sh'
alias cdr='~/Development/claude-code-config/scripts/cli/daily-report.sh'
alias cee='~/Development/claude-code-config/scripts/cli/explain-error.sh'

Script	Usage	What It Does
`review-changes.sh`	`cr`	Review uncommitted changes for bugs, security, code quality
`explain-error.sh`	`cmd 2>&1 \| cee`	Pipe error output to Claude for explanation
`daily-report.sh`	`cdr`	Summarize last 24h of git activity
`review-pr.sh`	`cpr 123`	Headless PR review

MCP Templates

MCP server configurations per project type, generated alongside settings.local.json:

Template	MCP Servers
`base`	None (MCP is opt-in)
`django`	PostgreSQL (`@modelcontextprotocol/server-postgres`)

Playwright is provided as a first-class plugin (playwright@claude-plugins-official, enabled in settings.json), so React projects do not get a generated .mcp.json from this repo by default.

MCP templates are automatically merged when running setup-project.sh if a matching template exists.

Directory Structure

claude-code-config/
├── agents/                  # Agent definitions (markdown)
├── commands/                # Slash commands (markdown)
├── skills/                  # Auto-activating domain knowledge (markdown)
├── rules/                   # Path-scoped code style rules (markdown)
├── settings-templates/      # Permission templates (JSON)
├── mcp-templates/           # MCP server templates (JSON)
├── settings.json            # Plugin config + hooks (symlinked globally)
├── scripts/
│   ├── setup-global.sh      # One-time machine setup
│   ├── setup-project.sh     # Per-project setup
│   ├── merge-settings.py    # Permission template merger
│   ├── merge-mcp.py         # MCP template merger
│   ├── hooks/               # Hook scripts referenced by settings.json
│   │   ├── session-context.sh
│   │   ├── statusline.sh
│   │   ├── dangerous-cmd-check.sh
│   │   ├── check-duplicates.sh
│   │   ├── format-on-edit.sh
│   │   └── pre-compact-state.sh
│   └── cli/                 # Headless CLI automation scripts
│       ├── review-changes.sh
│       ├── explain-error.sh
│       ├── daily-report.sh
│       └── review-pr.sh

Hooks

Hooks are configured in settings.json and run automatically at key points in the Claude Code lifecycle. Since settings.json is symlinked globally, hooks work in all projects.

Hook	Trigger	What It Does
SessionStart	New session	Outputs git branch, recent commits, and dirty files
Setup (init)	Project init	Detects project type, suggests configuration
UserPromptSubmit	Before prompt sent	LLM checks if prompt is specific enough to act on
PostToolUse (Write/Edit)	After file edits	Auto-formats Python (ruff) and JS/TS (prettier)
PreToolUse (Bash)	Before commands	Blocks dangerous patterns (`rm -rf /`, `dd`, etc.)
Stop	Session end	LLM checks: tests run? linters run? TODOs left?
SubagentStop	Before subagent returns	LLM checks if subagent completed its task fully
PreCompact	Before compaction	Saves working state (branch, staged files, recent commits)

Hook scripts live in scripts/hooks/ and only run when the required tools are available (e.g., ruff, prettier).

Output Styles

Claude Code supports several response styles via outputStyle in settings.json or with the per-session /output-style command. This repo doesn't set a default — outputStyle is a personal preference and varies by task type.

Style	When to use
`default`	Standard task-focused responses
`explanatory`	Adds learning insights inline (good for unfamiliar codebases)
`learning`	More guided; fewer one-shot answers (good for upskilling)

To set a default:

{
  "outputStyle": "explanatory"
}

Or switch on the fly with /output-style explanatory. See the official Claude Code docs for the current list of styles and how to author custom ones.

Sandbox

Claude Code supports a sandbox mode that constrains Bash execution. This repo ships disabled by default so the baseline config doesn't change a user's effective security posture when symlinked into projects:

"sandbox": {
  "enabled": false,
  "autoAllowBashIfSandboxed": false
}

To opt in, override in your local user settings (~/.claude/settings.local.json) or per-project once you've confirmed the boundary is acceptable:

"sandbox": {
  "enabled": true,
  "autoAllowBashIfSandboxed": true
}

autoAllowBashIfSandboxed reduces permission prompts inside sandboxed worktrees. Enable deliberately, not by default — silent enablement of auto-approved Bash is exactly the kind of behaviour shared/symlinked configs should avoid.

Skills

Skills are domain knowledge documents that auto-activate when you touch matching files. They provide passive guidance without explicit invocation.

Skill	Activates On	What It Covers
`git-workflow`	`.git/**`	Conventional commits, branch naming, PR size
`testing-patterns`	`test_.py`, `_test.py`, `.test.ts`, `.spec.ts`, etc.	AAA pattern, factories, coverage
`security-review`	`auth/`, `middleware/`, `security/`, `routes/`	Input validation, JWT, CSRF, secrets
`api-design`	`views/`, `api/`, `routes/`, `controllers/`, `endpoints/**`	REST conventions, status codes, pagination
`django-patterns`	`models.py`, `views.py`, `managers.py`, `signals.py`, etc.	Fat models, managers, query optimization, signals
`docker-patterns`	`Dockerfile`, `docker-compose*.yml`, `.dockerignore`	Multi-stage builds, layer caching, security
`infrastructure`	`.tf`, `k8s//.yaml`, `helm/**`	Terraform modules, K8s resources, Helm charts

Rules

Rules are path-scoped code style enforcement files in rules/. They use paths frontmatter for granular file matching and are enforced when touching matching files.

Rule	Applies To	What It Enforces
`python-style`	`*/.py`	Naming, error handling, imports, type hints
`typescript-style`	`*/.ts`, `*/.tsx`	Naming, error handling, type usage, plus React-specific rules for `.tsx`

Skills provide domain knowledge (patterns and best practices); rules enforce style requirements.

Customization

Adding an Agent

Create agents/my-agent.md:

---
name: my-agent
description: Brief description for when Claude should use this agent
model: opus
---

## Instructions

Your detailed agent instructions here...

Adding a Command

Create commands/my-command.md. The filename becomes /my-command.

Adding a Template

Create settings-templates/my-stack.json:

{
  "_source": "my-stack",
  "_version": 1,
  "permissions": {
    "allow": [
      "Bash(my-cli-tool:*)",
      "WebFetch(domain:docs.my-tool.com)"
    ]
  }
}

Then use: setup-project.sh my-stack

Keeping Settings in Sync

Check if your project settings match the templates:

cd ~/my-project
~/Development/claude-code-config/scripts/setup-project.sh --check django

Regenerate if drifted:

~/Development/claude-code-config/scripts/setup-project.sh django

Git Setup for Projects

Add to your project's .gitignore:

# Claude Code symlinks (personal config)
.claude/agents
.claude/commands
.claude/skills
.claude/rules
.claude/settings.json

Do commit settings.local.json if you want to share permissions with your team. The settings.json symlink is personal (plugin preferences), while settings.local.json contains project-specific permissions worth sharing.

Uninstalling / Cleanup

Remove global symlinks:

rm ~/.claude/agents ~/.claude/commands ~/.claude/skills ~/.claude/rules ~/.claude/settings.json
# If upgrading from an older version that included keybindings.json:
rm -f ~/.claude/keybindings.json

Remove from a project:

rm -rf .claude/agents .claude/commands .claude/skills .claude/rules .claude/settings.json
# Optionally remove generated permissions too:
rm .claude/settings.local.json

Moving the repo to a new location:

# After moving, re-run setup scripts to update symlinks
~/new-location/claude-code-config/scripts/setup-global.sh
cd ~/my-project && ~/new-location/claude-code-config/scripts/setup-project.sh django

Troubleshooting

Python not found

python3 --version  # Need 3.8+
# macOS: brew install python@3.11
# Ubuntu: sudo apt install python3

Symlinks broken after moving repo

# Re-run both setups
~/Development/claude-code-config/scripts/setup-global.sh
cd ~/my-project && ~/Development/claude-code-config/scripts/setup-project.sh django

"Circular symlink" error You're running setup-project.sh from inside the config repo. Run it from your actual project directory instead.

Requirements

Bash shell (macOS, Linux, or WSL on Windows)
Python 3.8+
Claude Code CLI

Windows Users

These scripts require a Unix-like environment. Options:

WSL (recommended): Install Windows Subsystem for Linux, then run scripts from within WSL
Git Bash: May work but is not tested

Note: Symlinks created in WSL are not visible from native Windows applications.

License

MIT - see LICENSE

Contributing

PRs welcome!

Name		Name	Last commit message	Last commit date
Latest commit History 75 Commits
.claude		.claude
.github/workflows		.github/workflows
agents		agents
commands		commands
mcp-templates		mcp-templates
rules		rules
scripts		scripts
settings-templates		settings-templates
skills		skills
.gitignore		.gitignore
.mcp.json		.mcp.json
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
README.md		README.md
settings.json		settings.json
settings.local.json		settings.local.json

Folders and files

Latest commit

History

Repository files navigation

Claude Code Config

Why This Exists

Quick Start

What Gets Created

Understanding Settings Files

How It Works

Which Should I Use?

"I want to..." Lookup

Understanding the Layers

Fork or Clone?

Available Templates

Available Agents

Available Commands

Common Workflows

Implement a Feature

Fix a Bug

Daily Development Cycle

Review a PR

End-of-Week Reporting

CLI Scripts

MCP Templates

Directory Structure

Hooks

Output Styles

Sandbox

Skills

Rules

Customization

Adding an Agent

Adding a Command

Adding a Template

Keeping Settings in Sync

Git Setup for Projects

Uninstalling / Cleanup

Troubleshooting

Requirements

Windows Users

License

Contributing

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 3

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Packages