Minoan Claude Code Configuration

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

Repository Map

claude-code-minoan/
├── skills/                      # 97 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/                       # 50 lifecycle hooks (handoffs, terminal UX, lint-on-write, phase-detect, mycelium)
├── commands/                    # 21 slash commands (session tracking, checkpoints, quotes, design, soul, workflows)
├── 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, tracker-db.js)
├── ghostty/                     # Ghostty terminal config for Claude Code
├── sounds/                      # Notification audio
├── demos/                       # Complete project demos (Project Thorn, Crypt Librarian)
├── docs/windows-setup/          # Windows setup guide, PowerShell installer, Codex CLI
└── 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/tdimino/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/

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

On Windows? See the Windows setup guide — includes a PowerShell installer, compatibility matrix, and Codex CLI setup.

Deep Dives

Skills — 97 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, 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 — 50 lifecycle event scripts

30 Python + 20 Bash scripts across 10 lifecycle events. Highlights:

PreToolUse ────────→ git-track.sh               (log git commands to JSONL)
                   → image-optimize.py           (auto-resize images, PNG→JPEG)
PostToolUse ───────→ lint-on-write.py            (ESLint/Clippy/Ruff + custom rules)
                   → phase-detect.py             (detect workflow phase transitions)
PermissionRequest ─→ smart-auto-approve.py       (auto-approve safe read-only commands)
Stop ──────────────→ session-tags-infer.py       (AI-powered session tagging)
PreCompact/End ────→ precompact-handoff.py       (structured YAML handoff for context survival)
SessionStart ──────→ soul-activate.py            (register Claudicle soul)
SubagentStart ─────→ soul-subagent-inject.py     (inject soul into subagents)

See hooks/README.md for the full event map, hook dependencies, and settings.json configuration.

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 — 16 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.

Session Cost Tracking

The enrichment pipeline (parseSessionEnriched in lib/tracker-utils.js) scans full JSONL transcripts to aggregate token usage from every API call, then computes USD cost using Anthropic's published per-model pricing.

sqlite3 ~/.claude/tracker.db "SELECT short_id, num_turns, printf('\$%.2f', total_cost_usd), model_short FROM sessions ORDER BY total_cost_usd DESC LIMIT 10;"

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.

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, JetBrainsMono Nerd Font with codepoint maps for Linear A/B, Phaistos Disc, and Minoan Glyphs (PUA), 100K scrollback, split panes for parallel sessions, prompt jumping, and session persistence.

brew install --cask font-jetbrains-mono-nerd-font
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

Start here: Read ARCHITECTURE.md for a bird's-eye view of the repo structure, then follow the steps below.

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

cp CLAUDE.template.md ~/.claude/CLAUDE.md
cp -r docs/global-setup/agent_docs/*.md ~/.claude/agent_docs/

Then customize:

• Identity: Create ~/.claude/userModels/{yourname}/{yourname}Model.md and uncomment the @reference. See the userModel guide.
• Always Loaded: Uncomment @agent_docs/ references you want active in every session. See progressive disclosure.
• On-Demand References: Add paths to docs Claude should read when relevant
• Agent docs: The starter templates in docs/global-setup/agent_docs/ give you active-projects, skills inventory, tools reference, and MCP server docs to customize.

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

The template includes: engineering principles, tool preferences (firecrawl, uv, RLAMA retrieve-only default), interaction conventions, planning patterns, 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 today --table          # box-drawing table output
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: 97 | Commands: 21 | Hooks: 50 | CLI Tools: 10

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