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.
• Plugin state lives in the baseline settings: enabledPlugins controls which plugins are turned on, and extraKnownMarketplaces declares where Claude Code fetches them.
• install.sh --claude reads those settings and runs claude plugin install for each enabled plugin; the install loop is idempotent.

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

Codex skill sync is curated:

• Upstream Claude user skills sync first
• Plugin skills sync next, with selective drops from claude-code/scripts/sync-codex.skill-policy.tsv
• Codex-only overrides in claude-code/codex-overrides/skills/ sync last and win on name collision

Core Principles

The CLAUDE.md guidelines emphasize:

• Type-first development: Define types before implementing logic; make illegal states unrepresentable
• Functional style: Prefer immutability, pure functions, and explicit data flow
• Minimal changes: Implement only what's requested; avoid unrequested features or refactoring
• Error handling: Handle or return errors at every level; fail loudly with clear messages
• Test integrity: Tests verify correctness, not just satisfy assertions
• Clean refactoring: Update all callers atomically; delete superseded code completely

Author

Created by Allen Eubank (Big Boss)

License

Licensed under the Apache License, Version 2.0. See LICENSE for details.