docs: add quick reference for multi-machine setup

docs: add multi-machine setup guide
Add comprehensive guide for using this config across multiple machines (personal, work, etc.) without branch conflicts. Changes: - Add MULTI-MACHINE-SETUP.md with complete setup instructions - Add CLAUDE-LOCAL.md.example as template for machine-specific overrides - Update .gitignore to exclude CLAUDE-LOCAL.md and *-local.json patterns - Update README.md to reference multi-machine setup guide Key features: - Layered configuration approach (shared + local overrides) - No branch conflicts - local overrides are git-ignored - Same repo works with different Claude Code credentials - Supports work/personal machines with different standards 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
2025-11-26 19:46:17 +01:00 · 2025-11-26 19:45:34 +01:00
5 changed files with 749 additions and 1 deletions
--- a/.gitignore
+++ b/.gitignore
@@ -18,9 +18,15 @@ secrets/
 *.secret

 # =============================================================================
-# MACHINE-SPECIFIC STATE
+# MACHINE-SPECIFIC STATE AND OVERRIDES
 # =============================================================================

+# Machine-specific overrides (work preferences, personal additions)
+CLAUDE-LOCAL.md
+*-local.json
+*-LOCAL.md
+local/
+
 # Conversation history (contains project-specific and personal conversations)
 history.jsonl
 history.*.jsonl
