Minoan Claude Code Configuration

A curated ~/.claude/ configuration for professional development workflows — skills, hooks, CLI tools, slash commands, MCP servers, and a VS Code extension.

Repository Map

claude-code-minoan/
├── skills/                      # 66 custom skills across 5 categories
│   ├── core-development/        #   Architecture, task tracking, code search
│   ├── integration-automation/  #   Local ML, RAG, browser, telephony
│   ├── design-media/            #   Frontend, image gen, TTS, vision
│   ├── research/                #   Academic, web search, scraping
│   └── planning-productivity/   #   Session tracking, swarms, iteration loops
├── hooks/                       # 44 lifecycle hooks (handoffs, terminal UX, lint-on-write, mycelium)
├── commands/                    # 49 slash commands (workflows, planning, code review)
├── agents/                      # Custom subagents (librarian, etc.)
├── scripts/                     # Standalone utilities (syspeek, screenshot-rename, plugins)
├── bin/                         # CLI tools (session tracker, launchers, tmux)
├── lib/                         # Shared libraries (tracker-utils.js)
├── extensions/                  # VS Code Claude Session Tracker extension
├── ghostty/                     # Ghostty terminal config for Claude Code
├── sounds/                      # Notification audio
└── docs/global-setup/          # Full ~/.claude/ structure reference

Each folder has its own README with setup instructions, examples, and credits.

Quick Start

# 1. Clone
git clone https://github.com/your-org/claude-code-minoan.git
cd claude-code-minoan

# 2. Start with the global CLAUDE.md template
cp CLAUDE.template.md ~/.claude/CLAUDE.md
# Edit ~/.claude/CLAUDE.md — add your Identity section, uncomment Always Loaded refs

