docs: add quick reference for multi-machine setup
This commit is contained in:
179
QUICK-REFERENCE.md
Normal file
179
QUICK-REFERENCE.md
Normal file
@@ -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**
|
||||
Reference in New Issue
Block a user