Claude Code Infrastructure

Overview

This directory contains Claude Code infrastructure that is shared across machines and tracked in git. It includes agents, skills, hooks, plugins, and settings for the Personal AI Infrastructure (PAI).

Inspired by Daniel Miessler’s Personal AI Infrastructure.

Directory Structure

dots/.config/claude/
├── README.md            # This file
├── agents/              # Specialized AI agents
├── hooks/               # Event-driven automation hooks
├── plugins/             # Custom plugins (session-manager, etc.)
├── skills/              # Modular AI capabilities
│   ├── CORE/           # Core operating principles
│   │   ├── CONSTITUTION.md
│   │   ├── SKILL.md
│   │   ├── prompting.md
│   │   └── history-system.md    # History/notes integration
│   ├── homelab/        # Homelab infrastructure management
│   ├── golang/         # Go development best practices
│   ├── nix/            # Nix/NixOS best practices
│   └── notes/          # Note-writing workflow (denote)
└── settings.json        # Shared settings (tracked in git)

~/.config/claude/
├── agents/             -> /home/vincent/src/home/dots/.config/claude/agents/
├── hooks/              -> /home/vincent/src/home/dots/.config/claude/hooks/
├── plugins/            -> /home/vincent/src/home/dots/.config/claude/plugins/
├── skills/             -> /home/vincent/src/home/dots/.config/claude/skills/
├── settings.json       -> /home/vincent/src/home/dots/.config/claude/settings.json
├── settings.local.json # Machine/project-specific (NOT tracked)
└── history/            # Captured sessions and logs (synced via Syncthing)
    ├── sessions/       # Work session summaries
    ├── learnings/      # Problem-solving insights
    ├── research/       # Deep investigations
    ├── execution/      # Command outputs
    ├── decisions/      # Architecture decisions
    └── tool-outputs/   # Captured tool executions (via hooks)

~/.claude/              -> ~/.config/claude/ (backward compatibility)

Note: History entries in ~/.config/claude/history/ are interconnected with denote notes in ~/desktop/org/notes/ using the :history: tag. History is synced across machines via Syncthing.

Migration Note: Claude Code now uses XDG Base Directory specification (~/.config/claude/). For backward compatibility, ~/.claude/ is symlinked to ~/.config/claude/ so older documentation and hooks continue to work.

Components

Agents (agents/)

Specialized AI agents with specific expertise:

engineer - Software engineering and implementation
architect - Architecture and PRD creation
designer - UX/UI design and accessibility
claude-researcher - Web research with WebSearch
researcher - Comprehensive multi-tool research

See agents/ for individual agent documentation.

Skills (skills/)

CORE Skills

The CORE skills auto-load and define fundamental operating principles:

CONSTITUTION.md: Personal AI philosophy and architectural principles
SKILL.md: Core behaviors, response patterns, and workflows
prompting.md: Effective prompting guidelines
history-system.md: Integration between history capture and denote notes

Domain-Specific Skills

homelab: Managing NixOS infrastructure in ~/src/home repository
golang: Go development patterns, testing, and Nix integration
nix: NixOS/home-manager configuration best practices
notes: Note-taking in denote format with org-mode
Art: Visual content generation and Mermaid diagrams
Createskill: Skill creation and validation

See each skill’s SKILL.md for documentation.

Hooks (hooks/)

Event-driven automation in TypeScript (~/.config/claude/hooks/):

initialize-session.ts - SessionStart: Sets terminal title, logs session start
capture-tool-output.ts - PostToolUse: Logs tool executions to JSONL
save-session.ts - SessionEnd: Prompts to save session summary
validate-write-path.ts - PreToolUse: Validates file paths and filenames

See dots/config/claude/hooks/ for source code.

Plugins (plugins/)

Custom Claude Code plugins:

session-manager: Provides /save-session command for creating session summaries

Installation and Setup

Setup on New Machine

To set up Claude Code infrastructure on a new machine:

# Clone the home repository
cd ~/src/home

# Run make to create all symlinks
cd dots
make all

# This will link:
# - ~/.config/claude/skills/
# - ~/.config/claude/agents/
# - ~/.config/claude/hooks/
# - ~/.config/claude/plugins/
# - ~/.config/claude/settings.json
# - ~/.claude/ -> ~/.config/claude/ (backward compatibility)

# Optionally create machine-specific settings
cat > ~/.config/claude/settings.local.json <<EOF
{
  "permissions": {
    "allow": [
      "Bash(*)"
    ]
  }
}
EOF

Makefile Targets

# Link individual components
make claude-skills     # Link skills
make claude-agents     # Link agents
make claude-hooks      # Link hooks
make claude-plugins    # Link plugins (session-manager, etc.)
make claude-settings   # Link settings.json

# Link everything
make all

Settings Strategy

settings.json (Shared)

Location: dots/.config/claude/settings.json (symlinked to ~/.config/claude/settings.json)

Purpose: Shared configuration across all machines

Contains:

