Claude Code Configuration
Personal configuration for Claude Code providing development guidelines, slash commands, custom agents, and language-specific skills.
What's Included
claude-code/
├── CLAUDE.md # Shared runtime agent instructions (synced to ~/.claude/CLAUDE.md and ~/.codex/AGENTS.md)
├── CLAUDE.local.md # Local operational notes for this repo (not the runtime instruction source)
├── commands/ # Slash commands
│ ├── fix-issue.md # /fix-issue <id> - locate and fix issues
│ ├── git-commit.md # /git-commit - conventional commit workflow
│ ├── handoff.md # /handoff - generate session handoff prompts
│ └── rewrite-history.md # /rewrite-history - clean up branch commits
├── agents/ # Custom subagents
│ ├── code-reviewer.md # Review code for quality and security
│ ├── debugger.md # Root cause analysis for failures
│ ├── refactorer.md # Clean refactoring with complete migrations
│ └── test-writer.md # Write tests that verify correctness
├── .claude/
│ └── skills/ # Language and tool best practices
│ ├── python-best-practices/
│ ├── typescript-best-practices/
│ ├── react-best-practices/
│ ├── go-best-practices/
│ ├── zig-best-practices/
│ ├── playwright-best-practices/
│ ├── tamagui-best-practices/
│ ├── tilt/
│ ├── web-fetch/
│ ├── axe-ios-simulator/
│ └── zig-docs/
├── scripts/ # Utility scripts
│ ├── install-symlinks.sh # Installation helper
│ └── sync-codex.sh # Sync/check Claude commands + skills into Codex
├── codex-overrides/
│ └── skills/ # Codex-only skill overrides applied after upstream sync
├── settings/ # Settings configurations
├── statusline/ # Statusline configurations
└── analytics/ # Usage analytics (submodule)
Installation
Via Stow (Recommended)
This repo is a submodule of a dotfiles repository using GNU Stow:
cd ~/code/dotfiles
stow -v -R -t ~ claude
The claude stow package symlinks to this repo's contents.
Manual Symlinks
mkdir -p ~/.claude
ln -sf "$(pwd)/CLAUDE.md" ~/.claude/CLAUDE.md
ln -sf "$(pwd)/commands" ~/.claude/commands
ln -sf "$(pwd)/agents" ~/.claude/agents
ln -sf "$(pwd)/.claude/skills" ~/.claude/skills
Commands
Invoke with /command-name in Claude Code:
| Command | Description |
|---|
/fix-issue <id> | Find and fix an issue by ID with tests and PR description |
/git-commit | Review changes and create conventional commits |
/handoff | Generate a self-contained handoff prompt for another agent |
/rewrite-history | Rewrite branch with clean, narrative commit history |
Agents
Custom subagents for focused tasks. Claude Code delegates to these automatically when appropriate:
| Agent | Purpose |
|---|
code-reviewer | Reviews changes for quality, security, and project conventions |
debugger | Investigates failures through root cause analysis |
refactorer | Restructures code with clean breaks and complete migrations |
test-writer | Writes tests that verify correctness without gaming assertions |
Skills
Language and tool-specific best practices loaded automatically based on file context:
| Context | Skill |
|---|
Python (.py, pyproject.toml) | python-best-practices |
TypeScript (.ts, .tsx) | typescript-best-practices |
React (.tsx, .jsx, @react imports) | react-best-practices |
Go (.go, go.mod) | go-best-practices |
Zig (.zig, build.zig) | zig-best-practices |
Playwright (@playwright/test) | playwright-best-practices |
Tamagui (@tamagui imports) | tamagui-best-practices |
Tilt (Tiltfile) | tilt |
Runtime Settings
- Baseline settings:
claude-code/settings/settings.json
- Local overrides:
~/.claude/settings.local.json
- Generated runtime file:
~/.claude/settings.json (generated by bin/bin/claude-settings-merge --fix)
- Merge behavior: object keys merge recursively;
permissions.allow and permissions.additionalDirectories append local entries without removing baseline entries; other arrays are replaced by local values.
Instruction Source of Truth
- Keep shared agent behavior in
claude-code/CLAUDE.md.
- Keep local repo notes and personal operational guidance in
claude-code/CLAUDE.local.md.
- Do not move local-only content into
claude-code/CLAUDE.md; that file syncs to both ~/.claude/CLAUDE.md and ~/.codex/AGENTS.md.
Codex Asset Sync
# Drift check only (exit 0 clean, 2 drift, 1 error)
claude-code/scripts/sync-codex.sh --check
# Apply sync and prune stale managed entries (commands + skills)
claude-code/scripts/sync-codex.sh
alleneubank