README.md 12 KB
claude-mods
A comprehensive extension toolkit for Claude Code that transforms your AI coding assistant into a powerhouse development environment.
24 expert agents. 11 slash commands. 11 skills. 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
/saveplanand/loadplan, implementing Anthropic's recommended pattern for long-running agents.Expert-level knowledge on demand — 24 specialized agents covering React, TypeScript, Python, 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 (24)
├── commands/ # Slash commands (11)
├── skills/ # Custom skills (11)
├── 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)
# In Claude Code, run:
/plugin install 0xDarkMatter/claude-mods
This installs directly from GitHub. Toggle on/off with /plugin menu.
Script Install
Linux/macOS:
git clone https://github.com/0xDarkMatter/claude-mods.git
cd claude-mods
./scripts/install.sh
Windows (PowerShell):
git clone https://github.com/0xDarkMatter/claude-mods.git
cd claude-mods
.\scripts\install.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. |
| loadplan | Restore plan session state. Loads TodoWrite tasks, plan progress from saved state. |
| saveplan | Save plan session state. Persists TodoWrite tasks, current plan step, and git context. |
| showplan | Show plan status: progress, active tasks, git state. Quick read-only view. |
| plan | Create and persist project plans. Captures Plan Mode state and writes to git-trackable PLAN.md. |
| g-slave | Dispatch Gemini CLI to analyze large codebases. Gemini does the grunt work, Claude gets the summary. |
| agent-genesis | Generate Claude Code expert agent prompts for any technology platform. |
| review | Code review staged changes or specific files. Analyzes bugs, security, performance, style. |
| test | Generate tests with automatic framework detection (Jest, Vitest, pytest, etc.). |
| explain | Deep explanation of complex code, files, or concepts. Architecture, data flow, design decisions. |
| init-tools | Initialize and verify CLI tool dependencies for skills. |
Skills
| Skill | Description |
|---|---|
| agent-discovery | Analyze tasks and recommend specialized agents |
| code-stats | Analyze codebase with tokei and difft |
| data-processing | Process JSON with jq, YAML/TOML with yq |
| git-workflow | Enhanced git operations with lazygit, gh, delta |
| project-docs | Scan and synthesize project documentation |
| python-env | Fast Python environment management with uv |
| safe-file-reader | Read files without permission prompts |
| structural-search | Search code by AST structure with ast-grep |
| task-runner | Run project commands with just |
| tool-discovery | Find the right library/tool for any task |
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 |
| 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 |
| fetch-expert | Parallel web fetching with retry logic |
| firecrawl-expert | Web scraping, crawling, structured extraction |
| javascript-expert | Modern JavaScript, async patterns, optimization |
| laravel-expert | Laravel framework, Eloquent, testing |
| react-expert | React hooks, state management, Server Components, performance |
| typescript-expert | TypeScript type system, generics, utility types, strict mode |
| vue-expert | Vue 3, Composition API, Pinia state management, performance |
| 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 |
| rest-expert | RESTful API design, HTTP methods, status codes |
| sql-expert | Complex SQL queries, optimization, indexing |
| tailwind-expert | Tailwind CSS, responsive design |
| wrangler-expert | Cloudflare Workers deployment, wrangler.toml |
| claude-architect | Claude Code architecture, extensions, MCP, plugins, debugging |
Tools, Rules & Hooks
| Resource | Description |
|---|---|
| tools/ | Modern CLI toolkit - token-efficient replacements for legacy commands |
| rules/cli-tools.md | Tool preference rules (fd, rg, eza, bat, etc.) |
| hooks/ | Hook examples for pre/post execution automation |
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
These commands fill 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: /saveplan and /loadplan 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]
/saveplan "Stopped at auth module" # Writes .claude/claude-state.json
Session 2:
/sync # Read project context
/loadplan # Restore TodoWrite, show what changed
→ "In progress: Auth module refactor"
→ "Notes: Stopped at auth module"
/showplan # Quick status check anytime
Why Not Just Use --resume?
| Feature | --resume |
/saveplan + /loadplan |
|---|---|---|
| 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, /loadplan for task state.
Updating
git pull
Then re-run the install script to update your global Claude configuration.
Contributing
PRs welcome. Run cd tests && just test before submitting.
Resources
- Claude Code Best Practices — Official Anthropic guide
- Claude Code Plugins — Plugin system documentation
- Effective Harnesses for Long-Running Agents — The pattern behind
/saveplan
Extend Claude Code. Your way.