Claude Configuration

My Claude Code configuration with custom settings, permissions, and agent templates.

Setup on a New Machine

1. Backup existing ~/.claude

mkdir -p ~/.claude-backup
cp -a ~/.claude/. ~/.claude-backup/

2. Clone the repo

git clone git@github.com:ldraney/claude-custom.git ~/claude-custom

3. Create symlinks

# Ensure ~/.claude exists (fresh machines may not have it yet)
mkdir -p ~/.claude

# Remove existing targets
rm -f ~/.claude/settings.json ~/.claude/settings.local.json ~/.claude/CLAUDE.md
rm -rf ~/.claude/plugins ~/.claude/commands ~/.claude/hooks ~/.claude/agents ~/.claude/skills

# Create symlinks
ln -s ~/claude-custom/settings.json ~/.claude/settings.json
ln -s ~/claude-custom/settings.local.json ~/.claude/settings.local.json
ln -s ~/claude-custom/CLAUDE.md ~/.claude/CLAUDE.md
ln -s ~/claude-custom/plugins ~/.claude/plugins
ln -s ~/claude-custom/commands ~/.claude/commands
ln -s ~/claude-custom/hooks ~/.claude/hooks
ln -s ~/claude-custom/agents ~/.claude/agents
ln -s ~/claude-custom/skills ~/.claude/skills

4. Port memory files (cross-platform)

Claude Code stores project memory under ~/.claude/projects/ using path-based directory names. The path prefix differs by OS:

• macOS: -Users-ldraney-{project}
• Linux: -home-ldraney-{project}

The repo tracks memory files under the macOS prefix. When setting up on Linux, copy each project's memory directory to the corresponding path:

for dir in ~/claude-custom/projects/-Users-ldraney*/; do
  project=$(basename "$dir" | sed 's/-Users-ldraney/-home-ldraney/')
  mkdir -p ~/.claude/projects/$project/memory
  cp "$dir"/memory/*.md ~/.claude/projects/$project/memory/ 2>/dev/null
done

Note: Project names may differ between machines (e.g., terraform-eks-mastery on Mac vs terraform-eks-lab on Linux). Check both names and copy to whichever exists locally. If local memory already exists and is richer than the repo version, keep the local copy.

What Gets Symlinked vs What Stays Local

Symlinked (version-controlled)

• settings.json — model preferences
• settings.local.json — command permissions and security
• CLAUDE.md — Devy's brain (global SOP)
• plugins/ — Claude plugins configuration
• commands/ — custom slash commands
• hooks/ — event hooks
• agents/ — agent templates and config
• skills/ — custom skills

Stays local (gitignored, regenerates)

.credentials.json, cache/, debug/, file-history/, history.jsonl, image-cache/, logs/, paste-cache/, session-env/, shell-snapshots/, stats-cache.json, statsig/, tasks/, telemetry/, todos/

Partially tracked

• projects/ — only memory/ subdirectories are tracked in git. Everything else is local-only.
• plugins/ — symlinked and version-controlled, but plugins/marketplaces/ is gitignored. Claude Code manages marketplace plugin repos itself; they regenerate automatically.

Repo-Only Reference Directories

These directories live in the repo for reference but are not symlinked into ~/.claude/.

• docs/ — Curated Claude Code documentation: official Anthropic docs, best practices, and configuration guides (installation notes, memory management).
• dotfiles/ — Index of all dotfile repos (zshrc-custom, oh-my-zsh-custom, tmux-custom, nvim-custom, etc.) with their clone URLs, local paths, and setup commands.
• github/ — Cached snapshot of GitHub repositories for quick reference and tooling.
• patterns/ — Reusable orchestration patterns and project templates (e.g., Docker hello-world scaffold, nvim-agent template, Docker app-creation workflow).

Custom Commands

Custom slash commands live in commands/ as markdown files. Each .md file becomes a /command-name slash command in Claude Code.

Directory Structure

commands/
└── update-docs.md     # /update-docs — post-merge documentation chain walk

Convention

• One markdown file per command
• Filename becomes the command name (e.g., update-docs.md -> /update-docs)
• Commands are prompts, not scripts -- they tell Claude what to do
• Commands should be self-contained: an agent can follow the prompt without reading external SOPs
• Commands should be idempotent (safe to run multiple times)

Deploy

Commands are symlinked from ~/claude-custom/commands/ to ~/.claude/commands/ (see Setup). New commands are available immediately after creating the file -- no restart required.

Commands vs Skills

Both appear as slash commands. The difference:

• Commands (commands/*.md) -- simple markdown prompts. No frontmatter required.
• Skills (skills/*/SKILL.md) -- support YAML frontmatter for context: fork, agent:, argument-hint:, etc. Delegate to pal-e-docs skill notes.

Use commands for workflows that should be self-contained. Use skills for workflows that need agent dispatch or context forking. Existing skills delegate to pal-e-docs skill notes; commands are self-contained replacements that work without pal-e-docs access (e.g., for agents that only have repo + Forgejo).

Agent System

Directory Structure

agents/
└── nvim-minion/        # Individual agent directory
    ├── config.json     # Agent configuration
    ├── template.md     # Agent prompt template
    └── patterns.md     # Working command patterns

Agent Organization

Each agent gets its own directory under agents/ containing:

• config.json - Agent metadata, environment, capabilities, known issues
• template.md - Reusable prompt template for spawning the agent
• patterns.md - Documented working commands and verification steps

Available Agents

• nvim-minion - Controls nvim instance in tmux for file operations

Usage Pattern

1. Define Agent: Create agent directory with config files
2. Document Patterns: Capture working commands as you discover them
3. Create Templates: Build reusable prompt templates
4. Spawn Agent: Load template + config + specific task instructions