alexander/claude-settings
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: add multi-machine setup guide

Browse Source 
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>
This commit is contained in:
Alexander Hinrichs
2025-11-26 19:45:34 +01:00
parent 57f52fd4b7
commit 076a7be7e6
4 changed files with 570 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

393
MULTI-MACHINE-SETUP.md Normal file
View File

@@ -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