--- a/CLAUDE-LOCAL.md.example
+++ b/CLAUDE-LOCAL.md.example
@@ -0,0 +1,155 @@
+# Local Overrides Example
+
+This is an example file. Copy to `CLAUDE-LOCAL.md` to use:
+
+```bash
+cp CLAUDE-LOCAL.md.example CLAUDE-LOCAL.md
+vim CLAUDE-LOCAL.md  # Customize for this machine
+```
+
+`CLAUDE-LOCAL.md` will NOT be tracked in git (excluded by .gitignore).
+
+---
+
+# Local Overrides - [Machine Name/Purpose]
+
+Last updated: 2025-11-26
+
+This file contains machine-specific preferences that override or extend
+CLAUDE.md. It is NOT tracked in git.
+
+## Machine Context
+
+- **Purpose**: [Personal/Work/Research/etc.]
+- **Primary languages**: [Additional languages beyond CLAUDE.md]
+- **Authentication**: [Company/Personal Claude Code account]
+- **Operating System**: [If different from Gentoo]
+
+## Company-Specific Standards (for Work Machines)
+
+### Commit Message Format
+
+Override the format in CLAUDE.md for company requirements:
+
+```
+[TICKET-123] type: description
+
+Examples:
+[PROJ-456] feat: add user authentication
+[BUG-789] fix: resolve memory leak in parser
+```
+
+### Code Review Process
+
+- All PRs require 2 approvals
+- Use company GitHub Enterprise: github.company.com
+- PR template required
+- CI must pass: Jenkins pipeline
+
+### Testing Requirements
+
+- Minimum 80% code coverage
+- Integration tests required for API changes
+- Use company test fixtures: `@company/test-utils`
+
+### Deployment
+
+- Dev: dev.company.internal
+- Staging: staging.company.internal
+- Production: company.com
+- Deploy via Jenkins: jenkins.company.internal
+
+## Internal Resources (for Work Machines)
+
+### Documentation
+- API docs: https://api-docs.company.internal
+- Architecture decisions: https://wiki.company.com/adr
+- Style guide: https://styleguide.company.com
+- Onboarding: https://wiki.company.com/onboarding
+
+### Tools
+- Issue tracker: jira.company.com
+- Code review: github.company.com
+- CI/CD: jenkins.company.internal
+- Monitoring: grafana.company.internal
+
+## Additional Languages/Tools
+
+If this machine uses languages not in CLAUDE.md:
+
+### Java
+- Style: Google Java Style Guide
+- Build: Maven (follow company pom.xml template)
+- Testing: JUnit 5 + Mockito
+
+### Go
+- Style: Follow gofmt + company conventions
+- Testing: standard testing package
+- Linting: golangci-lint
+
+## Project-Specific Context
+
+### Current Projects
+- **Project A**: [Brief description, repo URL]
+- **Project B**: [Brief description, repo URL]
+
+### Local Development Setup
+- Docker registry: registry.company.internal:5000
+- Database: postgres://localhost:5432/dev
+- Redis: localhost:6379
+
+## Machine-Specific Paths
+
+- **Work repos**: ~/work/repos/
+- **Company tools**: ~/work/tools/
+- **Certificates**: ~/work/certs/
+- **VPN config**: ~/work/vpn/
+
+## Network/Infrastructure
+
+### VPN
+- Connect before git operations: `vpn-connect company`
+- All internal resources require VPN
+
+### SSH Keys
+- Work key: ~/.ssh/id_ed25519_work
+- GitHub config:
+  ```
+  Host github.company.com
+    HostName github.company.com
+    User git
+    IdentityFile ~/.ssh/id_ed25519_work
+  ```
+
+## Security & Compliance
+
+### Secrets Management
+- Use company vault: vault.company.internal
+- Never commit secrets (same as CLAUDE.md)
+- Use environment variables from company secrets manager
+
+### Compliance
+- GDPR compliance required for user data
+- Follow company security hardening guide
+- All dependencies must pass security scan
+
+## Overrides Summary
+
+Quick reference of what's different on this machine:
+
+| Setting | CLAUDE.md | This Machine |
+|---------|-----------|--------------|
+| Commit format | `type: PHASE - desc` | `[TICKET] type: desc` |
+| Git remote | Personal repos | Company GitHub Enterprise |
+| Review process | N/A | 2 approvals required |
+| Deployment | N/A | Via Jenkins |
+| Code coverage | Pragmatic | Minimum 80% |
+
+## Additional Notes
+
+[Any other context Claude should know about this machine]
+
+---
+
+**Remember**: This file is machine-specific and should never be committed to
+git. It's already excluded by `.gitignore`.
--- a/MULTI-MACHINE-SETUP.md
+++ b/MULTI-MACHINE-SETUP.md
@@ -0,0 +1,393 @@
+# Multi-Machine Setup Guide
+
+This guide explains how to use this Claude Code configuration across
+multiple machines (personal, work, etc.) without branch conflicts.
+
+## The Problem
+
+Using separate git branches for different machines creates merge conflicts,
+especially with frequently-changing files like `CLAUDE.md`.
+
+## The Solution: Layered Configuration
+
+Use a **layered approach** where machine-specific settings override shared
+settings without git conflicts.
+
+```
+~/.claude/                    # Shared (in git)
+├── CLAUDE.md                 # Universal preferences
+├── agents/                   # Shared agents
+└── commands/                 # Shared commands
+
+~/.claude/CLAUDE-LOCAL.md     # Machine-specific (NOT in git)
+```
+
+The `.gitignore` already excludes `CLAUDE-LOCAL.md` and `*-local.json`
+patterns.
+
+## Setup Instructions
+
+### First Machine (Already Done)
+
+You've already set this up:
+```bash
+cd ~/.claude
+git clone <repo-url> .
+claude setup-token  # Personal credentials
+```
+
+### Second Machine (e.g., Work Computer)
+
+1. **Clone the shared config:**
+   ```bash
+   cd ~/.claude
+   git clone <repo-url> .
+   ```
+
+2. **Set up work credentials:**
+   ```bash
+   claude setup-token  # Company-provided account
+   ```
+
+3. **Create local overrides** (if needed):
+   ```bash
+   cat > ~/.claude/CLAUDE-LOCAL.md <<'EOF'
+   # Local Overrides for [Machine Name]
+
+   This file contains machine-specific preferences that override or extend
+   CLAUDE.md. It is NOT tracked in git.
+
+   ## Work-Specific Standards
+
+   - Follow company ESLint config (located at ~/.eslintrc-work)
+   - Use company commit format: "TICKET-123: description"
+   - Deploy to company infrastructure
+
+   ## Additional Context
+
+   - Internal wiki: https://wiki.company.com
+   - Use company VPN for git operations
+   EOF
+   ```
+
+4. **Verify git status:**
+   ```bash
+   cd ~/.claude
+   git status
+   # Should NOT show CLAUDE-LOCAL.md
+   ```
+
+## How It Works
+
+### Shared Configuration (CLAUDE.md)
+
+Contains universal preferences that apply everywhere:
+- ✅ Code style standards (80 chars, 2 spaces, PEP 8, etc.)
+- ✅ TDD Ping-Pong workflow
+- ✅ Git workflow and commit conventions
+- ✅ Testing philosophy
+- ✅ Security best practices
+
+This is **tracked in git** and synced across all machines.
+
+### Local Overrides (CLAUDE-LOCAL.md)
+
+Contains machine-specific additions:
+- 🏢 Company-specific coding standards
+- 🔧 Machine-specific tool paths
+- 🌐 Network/infrastructure specific details
+- 📋 Additional context that doesn't apply universally
+
+This is **NOT tracked in git** (ignored by `.gitignore`).
+
+### Agent & Command Usage
+
+Since Claude Code reads from both files when present:
+
+1. On **personal machine**: Uses only `CLAUDE.md`
+2. On **work machine**: Uses `CLAUDE.md` + `CLAUDE-LOCAL.md`
+
+Agents and commands remain universal and work on all machines.
+
+## Example Use Cases
+
+### Use Case 1: Work Computer with Company Standards
+
+**CLAUDE-LOCAL.md on work machine:**
+```markdown
+# Work Computer Overrides
+
+## Company Coding Standards
+
+### JavaScript/TypeScript
+- Use company ESLint config: `@company/eslint-config`
+- All PRs require 2 approvals
+- Deploy via Jenkins pipeline
+
+### Git Workflow
+- Commit format: `[JIRA-123] feat: description`
+- Branch naming: `feature/JIRA-123-description`
+- Squash merge to main
+
+## Internal Resources
+- API docs: https://api-docs.company.internal
+- Style guide: https://styleguide.company.com
+- Architecture decisions: https://wiki.company.com/adr
+
+## Infrastructure
+- Dev: dev.company.internal
+- Staging: staging.company.internal
+- Production: company.com
+```
+
+### Use Case 2: Personal Machine with Project-Specific Setup
+
+**CLAUDE-LOCAL.md on personal machine:**
+```markdown
+# Personal Computer - Home Lab
+
+## Personal Projects
+
+### Container Registry
+- Registry: registry.home.lan:5000
+- Auth stored in ~/.docker/config.json
+
+### Git Remotes
+- Personal: git.hinrichs.dev
+- GitHub mirror: github.com/alexander
+
+### Backup Locations
+- NAS: /mnt/network/nas/backups
+- Offsite: rsync://offsite.backup.com
+```
+
+### Use Case 3: Different Programming Languages
+
+**CLAUDE-LOCAL.md on specialized machine:**
+```markdown
+# AI Research Machine
+
+## Additional Language Focus
+
+In addition to the languages in CLAUDE.md, this machine also uses:
+
+### Julia
+- Style: Follow JuliaFormatter defaults
+- Testing: Use Test.jl
+- Documentation: Documenter.jl
+
+### R
+- Style: Follow tidyverse style guide
+- Testing: testthat
+- Use renv for package management
+```
+
+## Syncing Updates
+
+### Pulling Updates from Shared Repo
+
+On any machine:
+```bash
+cd ~/.claude
+git pull origin main
+# Your CLAUDE-LOCAL.md is untouched
+```
+
+### Pushing Updates to Shared Repo
+
+On any machine:
+```bash
+cd ~/.claude
+# Edit CLAUDE.md, agents/, or commands/
+git add CLAUDE.md agents/ commands/
+git commit -m "feat: add new agent for X"
+git push origin main
+
+# CLAUDE-LOCAL.md is never committed
+```
+
+### Keeping Multiple Machines in Sync
+
+1. Make changes on **Machine A**
+2. Commit and push to git
+3. On **Machine B**: `git pull`
+4. Done! Machine-specific overrides remain intact
+
+## What Gets Synced vs Local
+
+### ✅ Synced Across All Machines (in git)
+
+```
+CLAUDE.md                 # Universal preferences
+agents/*.json             # Shared agents
+commands/*.md             # Shared commands
+settings.json             # Application settings
+README.md                 # Documentation
+.gitignore                # Ignore patterns
+```
+
+### 🔒 Stays Local (ignored by git)
+
+```
+.credentials.json         # Authentication (different per machine)
+CLAUDE-LOCAL.md           # Machine-specific overrides
+*-local.json              # Machine-specific settings
+history.jsonl             # Conversation history
+todos/                    # Session state
+projects/                 # Project state
+```
+
+## Best Practices
+
+### 1. Keep Universal Preferences in CLAUDE.md
+
+If something applies to **all your machines**, put it in `CLAUDE.md`:
+- Code style standards
+- General workflows
+- Testing philosophy
+- Security practices
+
+### 2. Use CLAUDE-LOCAL.md for Machine-Specific Context
+
+Only put in `CLAUDE-LOCAL.md` what differs between machines:
+- Company-specific standards
+- Internal URLs/resources
+- Machine-specific paths
+- Infrastructure details
+
+### 3. Never Commit Local Overrides
+
+```bash
+# Bad - don't do this
+git add CLAUDE-LOCAL.md
+
+# Good - it's already ignored
+cd ~/.claude
+git status
+# Should not list CLAUDE-LOCAL.md
+```
+
+### 4. Document What You Override
+
+In `CLAUDE-LOCAL.md`, be explicit about what you're changing:
+
+```markdown
+## Override: Commit Message Format
+
+CLAUDE.md specifies: `type: PHASE - description`
+
+On this machine, use: `[TICKET-123] type: description`
+```
+
+### 5. Test Changes Locally First
+
+Before committing changes to `CLAUDE.md`:
+```bash
+# Test on current machine
+# If it works, commit and push
+git add CLAUDE.md
+git commit -m "docs: update coding standards"
+git push
+
+# Pull on other machines and test
+```
+
+## Troubleshooting
+
+### Problem: Local Overrides Not Applied
+
+**Check if Claude Code is reading the file:**
+```bash
+cat ~/.claude/CLAUDE-LOCAL.md
+# Should exist and have content
+```
+
+Claude Code will automatically read both `CLAUDE.md` and `CLAUDE-LOCAL.md`
+when they exist in `~/.claude/`.
+
+### Problem: Accidentally Committed Local Overrides
+
+**Remove from git but keep file:**
+```bash
+cd ~/.claude
+git rm --cached CLAUDE-LOCAL.md
+git commit -m "chore: remove accidentally committed local overrides"
+git push
+
+# File still exists locally, just not tracked by git
+```
+
+### Problem: Merge Conflicts After Pull
+
+This shouldn't happen with this approach, but if it does:
+```bash
+cd ~/.claude
+git pull
+# Conflict in CLAUDE.md
+
+# Resolve conflict in CLAUDE.md
+# Your CLAUDE-LOCAL.md is never touched
+git add CLAUDE.md
+git commit
+```
+
+### Problem: Want to Share Local Override
+
+If you realize something in `CLAUDE-LOCAL.md` should be universal:
+
+1. Copy the content
+2. Add it to `CLAUDE.md`
+3. Remove from `CLAUDE-LOCAL.md`
+4. Commit and push `CLAUDE.md`
+
+```bash
+# Example: Moving work standards to universal
+cat CLAUDE-LOCAL.md  # Review what to move
+vim CLAUDE.md        # Add the universal parts
+vim CLAUDE-LOCAL.md  # Remove what was moved
+git add CLAUDE.md
+git commit -m "docs: add XYZ standards to universal config"
+git push
+```
+
+## Template for CLAUDE-LOCAL.md
+
+Copy this template to create your local overrides:
+
+```markdown
+# Local Overrides - [Machine Name/Purpose]
+
+Last updated: [Date]
+
+This file contains machine-specific preferences that override or extend
+CLAUDE.md. It is NOT tracked in git.
+
+## Machine Context
+
+- **Purpose**: [Personal/Work/Research/etc.]
+- **Primary languages**: [Languages used here]
+- **Authentication**: [Company/Personal account]
+
+## Overrides
+
+### [Category 1]
+[What's different on this machine]
+
+### [Category 2]
+[Additional context]
+
+## Additional Context
+
+### Internal Resources
+- [Links to internal docs]
+
+### Infrastructure
+- [Environment URLs, paths, etc.]
+
+### Special Considerations
+- [Anything else Claude should know]
+```
+
+---
+
+**Last Updated**: 2025-11-26
--- a/QUICK-REFERENCE.md
+++ b/QUICK-REFERENCE.md
@@ -0,0 +1,179 @@
+# Quick Reference
+
+## Multi-Machine Setup (TL;DR)
+
+### On Any New Machine
+
+```bash
+# 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
+
+```bash
+# 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
+
+```bash
+/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)
+
+```bash
+cd ~/.claude
+vim CLAUDE.md  # or agents/, commands/
+git add .
+git commit -m "feat: add XYZ"
+git push origin main
+```
+
+### Pull Updates (Work Machine)
+
+```bash
+cd ~/.claude
+git pull origin main
+# Your CLAUDE-LOCAL.md stays untouched
+```
+
+### Add Work-Specific Override
+
+```bash
+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:
+```bash
+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
+
+```bash
+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:
+
+```bash
+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
+
+```bash
+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**
--- a/README.md
+++ b/README.md
@@ -35,6 +35,8 @@ Quick workflow commands:

 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)
@@ -43,6 +45,19 @@ The `.gitignore` excludes machine-specific and sensitive data:
 - `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](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: