180 lines
4.1 KiB
Markdown
180 lines
4.1 KiB
Markdown
# 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**
|