LLM Environment Management

A modular system for managing Claude Code configuration using GNU stow for symlink management and layered settings merging. Provides a clean separation between base, personal, and work configurations.

Key Features

🔗 Stow-based: Simple symlink management using industry-standard tool 🎯 Layered Settings: Base → Personal → Work configuration merging 📦 Modular: Organized skills, agents, and commands 🔄 Auto-merge: Git hooks automatically merge settings after pulls 🐳 Docker-ready: Mount readonly configuration in containers

Directory Structure

llmenv/
├── claude-code/           # Stow package for Claude Code configuration
│   └── .claude/           # Configuration directory (stowed to ~/.claude/)
│       ├── CLAUDE.md                      # Consolidated guidelines
│       ├── settings.base.json             # Base configuration (committed)
│       ├── settings.personal.json         # Personal overrides (committed)
│       ├── settings.wealthsimple.json     # Work config (gitignored)
│       ├── settings.json                  # Merged output (gitignored, generated)
│       ├── skills/                        # Language-specific skills
│       │   ├── typescript.md
│       │   ├── ruby.md
│       │   ├── react.md
│       │   └── terraform.md
│       ├── agents/                        # Specialized agents
│       │   ├── code-reviewer.md
│       │   ├── pr-helper.md
│       │   ├── typescript-expert.md
│       │   └── ... (9 total)
│       └── commands/
│           └── pr-wrapup.md
├── bin/
│   └── merge-settings     # Python script for recursive settings merge
├── scripts/
│   └── hooks/
│       └── post-merge     # Git hook for auto-merge
└── docker/                # Docker setup files

Installation

1. Install Configuration with Stow

Use GNU stow to symlink the .claude directory to your home directory:

# From the llmenv directory
cd /path/to/llmenv
stow -t ~ claude-code

This creates ~/.claude/ as a symlink to llmenv/claude-code/.claude/.

2. Merge Settings

Generate the final settings.json by merging base, personal, and work settings:

# Add llmenv/bin to your PATH (or use full path)
export PATH="$PATH:/path/to/llmenv/bin"

# Merge settings
merge-settings --verbose

3. Setup Git Hook (Optional but Recommended)

Auto-merge settings after git operations:

# From the llmenv directory
ln -s ../../scripts/hooks/post-merge .git/hooks/post-merge

Configuration

Layered Settings

Settings are merged in order: base → personal → work

1. Base Settings (settings.base.json): Core configuration, committed to repo
2. Personal Settings (settings.personal.json): Your personal overrides, committed to repo
3. Work Settings (settings.wealthsimple.json): Work-specific config, gitignored

Merge Rules:

• Nested objects: Deep recursive merge
• Arrays: Concatenate (useful for statusLine.context)
• Primitives: Last value wins

Example: Adding Personal Settings

Edit claude-code/.claude/settings.personal.json:

{
  "statusLine": {
    "context": [
      "My custom status line item"
    ]
  },
  "hooks": {
    "myCustomHook": {
      "command": "echo 'Hello from personal config'",
      "description": "My personal hook"
    }
  }
}

Then merge:

merge-settings --verbose

Example: Adding Work Settings

Create claude-code/.claude/settings.wealthsimple.json:

{
  "enabledPlugins": {
    "superpowers@ws-claude-marketplace": true
  },
  "extraKnownMarketplaces": {
    "ws-claude-marketplace": {
      "source": {
        "source": "github",
        "repo": "wealthsimple/ws-claude-marketplace"
      }
    }
  }
}

Then merge:

merge-settings --verbose

Usage

merge-settings Command

# Basic merge with defaults
merge-settings

# Verbose output showing merge operations
merge-settings --verbose

# Dry run to preview merged output
merge-settings --dry-run

# Custom file locations
merge-settings -b ~/.claude/settings.base.json -p ~/.claude/settings.personal.json

Options:

• -o, --output: Output file (default: ~/.claude/settings.json)
• -b, --base: Base settings file (default: ~/.claude/settings.base.json)
• -p, --personal: Personal settings file (default: ~/.claude/settings.personal.json)
• -w, --work: Work settings file (default: ~/.claude/settings.wealthsimple.json)
• --dry-run: Print merged output without writing
• -v, --verbose: Show detailed merge operations

Updating Configuration

Since .claude is a symlink to the repo, you can edit files directly:

# Edit base guidelines
vim ~/.claude/CLAUDE.md

# Edit a skill
vim ~/.claude/skills/typescript.md

# Edit an agent
vim ~/.claude/agents/code-reviewer.md

# Merge settings after changes
merge-settings --verbose

Changes are immediately reflected in Claude Code since it reads from the symlinked location.