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:

cd ~/.claude
git clone <repo-url> .
claude setup-token  # Personal credentials

Second Machine (e.g., Work Computer)

1. Clone the shared config:

   cd ~/.claude
   git clone <repo-url> .
   

2. Set up work credentials:

   claude setup-token  # Company-provided account
   

3. Create local overrides (if needed):

   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:

   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:

# 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:

# 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:

# 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:

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

Pushing Updates to Shared Repo

On any machine:

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

# 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:

## 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:

# 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:

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:

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:

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

# 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:

# 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