claude-settings/MULTI-MACHINE-SETUP.md

# 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