claude-settings/README.md

Claude Code Configuration

This directory contains global Claude Code configuration that is synced across machines via git.

What's Tracked

Global Instructions

• CLAUDE.md - Global working preferences, code style standards, TDD workflow, and communication style

Settings

• settings.json - Claude Code application settings

Custom Agents (agents/)

Specialized agents for specific workflows:

• gentoo-sysadmin.json - Gentoo Linux system administration (OpenRC, Portage, kernel)
• tdd-test-writer.json - TDD Ping-Pong workflow (writes failing tests)
• code-reviewer.json - Code review against strict style guidelines
• documentation-writer.json - Creates comprehensive project documentation
• python-ai-tutor.json - AI/ML coursework assistant with teaching focus
• dotfiles-manager.json - Dotfiles management with chezmoi

Slash Commands (commands/)

Quick workflow commands:

• /gentoo-update - Safe Gentoo system update workflow
• /tdd-next - Start next TDD test cycle
• /style-check - Comprehensive code style validation
• /doc-sync - Update all project documentation
• /review-pr - Review pull request before merge
• /script-install - Install system script with proper permissions

What's NOT Tracked

The .gitignore excludes machine-specific and sensitive data:

• .credentials.json - Authentication tokens (SENSITIVE)
• CLAUDE-LOCAL.md - Machine-specific overrides (work/personal)
• *-local.json - Machine-specific settings
• history.jsonl - Conversation history (machine-specific)
• todos/ - Session-specific todo lists
• projects/ - Project state (machine-specific paths)
• session-env/ - Session environment data
• file-history/ - File version history
• plans/ - Plan mode drafts
• debug/, downloads/, statsig/ - Temporary/analytics data

Multi-Machine Setup

Using this config across multiple machines (personal, work, etc.)?

See MULTI-MACHINE-SETUP.md for the complete guide.

Quick summary:

• Shared config (CLAUDE.md, agents, commands) syncs via git
• Machine-specific overrides go in CLAUDE-LOCAL.md (not tracked)
• No branch conflicts - layered configuration approach
• Same repo works for personal and work computers with different credentials

Using Custom Agents

Custom agents are invoked using the Task tool:

# In conversation context
Use the Task tool with subagent_type matching the agent name

Or via CLI:

claude --agents '{"review": "~/.claude/agents/code-reviewer.json"}'

Using Slash Commands

In Claude Code conversation:

/gentoo-update
/tdd-next
/style-check
/doc-sync
/review-pr <pr-number>
/script-install

Setup on New Machine

1. Clone this repository:

   cd ~/.claude
   git init
   git remote add origin <your-repo-url>
   git pull origin main
   

2. Set up credentials (not tracked):

   claude setup-token
   

3. Verify configuration:

   cat CLAUDE.md
   ls agents/
   ls commands/
   

Style Guidelines

All code follows strict standards defined in CLAUDE.md:

• 80-character line limit
• 2-space indentation
• Language-specific conventions (PEP 8, Airbnb, POSIX sh)
• Minimal comments
• Security-first approach
• TDD Ping-Pong workflow for development

Maintenance

Adding New Agents

1. Create agents/<name>.json with:
   • name: Agent identifier
   • description: When to use this agent
   • prompt: Detailed agent instructions
2. Commit and push

Adding New Commands

1. Create commands/<name>.md with markdown instructions
2. Commit and push

Updating Global Instructions

1. Edit CLAUDE.md
2. Test with a few conversations
3. Commit and push

Repository Structure

~/.claude/
├── README.md              # This file
├── CLAUDE.md              # Global instructions
├── settings.json          # Application settings
├── .gitignore             # Ignore patterns
├── agents/                # Custom agents (tracked)
│   ├── gentoo-sysadmin.json
│   ├── tdd-test-writer.json
│   ├── code-reviewer.json
│   ├── documentation-writer.json
│   ├── python-ai-tutor.json
│   └── dotfiles-manager.json
├── commands/              # Slash commands (tracked)
│   ├── gentoo-update.md
│   ├── tdd-next.md
│   ├── style-check.md
│   ├── doc-sync.md
│   ├── review-pr.md
│   └── script-install.md
└── [ignored directories]  # Machine-specific data (not tracked)
    ├── .credentials.json
    ├── history.jsonl
    ├── todos/
    ├── projects/
    ├── session-env/
    ├── file-history/
    ├── plans/
    ├── debug/
    ├── downloads/
    └── statsig/

Contributing

When adding or modifying agents/commands:

1. Follow the existing format
2. Test thoroughly
3. Update this README if adding new categories
4. Use semantic commit messages
5. Keep documentation in sync

---

Last Updated: 2025-11-26