A comprehensive, production-ready configuration for Claude Code demonstrating best practices for customization and automation. This is a reference implementation—fork it, steal what you like, adapt it to your workflow.
This directory (~/.claude) is the global configuration directory for Claude Code. All customizations here apply across projects unless overridden locally.
Don’t install this. Just steal what you like.
settings.json to adjust tool permissions and MCP serversCLAUDE.md to document your coding principles and preferences/create-agent [name] to build specialized agents/create-skill [name] to create reusable capabilities/create-command [name] to build quick shortcuts/create-output-style [name] to define behavior modesreferences/decision-matrix.md - Quick component selectionreferences/when-to-use-what.md - Detailed scenarios and examples| File | Purpose |
|---|---|
settings.json |
Global permissions, MCP servers, cleanup policies, and tool approvals |
CLAUDE.md |
Instructions for Claude when working in this repository |
.gitignore |
Git ignore rules for this configuration directory |
| Directory | Purpose |
|---|---|
agents/ |
Specialized AI agents for specific workflows |
skills/ |
Reusable capabilities and knowledge domains |
hooks/ |
Event-driven automation and validation |
rules/ |
Language and tool-specific coding standards |
commands/ |
Slash command shortcuts |
references/ |
Shared decision guides and naming conventions |
| Directory | Purpose |
|---|---|
projects/ |
Per-project metadata and usage tracking |
todos/ |
Session-scoped todo lists |
plans/ |
Implementation plans from plan mode |
file-history/ |
Change tracking for edited files |
session-env/ |
Environment snapshots per session |
sessions/ |
Session state and conversation data |
logs/ |
Session and commit history logs |
debug/ |
Session debug output |
shell-snapshots/ |
Shell environment captures |
cache/ |
Temporary cached data |
learned/ |
Claude’s learned preferences |
history.jsonl |
Conversation history across sessions |
When to use: Build specialized assistants for complex tasks requiring specific tools, models, or focused behavior.
Create a markdown file in agents/ with YAML frontmatter:
Examples: Read-only analyzers, code generators, domain-specific experts
When to use: Encapsulate domain knowledge, best practices, or complex workflows.
Create a directory in skills/ with a SKILL.md file:
Examples: Best practices, deployment procedures, workflow automation
When to use: Define persona modes that change how Claude behaves (tone, verbosity, approach).
Create a markdown file in output-styles/:
Examples: Technical writer, QA tester, learning mode, concise mode
When to use: Automate validation, formatting, logging, or policy enforcement without explicit prompting.
Create a shell script in the hooks/ directory, then configure it in settings.json:
{
"hooks": {
"preToolUse": [
{
"name": "my-hook",
"shell": "/Users/markayers/.claude/hooks/my-hook.sh",
"matchers": ["Bash.*"],
"timeoutMs": 5000
}
]
}
}
Exit codes: 0 = allow, 2 = block, anything else = fail gracefully
Examples: Auto-formatting, markdown validation, git command logging
Claude Code requires explicit permissions for tool operations. Configure in settings.json:
{
"permissions": {
"allowed": ["Read", "Bash(git:*)", "Write(*.md)"],
"denied": ["Read(.env*)", "Bash(sudo:*)"]
}
}
These are already configured in this setup:
.env* files are blocked from readinggo.sum, package-lock.json, etc.) are write-protectedsudo commands are denied by default.mcp.json contains API credentials (GitHub token)—not tracked in githistory.jsonl may contain sensitive context—not tracked in gitThis configuration includes 9 hooks:
# Check recent session logs
tail -n 50 logs/session-log.txt
# View commit history
cat logs/commit-log.txt
# List tracked projects
ls -l projects/
# View specific project stats
cat projects/-Users-markayers-source-mine-go/meta.json | jq
Claude Code automatically cleans session data older than 30 days. For manual cleanup:
# Remove old session data
find todos/ -name "*.json" -mtime +30 -delete
find debug/ -name "*.txt" -mtime +30 -delete
See CONTRIBUTING.md for guidelines on submitting improvements, bug reports, or new customizations.
MIT License - see LICENSE for details.
Last Updated: 2026-02-03