Claude Code Configuration

A comprehensive Claude Code configuration repository that combines dynamic upstream integration from solatis/claude-config with custom agent templates, skills, and global guidelines.

Features

• Dynamic Upstream Integration: Integrates solatis/claude-config as a git subtree for automatic updates
• Custom Agent Templates: Pre-configured agents for common development tasks (coder, researcher, reviewer, tester)
• Domain-Organized Skills: Reusable skills categorized by technology domain
  • Python: Hexagonal architecture, testing patterns, Alembic migrations
  • API: FastAPI REST API patterns
  • Frontend: Next.js + TanStack Query patterns
• Path-Scoped Rules (NEW): Language/framework conventions that auto-load based on file patterns
  • Python, TypeScript, Rust, FastAPI, Next.js
• Optimized Global Guidelines: Minimal CLAUDE.md with universal principles only
• Settings Template: Permissions configuration (no secrets)
• Chezmoi Integration: Designed to work seamlessly with chezmoi dotfile management

Recent Updates (Jan 2026)

Configuration Optimization

• 76% reduction in global CLAUDE.md size (187 → 44 lines)
• New rules/ directory: Path-scoped language/framework conventions
• Progressive disclosure: Rules auto-load only for relevant file types
• Better organization: Universal (CLAUDE.md) vs language-specific (rules/) vs project-specific (project CLAUDE.md)

Rules Directory

Language and framework conventions now live in rules/ with YAML frontmatter for path scoping:

• python.md - Auto-loads for **/*.py files
• typescript.md - Auto-loads for **/*.ts, **/*.tsx files
• rust.md - Auto-loads for **/*.rs files
• fastapi.md - Auto-loads for **/adapters/api/**/*.py files
• nextjs.md - Auto-loads for **/app/**/*.tsx files

Repository Structure

claude-config/
├── upstream/                       # solatis/claude-config (git subtree)
│   ├── agents/                     # Upstream agents (debugger, developer, etc.)
│   ├── skills/                     # Upstream skills (analyze, planner, etc.)
│   └── output-styles/              # Upstream output styles
│
├── agents/                         # Custom agent templates
│   ├── coder.md
│   ├── researcher.md
│   ├── reviewer.md
│   └── tester.md
│
├── skills/                         # Custom skills (categorized)
│   ├── python/
│   │   ├── hexagonal-architecture/
│   │   ├── testing-patterns/
│   │   └── alembic-migrations/
│   ├── api/
│   │   └── fastapi-rest-api/
│   └── frontend/
│       └── nextjs-tanstack/
│
├── rules/                          # Path-scoped conventions (NEW)
│   ├── python.md                   # Python 3.12+ conventions
│   ├── typescript.md               # TypeScript/JavaScript conventions
│   ├── rust.md                     # Rust and PyO3 conventions
│   ├── fastapi.md                  # FastAPI patterns
│   └── nextjs.md                   # Next.js App Router patterns
│
├── CLAUDE.md                       # Universal development guidelines (optimized)
├── settings.json.template          # Permissions configuration (no secrets)
│
├── docs/                           # Documentation
│   ├── integration-guide.md
│   ├── upstream-sync.md
│   ├── customization.md
│   └── architecture.md
│
└── scripts/                        # Utility scripts
    ├── sync-upstream.sh
    ├── install-standalone.sh
    └── validate-config.sh

MCP Server Configuration

This repository includes configurations for MCP (Model Context Protocol) servers.

Configured MCP Servers:

• context7 - Documentation lookup server (requires CONTEXT7_API_KEY env var)
• serena - Semantic code analysis and navigation

Setup:

MCP server API keys are stored in encrypted secrets (~/.config/zsh/secrets.zsh), and server definitions use environment variable substitution for security.

To apply MCP server configurations on a new machine:

# 1. Ensure secrets are loaded (chezmoi applies this automatically)
source ~/.config/zsh/secrets.zsh

# 2. Run the MCP setup script
~/.claude/scripts/setup-mcp-servers.sh

# 3. Verify servers are configured
claude mcp list

Adding New MCP Servers:

1. Add API key to encrypted secrets (in your chezmoi dotfiles)
2. Add server definition to mcp-servers.json using ${ENV_VAR} for secrets
3. Run scripts/setup-mcp-servers.sh to apply
4. Commit changes to this repository

Installation

Option 1: Chezmoi Integration (Recommended)

