claude-settings/QUICK-REFERENCE.md

Quick Reference

Multi-Machine Setup (TL;DR)

On Any New Machine

# 1. Clone config
cd ~/.claude
git clone <your-repo-url> .

# 2. Set up credentials (personal or work account)
claude setup-token

# 3. (Optional) Add machine-specific overrides
cp CLAUDE-LOCAL.md.example CLAUDE-LOCAL.md
vim CLAUDE-LOCAL.md

# Done! Pull updates anytime with:
git pull origin main

File Organization

File	Tracked in Git?	Purpose
CLAUDE.md	✅ Yes	Universal preferences (all machines)
CLAUDE-LOCAL.md	❌ No	Machine-specific overrides
agents/*.json	✅ Yes	Custom agents (shared)
commands/*.md	✅ Yes	Slash commands (shared)
.credentials.json	❌ No	Auth tokens (different per machine)
history.jsonl	❌ No	Conversation history

Configuration Precedence

CLAUDE-LOCAL.md  (highest priority, machine-specific)
      ↓ overrides
CLAUDE.md        (universal preferences)
      ↓ uses
agents/*.json    (shared agents)
commands/*.md    (shared commands)

Custom Agents

# Available agents:
- gentoo-sysadmin      # Gentoo Linux system admin
- tdd-test-writer      # TDD Ping-Pong workflow
- code-reviewer        # Code review against style guidelines
- documentation-writer # Comprehensive documentation
- python-ai-tutor      # AI/ML teaching assistant
- dotfiles-manager     # Dotfiles with chezmoi

Slash Commands

/gentoo-update    # Safe Gentoo system update
/tdd-next         # Start next TDD test cycle
/style-check      # Code style validation
/doc-sync         # Update all documentation
/review-pr        # Review pull request
/script-install   # Install system script

Common Workflows

Update Shared Config (Personal Machine)

cd ~/.claude
vim CLAUDE.md  # or agents/, commands/
git add .
git commit -m "feat: add XYZ"
git push origin main

Pull Updates (Work Machine)

cd ~/.claude
git pull origin main
# Your CLAUDE-LOCAL.md stays untouched

Add Work-Specific Override

cd ~/.claude
vim CLAUDE-LOCAL.md  # Add work standards
# File is already git-ignored, won't be committed
git status  # Should not show CLAUDE-LOCAL.md

Share Config with Others

Just give them your repo URL:

https://github.com/your-username/claude-config

They can fork or clone directly.

What's Safe to Share?

✅ Safe to share publicly:

• Agents (generic workflows)
• Commands (generic procedures)
• CLAUDE.md (your preferences, contains your name but that's fine)
• README.md (documentation)

❌ Never shared (git-ignored):

• .credentials.json (auth tokens)
• CLAUDE-LOCAL.md (machine-specific context)
• history.jsonl (conversation history)
• All session data (todos, projects, etc.)

Troubleshooting

Accidentally Committed Local File

cd ~/.claude
git rm --cached CLAUDE-LOCAL.md
git commit -m "chore: remove local overrides"
git push

Want Different Agents on Work Machine

Create work-specific agents in local/ directory:

mkdir -p ~/.claude/local/agents
vim ~/.claude/local/agents/company-specific-agent.json
# This is already git-ignored (local/* pattern)

Merge Conflict in CLAUDE.md

cd ~/.claude
git pull  # Conflict!
vim CLAUDE.md  # Resolve conflict
git add CLAUDE.md
git commit
git push
# Your CLAUDE-LOCAL.md is never touched

Documentation

• README.md - Overview and usage
• MULTI-MACHINE-SETUP.md - Complete multi-machine guide
• CLAUDE.md - Your coding preferences (THE SOURCE OF TRUTH)
• CLAUDE-LOCAL.md.example - Template for local overrides

Architecture Decision

Why layered config instead of branches?

❌ Branches approach (rejected):

• Constant merge conflicts in CLAUDE.md
• Tedious to keep work/personal in sync
• Easy to forget which branch you're on
• Hard to share universal updates

✅ Layered config approach (chosen):

• Zero merge conflicts
• git pull just works
• Universal updates propagate automatically
• Machine-specific stays local
• Same repo, different contexts

---

For detailed explanations, see MULTI-MACHINE-SETUP.md