README.md 14 KB
claude-mods
A comprehensive extension toolkit for Claude Code that transforms your AI coding assistant into a powerhouse development environment.
23 expert agents. 10 slash commands. 30 skills. 4 rules. Custom output styles. One plugin install.
Why claude-mods?
Claude Code is powerful out of the box, but it has gaps. This toolkit fills them:
Session continuity — TodoWrite tasks vanish when sessions end. We fix that with
/plan --saveand/plan --load, implementing Anthropic's recommended pattern for long-running agents.Expert-level knowledge on demand — 23 specialized agents covering React, TypeScript, Python, Go, Rust, AWS, PostgreSQL, and more. Each agent is deeply researched with real-world patterns, not generic advice.
Modern CLI tools — Stop using
grep,find, andcat. Our rules automatically preferripgrep,fd,eza, andbat— 10-100x faster and token-efficient.Smart web fetching — A fallback hierarchy that actually works: WebFetch → Jina Reader → Firecrawl. No more "I can't access that URL."
Workflow patterns — TDD cycles, code review, feature development, debugging — all documented with Anthropic's best practices.
Key Benefits
- Persistent task state — Pick up exactly where you left off, even across machines
- Domain expertise — Agents trained on framework docs, not just general knowledge
- Token efficiency — Modern CLI tools produce cleaner output, saving context window
- Team sharing — Git-trackable state files work across your whole team
- Production-ready — Validated test suite, proper plugin format, comprehensive docs
- Extended thinking — Built-in guidance for "think hard" and "ultrathink" triggers
- Zero lock-in — Standard Claude Code plugin format, toggle on/off anytime
Structure
claude-mods/
├── .claude-plugin/ # Plugin metadata
├── agents/ # Expert subagents (23)
├── commands/ # Slash commands (11)
├── skills/ # Custom skills (30)
├── output-styles/ # Response personalities
├── hooks/ # Hook examples & docs
├── rules/ # Claude Code rules
├── tools/ # Modern CLI toolkit docs
├── tests/ # Test suites + justfile
├── scripts/ # Install scripts
├── docs/ # Project docs (PLAN.md, DASH.md)
└── templates/ # Extension templates
Installation
Plugin Install (Recommended)
# Step 1: Add the marketplace
/plugin marketplace add 0xDarkMatter/claude-mods
# Step 2: Install the plugin
/plugin install claude-mods@0xDarkMatter-claude-mods
This installs globally (available in all projects). Toggle on/off with /plugin menu.
Script Install
Linux/macOS:
git clone https://github.com/0xDarkMatter/claude-mods.git
cd claude-mods
./tools/install-unix.sh
Windows (PowerShell):
git clone https://github.com/0xDarkMatter/claude-mods.git
cd claude-mods
.\tools\install-windows.ps1
Manual Install
git clone https://github.com/0xDarkMatter/claude-mods.git
Then symlink or copy to your Claude directories:
- Commands →
~/.claude/commands/ - Skills →
~/.claude/skills/ - Agents →
~/.claude/agents/ - Rules →
~/.claude/rules/
What's Included
Commands
| Command | Description |
|---|---|
| sync | Session bootstrap - read project context (README, AGENTS, docs, skills, agents). Quick orientation. |
| plan | Unified planning command: create plans, save/load session state, show status. Interactive by default. |
| review | Code review staged changes or specific files. Analyzes bugs, security, performance, style. |
| testgen | Generate tests with expert routing, framework detection, focus/depth modes. |
| explain | Deep explanation of complex code, files, or concepts. Architecture, data flow, design decisions. |
| spawn | Generate expert agents with PhD-level patterns and code examples. |
| conclave | [DEPRECATED] Use Conclave CLI instead. |
| atomise | Atom of Thoughts reasoning - decompose problems into atomic units with confidence tracking and backtracking. |
| pulse | Generate Claude Code ecosystem news digest from blogs, repos, and community sources. |
| setperms | Set tool permissions and CLI preferences. |
| archive | Archive completed plans and session state. |
Skills
Pattern Reference Skills
| Skill | Description |
|---|---|
| rest-patterns | HTTP methods, status codes, REST design patterns |
| tailwind-patterns | Tailwind utilities, responsive breakpoints, config |
| sql-patterns | CTEs, window functions, JOIN patterns, indexing |
| sqlite-ops | SQLite schemas, Python sqlite3/aiosqlite patterns |
| mcp-patterns | MCP server structure, tool handlers, resources |
CLI Tool Skills
| Skill | Description |
|---|---|
| file-search | Find files with fd, search code with rg, select with fzf |
| find-replace | Modern find-and-replace with sd |
| code-stats | Analyze codebase with tokei and difft |
| data-processing | Process JSON with jq, YAML/TOML with yq |
| structural-search | Search code by AST structure with ast-grep |
Workflow Skills
| Skill | Description |
|---|---|
| tool-discovery | Recommend agents and skills for any task |
| git-workflow | Enhanced git operations with lazygit, gh, delta |
| doc-scanner | Scan and synthesize project documentation |
| project-planner | Track stale plans, suggest /plan command |
| python-env | Fast Python environment management with uv |
| task-runner | Run project commands with just |
Agents
| Agent | Description |
|---|---|
| astro-expert | Astro projects, SSR/SSG, Cloudflare deployment |
| asus-router-expert | Asus routers, network hardening, Asuswrt-Merlin |
| aws-fargate-ecs-expert | Amazon ECS on Fargate, container deployment |
| bash-expert | Defensive Bash scripting, CI/CD pipelines |
| claude-architect | Claude Code architecture, extensions, MCP, plugins, debugging |
| cloudflare-expert | Cloudflare Workers, Pages, DNS, security |
| craftcms-expert | Craft CMS content modeling, Twig, plugins, GraphQL |
| cypress-expert | Cypress E2E and component testing, custom commands, CI/CD |
| firecrawl-expert | Web scraping, crawling, parallel fetching, structured extraction |
| go-expert | Go idioms, concurrency, error handling, performance |
| javascript-expert | Modern JavaScript, async patterns, optimization |
| laravel-expert | Laravel framework, Eloquent, testing |
| payloadcms-expert | Payload CMS architecture and configuration |
| playwright-roulette-expert | Playwright automation for casino testing |
| postgres-expert | PostgreSQL management and optimization |
| project-organizer | Reorganize directory structures, cleanup |
| python-expert | Advanced Python, testing, optimization |
| react-expert | React hooks, state management, Server Components, performance |
| rust-expert | Rust ownership, lifetimes, async, unsafe patterns |
| sql-expert | Complex SQL queries, optimization, indexing |
| typescript-expert | TypeScript type system, generics, utility types, strict mode |
| vue-expert | Vue 3, Composition API, Pinia state management, performance |
| wrangler-expert | Cloudflare Workers deployment, wrangler.toml |
Rules
| Rule | Description |
|---|---|
| cli-tools.md | Modern CLI tool preferences (fd, rg, eza, bat, etc.) |
| thinking.md | Extended thinking triggers (think → ultrathink) |
| commit-style.md | Conventional commits format and examples |
| naming-conventions.md | Component naming patterns for agents, skills, commands |
Tools & Hooks
| Resource | Description |
|---|---|
| tools/ | Modern CLI toolkit - token-efficient replacements for legacy commands |
| hooks/ | Hook examples for pre/post execution automation |
Output Styles
Output styles customize Claude's response personality. Use /output-style to switch between them.
| Style | Description |
|---|---|
| vesper | Sophisticated engineering companion with British wit, intellectual depth, and pattern recognition |
Creating custom styles: Add a markdown file to output-styles/ with YAML frontmatter:
---
name: StyleName
description: Brief description of the personality
keep-coding-instructions: true # Preserve Claude Code's core behavior
---
# Style content here...
Web Fetching Hierarchy
When fetching web content, tools are used in this order:
| Priority | Tool | When to Use |
|---|---|---|
| 1 | WebFetch |
First attempt - fast, built-in |
| 2 | r.jina.ai/URL |
JS-rendered pages, PDFs, cleaner extraction |
| 3 | firecrawl <url> |
Anti-bot bypass, blocked sites (403, Cloudflare) |
| 4 | firecrawl-expert agent |
Complex scraping, structured extraction |
See tools/README.md for full documentation and install scripts.
Testing & Validation
Validate all extensions before committing:
cd tests
# Run full validation (requires just)
just test
# Or run directly
bash validate.sh
# Windows
powershell validate.ps1
What's Validated
- YAML frontmatter syntax
- Required fields (name, description)
- Naming conventions (kebab-case)
- File structure (agents/.md, skills//SKILL.md)
Available Tasks
cd tests
just # List all tasks
just test # Run full validation
just validate-yaml # YAML only
just validate-names # Naming only
just stats # Count extensions
just list-agents # List all agents
Session Continuity
The /plan command fills a gap in Claude Code's native session management.
The problem: Claude Code's --resume flag restores conversation history, but TodoWrite task state does not persist between sessions—by design. Claude Code treats each session as isolated; the philosophy is that persistent state belongs in files you control.
TodoWrite tasks are stored at ~/.claude/todos/[session-id].json and deleted when the session ends. This is intentional.
The solution: /plan --save and /plan --load implement the pattern from Anthropic's Effective Harnesses for Long-Running Agents:
"Every subsequent session asks the model to make incremental progress, then leave structured updates."
What Persists vs What Doesn't
| Claude Code Feature | Persists? | Location |
|---|---|---|
| Conversation history | Yes | Internal (use --resume) |
| CLAUDE.md context | Yes | ./CLAUDE.md |
| TodoWrite tasks | No | Deleted on session end |
| Plan Mode state | No | In-memory only |
Session Workflow
Session 1:
/sync # Bootstrap - read project context
[work on tasks]
/plan --save "Stopped at auth module" # Writes .claude/session-cache.json
Session 2:
/sync # Read project context
/plan --load # Restore TodoWrite, show what changed
→ "In progress: Auth module refactor"
→ "Notes: Stopped at auth module"
/plan --status # Quick status check anytime
Why Not Just Use --resume?
| Feature | --resume |
/plan --save/--load |
|---|---|---|
| Conversation history | Yes | No |
| TodoWrite tasks | No | Yes |
| Git context | No | Yes |
| Human-readable summary | No | Yes |
| Git-trackable | No | Yes |
| Works across machines | No | Yes (if committed) |
| Team sharing | No | Yes |
Use both together: claude --resume for conversation context, /plan --load for task state.
Updating
git pull
Then re-run the install script to update your global Claude configuration.
Resources
- Claude Code Best Practices — Official Anthropic guide
- Claude Code Plugins — Plugin system documentation
- Effective Harnesses for Long-Running Agents — The pattern behind
/plan --save
Extend Claude Code. Your way.