Hook configurations
Enabled plugins list
General preferences (alwaysThinkingEnabled, etc.)
Shared MCP server configs

Why shared:

Consistent hooks across machines
Same plugins enabled everywhere
Synchronized preferences
Uses absolute paths that are consistent (/home/vincent/.config/claude/...)

settings.local.json (Machine-Specific)

Location: ~/.config/claude/settings.local.json or project .claude/settings.local.json

Purpose: Machine or project-specific overrides

Contains:

Permissions (project-specific)
Machine-specific paths
Local environment variables
Project-specific plugin configs

Not tracked in git: Machine/project-specific configuration

Settings Precedence

Claude Code merges settings in this order:

settings.json (base configuration)
settings.local.json (overrides)

Local settings always take precedence over shared settings.

Permissions

Permissions are intentionally kept in settings.local.json because:

Different projects need different permissions
Security policies may vary by machine
Easier to audit per-project permissions

Example project-specific permissions:

{
  "permissions": {
    "allow": [
      "Bash(make:*)",
      "Bash(nix:*)",
      "WebFetch(domain:docs.example.com)"
    ]
  }
}

Usage

Skills

Skills are automatically available in Claude Code sessions. No special invocation needed - Claude will reference them contextually based on the task.

Editing Skills

Skills are plain markdown files that can be edited directly:

# Edit a skill
cd ~/src/home/dots/.config/claude/skills
vim homelab/SKILL.md

# Changes are immediately available (no rebuild required)

Adding New Skills

Create a new directory in .config/claude/skills/
Add a SKILL.md file with the skill content
Skills are automatically discovered by Claude Code

Example:

mkdir -p .config/claude/skills/rust
cat > .config/claude/skills/rust/SKILL.md << 'EOF'
# Rust Development Skill

## Purpose
Guide Rust development following best practices.

## Best Practices
- Use cargo for builds
- Write comprehensive tests
- Follow Rust idioms
EOF

History System

The History system automatically captures and documents AI interactions to build a comprehensive knowledge base.

Adapted from the Personal AI Infrastructure History System.

Purpose

Capture ALL valuable work for future reference, learning, and analysis.

Directory Structure

~/.config/claude/history/
├── raw-outputs/              # Raw event logs (JSONL)
│   └── YYYY-MM/
│       └── YYYY-MM-DD_all-events.jsonl
│
├── learnings/                # Problem-solving narratives
│   └── YYYY-MM/
│       └── YYYY-MM-DD-HHMMSS_LEARNING_description.md
│
├── sessions/                 # Work logs and summaries
│   └── YYYY-MM/
│       └── YYYY-MM-DD-HHMMSS_SESSION_description.md
│
├── research/                 # Analysis and investigations
│   └── YYYY-MM-DD_topic/
│       ├── analysis.md
│       ├── findings.md
│       └── sources.md
│
├── execution/                # Command outputs and results
│   └── YYYY-MM/
│       └── YYYY-MM-DD-HHMMSS_command-name.txt
│
└── upgrades/                 # Architectural changes
    ├── deprecated/
    │   └── YYYY-MM-DD_upgrade-name/
    │       ├── README.md
    │       └── [deprecated files]
    └── YYYY-MM-DD_upgrade-description.md

What Gets Captured

Automatic Capture (via hooks)

Session start and completion events
Tool usage and command execution
All events logged to raw-outputs/YYYY-MM/YYYY-MM-DD_all-events.jsonl

Manual Capture (by AI)

Research completed → save to research/
Learning captured → save to learnings/
Work summary → save to sessions/
Command outputs → save to execution/

Workflow-Driven

Some skills auto-save outputs
Example: research skill → history/research/

Scratchpad vs History

Scratchpad (`~/.config/claude/scratchpad/`)

Temporary working files
Tests and experiments
Draft outputs
Delete when done

History (`~/.config/claude/history/`)

Permanent valuable outputs
Research findings
Learnings and insights
Session logs
Keep forever

Critical Rule

When in doubt, save to history!

Benefits

Learn from history: Reference past solutions to similar problems
Track evolution: See how approaches and understanding develop over time
Share knowledge: Documentation is automatically created
Context building: AI can reference past interactions for better assistance
Institutional memory: Build a knowledge base over time

Integration with Denote Notes

The History system is interconnected with the denote note-taking system in ~/desktop/org/notes/.

Tag-Based Integration

All history-related notes use the :history: tag plus category-specific tags:

:history:session: - Work session summaries
:history:learning: - Problem-solving insights
:history:research: - Deep investigations
:history:decision: - Architecture decisions
:history:execution: - Command execution logs

Bidirectional Links

History entries in ~/.config/claude/history/ and denote notes cross-reference each other:

From history to notes (markdown links in .md files):

## Related Notes
- [Topic Note](~/desktop/org/notes/20251203T151822--topic__history_session.org)

From notes to history (org-mode links in .org files):