If you're using chezmoi for dotfile management:

1. Edit .chezmoiexternal.toml in your chezmoi source directory:

[".claude"]
    type = "git-repo"
    url = "ssh://git@nas.tortoise-hamlet.ts.net:222/jmz/claude-config.git"
    refreshPeriod = "168h"
    exact = false
    exclude = [".git/**", "docs/**", "scripts/**", ".gitignore", "LICENSE", "README.md"]

2. Apply the configuration:

chezmoi update

This will deploy the configuration to ~/.claude/ with merged content from both upstream and custom sources.

For detailed integration instructions, see docs/integration-guide.md.

Option 2: Standalone Installation

For direct installation without chezmoi:

# Clone the repository
git clone ssh://git@nas.tortoise-hamlet.ts.net:222/jmz/claude-config.git ~/.claude

# Copy settings template (review and customize)
cp ~/.claude/settings.json.template ~/.claude/settings.json

# Verify installation
~/.claude/scripts/validate-config.sh

Or use the provided installation script:

# Clone and run installer
git clone ssh://git@nas.tortoise-hamlet.ts.net:222/jmz/claude-config.git /tmp/claude-config
cd /tmp/claude-config
./scripts/install-standalone.sh

Usage

Once installed, Claude Code will automatically have access to:

Custom Agents

Use custom agents for specific workflows:

# In Claude Code
"Use the coder agent to implement this feature"
"Use the reviewer agent to analyze this PR"

Skills

Skills activate automatically based on task context, or can be explicitly invoked:

# Automatic activation
"Add a new API endpoint for comments"  # Uses fastapi-rest-api skill

# Explicit invocation
"Following hexagonal-architecture, create a notification system"

Global Guidelines

The CLAUDE.md file provides global Python development guidelines that Claude Code references automatically.

Maintenance

Syncing Upstream Changes

To pull updates from solatis/claude-config:

cd /path/to/claude-config
./scripts/sync-upstream.sh
git push origin master

# If using chezmoi
chezmoi update

For detailed sync instructions, see docs/upstream-sync.md.

Adding Custom Skills

1. Create skill directory in appropriate category:

mkdir -p skills/python/new-skill

2. Create SKILL.md following the skill format (see existing skills for examples)

3. Commit and push:

git add skills/python/new-skill/
git commit -m "feat: add new-skill for Python development"
git push origin master

4. If using chezmoi, apply the update:

chezmoi update

For detailed customization instructions, see docs/customization.md.

Adding Custom Agents

1. Create agent template in agents/ directory:

vim agents/my-agent.md

2. Follow the agent template format (see existing agents for examples)

3. Commit and push:

git add agents/my-agent.md
git commit -m "feat: add my-agent template"
git push origin master

File Deployment Mapping (Chezmoi)

When deployed via chezmoi, files are merged as follows:

Source in claude-config repo	Deployed to ~/.claude/
CLAUDE.md	~/.claude/CLAUDE.md
settings.json.template	~/.claude/settings.json (managed)
agents/*.md	~/.claude/agents/*.md
skills/**/*	~/.claude/skills/**/*
upstream/agents/*.md	~/.claude/agents/*.md (merged)
upstream/skills/**/*	~/.claude/skills/**/* (merged)
upstream/output-styles/*	~/.claude/output-styles/*

Files excluded from deployment: .git/, docs/, scripts/, .gitignore, LICENSE, README.md

Documentation

• Integration Guide - Chezmoi integration steps
• Upstream Sync - How to sync from solatis/claude-config
• Customization - How to add custom skills/agents
• Architecture - Design decisions and rationale

Security

• No secrets are stored in this repository in plain text
• settings.json.template contains only permissions configuration
• Machine-specific settings belong in settings.local.json (gitignored)
• Runtime data (history, cache, etc.) is gitignored
• Suitable for public sharing and version control

Contributing

This is a personal configuration repository, but feel free to:

1. Fork and adapt for your own use
2. Submit issues for bugs or suggestions
3. Share your own skill/agent templates

License

MIT License - see LICENSE file for details.

Acknowledgments

• solatis/claude-config - Upstream configuration source
• Anthropic - Claude Code and Claude AI
• chezmoi - Dotfile management

Version

Last Updated: 2026-01-01 Repository: ssh://git@nas.tortoise-hamlet.ts.net:222/jmz/claude-config.git Branch: master