# 3. Install skills
cp -r skills/*/* ~/.claude/skills/

# 4. Install commands
cp -r commands/* ~/.claude/commands/

# 5. Install hooks + sounds
cp -r hooks/* ~/.claude/hooks/
cp -r sounds ~/.claude/sounds/
chmod +x ~/.claude/hooks/*.py ~/.claude/hooks/*.sh

# 6. Install CLI tools
cp bin/* ~/.local/bin/
mkdir -p ~/.claude/lib && cp lib/* ~/.claude/lib/

# 7. Install VS Code extension
cd extensions/claude-session-tracker
npm install && npm run compile
npx @vscode/vsce package --no-dependencies
code --install-extension claude-session-tracker-*.vsix

Configure hooks in ~/.claude/settings.json — see hooks/README.md for the full settings block.

Deep Dives

Skills — 66 skills across 5 categories

Custom Claude Code capabilities organized by domain. Each skill has a SKILL.md entry point, optional scripts, and reference docs.

Highlights:

Toggle skills on/off: python3 ~/.claude/skills/skill-toggle/scripts/skill_toggle.py list

Claude 4.6 Prompting Alignment (Feb 2026): All agentic skills (minoan-swarm, super-ralph-wiggum, firecrawl, osgrep-reference, claude-agent-sdk, skill-optimizer) updated to follow Anthropic's Claude 4.6 prompting best practices—softer tool-use language, factual quality criteria over motivational framing, effort parameter guidance, structured state management.

Memory Hierarchy: The claude-md-manager skill documents the full 6-tier memory system — managed policy, project memory, project rules (.claude/rules/), user memory, project local, and auto memory. See also docs/global-setup/README.md for how this complements the Claudicle soul architecture.

Hooks — Lifecycle event scripts

Scripts that run in response to Claude Code events — terminal UX, crash-resilient session handoffs, cross-repo git tracking, and multi-response sampling.

UserPromptSubmit ──→ multi-response-prompt.py    (/5x trigger)
PreToolUse ────────→ on-thinking.sh              (🔴 repo-icon + title)
                   → git-track.sh               (Bash: log git commands to JSONL)
PostToolUse ───────→ git-track-post.sh           (Bash: capture commit hashes)
                   → plan-rename.py              (Write/Edit/MultiEdit: random→dated slug)
                   → plan-session-rename.py      (Write: auto-title session from plan H1)
                   → lint-on-write.py            (Write/Edit: ESLint/Clippy/Ruff + custom rules)
                   → mycelium-context.py         (Read: surface git notes for files being read)
SubagentStart ─────→ mycelium-subagent.py        (inject mycelium spore protocol)
SessionStart ──────→ mycelium-arrive.sh          (announce arrival to mycelium substrate)
Stop ──────────────→ on-ready.sh + stop-handoff.py (🟢 title:subtitle + 5-min checkpoint)
                   → mycelium-depart.sh          (leave departure note on modified files)
PreCompact ────────→ precompact-handoff.py       (full handoff before compaction, 1M context)
SessionEnd ────────→ precompact-handoff.py       (handoff on graceful exit)
                   → git-track-rebuild.py        (rebuild git tracking index)
                   → plan-cleanup-symlinks.py    (remove plan forwarding symlinks)

Terminal Title: Two-tier format with repo-type emoji icons — 🔴 🐍 claudicle: Building test suite. Icons auto-detected from CLAUDE.md keywords and project files. Main title persists across events; subtitle updates from transcript.

Session Handoff System: Three hooks ensure context survives compaction, graceful exits, and crashes. Writes structured YAML to ~/.claude/handoffs/ with objective, decisions, blockers, and next steps. Auto-maintains INDEX.md.

Git Tracking: Three hooks intercept git commands across any directory, capturing repos, branches, operations, and commit hashes. Builds a bidirectional session↔repo index. Query with getSessionsForRepo() / getReposForSession() or generate a dashboard with /session-report.

Plan Auto-Naming: Renames randomly-named plan files (e.g. tingly-humming-simon.md) to dated slugs (e.g. 2026-02-17-auto-rename-plan-files-hook.md) by extracting the H1 header. Creates forwarding symlinks for mid-session continuity; cleaned up on SessionEnd.

Session Auto-Titling: When a plan file is created, plan-session-rename.py immediately extracts the H1 header and sets the session's customTitle in sessions-index.json—no LLM call, pure local, ~10ms. If the session isn't yet in the index (Claude Code writes lazily), a .pending-title breadcrumb is saved for session-tags-infer.py to apply on next Stop.

Lint-Directed Agent Loop: lint-on-write.py runs standard linters (ESLint, Clippy, Ruff) and custom grep-based convention rules after every Write/Edit, returning violations as additionalContext so the agent self-corrects against machine-enforced rules. Any repo can opt in by dropping a .claude/lint-rules.json config file declaring which linter to use and what CLAUDE.md conventions to enforce as grep rules. Implements the Factory.ai pattern. 5s per-file cooldown, 10-violation cap.

Commands — 49 slash commands

Markdown templates invoked as /command-name. Key workflows:

Agents — Custom subagents

Read-only research subagents invoked via the Task tool with subagent_type: "Bash" and the agent instructions in the prompt.

CLI Tools — Session management & launchers

All CLIs share lib/tracker-utils.js for session parsing and status detection.

Plugin Profile Manager — cplugins

Claude Code has an undocumented ~37-40 agent limit. When total agents (built-in + plugin + custom) exceed this, agents are silently dropped with no warning. This tool manages plugin profiles to keep the total under the limit.

cplugins status     # Show current profile, agent counts, over/under limit
cplugins soul       # All custom subdaimones, no compound-engineering (34 agents)
cplugins compound   # Compound Engineering workflows (45 agents)
cplugins lean       # Maximum headroom, minimal plugins (17 agents)
cplugins --only compound-engineering model-trainer  # Ad-hoc: enable only these

Setup:

cp scripts/claude-plugins.py ~/.claude/scripts/
cp scripts/plugin-profiles.json ~/.claude/scripts/
chmod +x ~/.claude/scripts/claude-plugins.py
echo "alias cplugins='python3 ~/.claude/scripts/claude-plugins.py'" >> ~/.zshrc

Profiles are defined in plugin-profiles.json. Edit AGENT_COUNTS in the script when plugins change. Changes take effect on next session start.

VS Code Extension — Claude Session Tracker

Track and resume Claude Code sessions across crashes, restarts, and multiple VS Code windows.

• Cross-window tracking ("Claude Active (7)")
• Quick resume: Cmd+Shift+C
• Crash recovery with one-click resume
• Session browser with AI-generated titles, model info, turn counts, cost

Global Config Reference — Full ~/.claude/ structure

Complete reference for the ~/.claude/ directory: CLAUDE.md patterns, user persona models, progressive disclosure with agent_docs/, settings.json hooks/MCP/plugins, session handoff system, plans, and design principles.

Recommended Plugins

feature-dev — Claude Code Team's Arsenal

The official plugin from the Claude Code team:

/plugin marketplace add anthropics/claude-code
/plugin install feature-dev

Three specialized agents: code-architect (implementation blueprints), code-explorer (trace execution paths), code-reviewer (confidence-based review).

compound-engineering — Multi-Agent Review Workflows

By Every AI Labs. Provides 12+ specialized review agents (security-sentinel, performance-oracle, architecture-strategist, etc.) and workflow orchestration commands.

MCP Servers

We've shifted toward skills over MCPs for most workflows. Claude Code's MCP Tool Search loads tools on-demand, reducing context pollution by ~85%.

Configured in .mcp.json: supabase, playwright, context7, shadcn, figma, arxiv, perplexity, telnyx, twilio, and more. See the file for full configuration.

Ghostty Config — Terminal for Claude Code

Optimized Ghostty config: Catppuccin Mocha/Latte theme, JetBrains Mono, 100K scrollback, split panes for parallel sessions, prompt jumping, and session persistence.

cp ghostty/config ~/Library/Application\ Support/com.mitchellh.ghostty/config

Key bindings: Cmd+D split right, Cmd+Alt+Enter zoom split, Cmd+Up/Down jump prompts. See ghostty/README.md for full keybinding reference.

Pair with ccstatusline (npm install -g ccstatusline) and lazygit (brew install lazygit) in a side split.

Teammate Onboarding

CLAUDE.template.md — A teammate-ready global config with all tooling conventions and no personal details.

cp CLAUDE.template.md ~/.claude/CLAUDE.md

Then customize:

• Identity: Create ~/.claude/userModels/{yourname}/{yourname}Model.md and uncomment the @reference
• Always Loaded: Uncomment @agent_docs/ references you want active in every session
• On-Demand References: Add paths to docs Claude should read when relevant

See docs/global-setup/README.md for the full ~/.claude/ structure reference, including userModel examples.

The template includes: engineering principles, tool preferences (OSGrep, firecrawl, uv, RLAMA retrieve-only default), interaction conventions, planning patterns, session continuity via handoffs, and infrastructure notes.

Contributing

1. Skills: Follow the SKILL.md + scripts/ + references/ structure. Test across projects.
2. Commands: Use frontmatter (description, argument-hint). Keep single-purpose.
3. Hooks: Test with piped JSON input before wiring into settings.json.

Companion Projects

Claudicle — Soul Agent Framework

Open-source 4-layer soul architecture (Identity, Cognition, Memory, Channels) that gives Claude Code sessions persistent personality, memory, and behavioral continuity. The soul hooks in this repo (soul-activate.py, soul-deregister.py, soul-registry.py) register sessions with the Claudicle daemon. Souls like Kothar—the Ugaritic craftsman god—maintain identity across sessions, respond on Slack, and dream in the Daimon Chamber.

git clone https://github.com/tdimino/claudicle
cd claudicle && ./setup.sh --personal
# then in any Claude Code session: /ensoul

Dabarat — Live Markdown Preview

AI-native markdown previewer with annotations, bookmarks, and live reload. Zero dependencies. The dabarat-open.py hook auto-opens new .md files in a browser tab as Claude writes them—plans, docs, and READMEs render live. Multi-tab support, margin annotations, and global bookmarks saved to ~/.claude/bookmarks/.

git clone https://github.com/tdimino/dabarat
cd dabarat && pip install -e .
dabarat plan.md               # preview in browser
dabarat --add spec.md         # add tab to running instance

ClipLog — Clipboard History Daemon

Git-tracked clipboard history with source attribution for macOS. Polls NSPasteboard every 500ms, logs to daily JSONL files at ~/.clipboard-log/, and tags each copy with the frontmost application. Distinguishes claude copies (Terminal, Ghostty, VS Code) from user copies (Safari, Finder). Auto-redacts API keys and secrets. Auto-commits on shutdown and midnight rollover.

git clone https://github.com/tdimino/cliplog
cd cliplog && uv sync
uv run python cliplog.py                           # run daemon
uv run python cliplog_query.py today --source claude  # query Claude copies
uv run python cliplog_query.py search "function"   # full-text search
uv run python cliplog_query.py stats               # per-app breakdown

Persistent daemon via launchd: cp com.minoan.cliplog.plist ~/Library/LaunchAgents/ && launchctl load ~/Library/LaunchAgents/com.minoan.cliplog.plist

Credits & Inspiration

• Claude Code by Anthropic — the terminal-first AI coding tool
• Open Souls — the AI souls paradigm
• compound-engineering by Every AI Labs — multi-agent review workflows
• feature-dev plugin by the Claude Code team — code-architect, code-explorer, code-reviewer
• super-ralph-wiggum by AI Hero — autonomous iteration loop pattern
• ccstatusline by sirmalloc — terminal statusline for Claude Code
• beautiful-mermaid by Craft — Mermaid diagram rendering
• llama.cpp by Georgi Gerganov — local LLM inference
• RLAMA by dontizi — local RAG system
• Firecrawl by Mendable — web scraping and content extraction
• Scrapling by D4Vinci — local stealth web scraping
• Exa — neural web search API
• Handy by CJ Pais — push-to-talk speech-to-text
• matklad's ARCHITECTURE.md — codebase documentation guide

Skills: 66 | Commands: 49 | Hooks: 44 | CLI Tools: 10

"ἀπιστίῃ διαφυγγάνει μὴ γιγνώσκεσθαι." — "Divine things escape recognition through disbelief." — Heraclitus