* Related History
- [[file:~/.config/claude/history/sessions/2025-12/2025-12-03-150000_SESSION_implementation.md][Implementation Session]]

Note on formats: History uses markdown (.md), notes use org-mode (.org). Both are plain text, searchable, and git-friendly. Use appropriate link syntax for each format.

Finding History-Linked Notes

# All history notes (by tag)
ls ~/desktop/org/notes/*__history*.org

# Automated history notes (by pkai signature)
ls ~/desktop/org/notes/*==pkai*.org

# Specific category
ls ~/desktop/org/notes/*__history_learning*.org
ls ~/desktop/org/notes/*==pkai*__history_session*.org

# Search across both systems
rg "topic" ~/.config/claude/history/ ~/desktop/org/notes/*__history*.org

Signature: pkai stands for “Personal Knowledge Automated Infrastructure” and identifies notes created by the history system. This makes it easy to distinguish automated notes from manual ones.

When to Use Each System

History directory (~/.config/claude/history/): Chronological tracking, raw captures, session-by-session
Denote notes (~/desktop/org/notes/): Topic-based organization, long-term reference, knowledge building
Both: Significant learnings, important decisions, research worth sharing

See skills/CORE/history-system.md for complete integration details.

Implementation Status

Current implementation (manual workflow):

Manually create history entries for significant work
Manually create denote notes with :history: tag
Cross-link between history and notes
Organize by category and date

Future automation (with hooks):

Automatic session capture via hooks
Auto-suggest history entries for significant work
Searchable indexing across both systems
AI-assisted note generation from history

Philosophy

Deterministic Over Probabilistic

Prefer structured, testable, code-based solutions over pure prompt engineering.

Progressive Disclosure

Load context in three tiers:

Essential: Core principles always loaded
Contextual: Task-specific knowledge loaded as needed
Reference: Detailed docs retrieved on demand

Code Before Prompts

Build CLI tools and code first, then wrap with AI assistance. Code is:

Testable
Versioned
Deterministic
Shareable

Version Control

Skills are tracked in the home repository:

cd ~/src/home
git add dots/.config/claude/
git commit -m "feat: Update Claude AI skills"

Benefits of This Approach

Consistency: Same agents, skills, hooks, and plugins everywhere
Version Control: Infrastructure tracked in git
Flexibility: Machine-specific overrides when needed
Portability: Easy to set up on new machines
Maintainability: Single source of truth for shared config
Instant updates: Edit skills, changes are immediate
No rebuilds: No NixOS rebuild required (for skills/agents/plugins)
Iterative: Easy to refine and experiment

Troubleshooting

Symlinks not working?

cd ~/src/home/dots
make all

Settings not loading?

# Check symlink
ls -la ~/.config/claude/settings.json

# Should point to: /home/vincent/src/home/dots/.config/claude/settings.json

# Check backward compatibility symlink
ls -la ~/.claude
# Should point to: ~/.config/claude

Hooks not running?

# Check settings.json has hooks configured
cat ~/.config/claude/settings.json | grep -A 10 hooks

# Verify hook binaries are in PATH
ls ~/.config/claude/hooks/initialize-session.ts
ls ~/.config/claude/hooks/capture-tool-output.ts
ls ~/.config/claude/hooks/save-session.ts

History not syncing?

# Verify Syncthing is running
systemctl --user status syncthing

# Check if claude-history folder is configured
# After rebuilding NixOS with updated globals.nix

Agents: See individual agent .md files in agents/
Skills: See each skill’s SKILL.md in skills/
Hooks: See ~/.config/claude/hooks/ (TypeScript, run via bun)
History System: See skills/CORE/history-system.md
Repository Instructions: See ~/src/home/CLAUDE.md

Claude Code Infrastructure

Overview

Directory Structure

Components

Agents (agents/)

Skills (skills/)

CORE Skills

Domain-Specific Skills

Hooks (hooks/)

Plugins (plugins/)

Installation and Setup

Setup on New Machine

Makefile Targets

Settings Strategy

settings.json (Shared)

settings.local.json (Machine-Specific)

Settings Precedence

Permissions

Usage

Skills

Editing Skills

Adding New Skills

History System

Purpose

Directory Structure

What Gets Captured

Automatic Capture (via hooks)

Manual Capture (by AI)

Workflow-Driven

Categories

Learnings

Sessions

Research

Execution

Upgrades

Scratchpad vs History

Scratchpad (~/.config/claude/scratchpad/)

History (~/.config/claude/history/)

Critical Rule

Benefits

Integration with Denote Notes

Tag-Based Integration

Bidirectional Links

Finding History-Linked Notes

When to Use Each System

Implementation Status

Philosophy

Deterministic Over Probabilistic

Progressive Disclosure

Code Before Prompts

Version Control

Benefits of This Approach

Troubleshooting

Symlinks not working?

Settings not loading?

Hooks not running?

History not syncing?

Related Documentation

Scratchpad (`~/.config/claude/scratchpad/`)

History (`~/.config/claude/history/`)