🚀 Supercharge Claude Code with Specialized AI Sub-Agents for Code Review, Testing, Debugging & More

Transform your development workflow with intelligent AI assistants that excel at specific programming tasks

Installation • Quick Start • Available Agents • Documentation • Contributing

npm install -g @webdevtoday/claude-agents

yarn global add @webdevtoday/claude-agents

git clone https://github.com/webdevtodayjason/sub-agents.git
cd sub-agents
npm install
npm link

# Initialize all agents in your project
claude-agents init

# List available agents
claude-agents list

# Initialize with context-forge awareness
claude-agents init --respect-context-forge

# Agents will:
# - Detect existing PRPs and CLAUDE.md
# - Place commands in .claude/commands/agents/
# - Append to CLAUDE.md without overwriting
# - Work alongside your existing setup

# Project Planning - Reads and understands your PRPs
claude-agents run project-planner --task "Create implementation roadmap from existing PRPs"
claude-agents run project-planner --task "Break down auth-prp into sprint tasks"

# API Development - PRP-aware implementation
claude-agents run api-developer --task "Implement user endpoints from feature-auth-prp.md"
claude-agents run api-developer --task "Create REST API following our conventions"

# Frontend Development
claude-agents run frontend-developer --task "Build login UI matching dark-theme-ui-prp"
claude-agents run frontend-developer --task "Create dashboard from feature-dashboard-prp.md"

# Testing & Quality
claude-agents run tdd-specialist --task "Create tests for authentication flow"
claude-agents run code-reviewer --task "Review API endpoints for security"
claude-agents run security-scanner --task "Scan authentication implementation"

# Documentation
claude-agents run api-documenter --task "Generate OpenAPI spec from implemented endpoints"
claude-agents run doc-writer --task "Update Implementation.md with progress"

# Debugging & Refactoring
claude-agents run debugger --task "Analyze login timeout issue"
claude-agents run refactor --task "Improve error handling in auth module"

# DevOps & Deployment
claude-agents run devops-engineer --task "Setup CI/CD for main branch"
claude-agents run devops-engineer --task "Create Docker configuration"

# Product & Marketing
claude-agents run product-manager --task "Create user stories from PRPs"
claude-agents run marketing-writer --task "Write feature announcement for auth system"

# Via slash commands (in .claude/commands/agents/)
> /agent-review            # Triggers code review
> /agent-api              # Triggers API development
> /agent-debug login issue # Debug specific problem

# Via Task tool
> Task("project-planner: analyze all PRPs and create sprint plan")
> Task("api-developer: implement endpoints from feature-auth-prp.md")
> Task("frontend-developer: build UI from feature-dashboard-prp.md")

# Install
claude-agents install code-reviewer

# Use
> /review

# Install
claude-agents install test-runner

# Use
> /test
> /test src/**/*.test.js

# Install
claude-agents install debugger

# Use
> /debug Cannot read property 'map' of undefined

# Install
claude-agents install refactor

# Use
> /refactor improve performance
> /refactor apply SOLID principles

# Install
claude-agents install doc-writer

# Use
> /document API
> /document architecture

# Install
claude-agents install security-scanner

# Use
> /security-scan
> /security-scan src/api/

# Install
claude-agents install shadcn-ui-builder

# Use
> /ui create a login page
> /shadcn implement dashboard with sidebar

# Install
claude-agents install project-planner

# Use
> /plan e-commerce platform
> /plan microservices migration

# Install
claude-agents install api-developer

# Use
> /api user authentication endpoints
> /api payment processing service

# Install
claude-agents install frontend-developer

# Use
> /frontend user dashboard
> /frontend shopping cart component

# Install
claude-agents install tdd-specialist

# Use
> /tdd UserService class
> /tdd API integration tests

# Install
claude-agents install api-documenter

# Use
> /apidoc REST endpoints
> /apidoc GraphQL schema

# Install
claude-agents install devops-engineer

# Use
> /devops GitHub Actions workflow
> /devops Kubernetes deployment

# Install
claude-agents install product-manager

# Use
> /product user onboarding flow
> /product feature prioritization

# Install
claude-agents install marketing-writer

# Use
> /marketing product launch post
> /marketing API feature announcement

## 📖 Documentation

### Command Reference

| Command | Description | Example |
|---------|-------------|---------|
| `init` | Initialize agents in project | `claude-agents init` |
| `init --respect-context-forge` | Init preserving context-forge | `claude-agents init --respect-context-forge` |
| `install` | Install agents interactively | `claude-agents install` |
| `install --all` | Install all available agents | `claude-agents install --all` |
| `install --project` | Install to project directory | `claude-agents install --project` |
| `list` | Show all agents | `claude-agents list` |
| `list --installed` | Show only installed agents | `claude-agents list --installed` |
| `enable <agent>` | Enable a disabled agent | `claude-agents enable code-reviewer` |
| `disable <agent>` | Disable an agent | `claude-agents disable test-runner` |
| `remove <agent>` | Remove specific agent | `claude-agents remove debugger` |
| `uninstall` | Bulk uninstall with options | `claude-agents uninstall --all --clean` |
| `info <agent>` | Show agent details | `claude-agents info debugger` |
| `create` | Create a custom agent | `claude-agents create` |
| `run <agent>` | Run agent independently | `claude-agents run marketing-writer --task "write launch post"` |
| `dashboard` | Launch web dashboard | `claude-agents dashboard` |

### Independent Agent Execution

Run agents outside of Claude Code for automation and scripting:

```bash
# Run with inline task
claude-agents run marketing-writer --task "Write launch announcement for v2.0"

# Run with task file
claude-agents run api-developer --file api-spec.md

# Interactive mode
claude-agents run tdd-specialist --interactive

# Start dashboard on port 7842
claude-agents dashboard

# Custom port
claude-agents dashboard --port 8080

---
name: my-agent
description: What this agent does and when to use it
tools: Read, Edit, Grep, Bash
---

You are an expert in [DOMAIN]. Your role is to [PURPOSE].

When invoked, you will:
1. [STEP 1]
2. [STEP 2]
3. [STEP 3]

Always ensure [KEY PRINCIPLE].

{
  "installedAgents": {
    "code-reviewer": {
      "version": "1.0.0",
      "scope": "user",
      "installedAt": "2024-01-20T10:00:00Z"
    }
  },
  "enabledAgents": ["code-reviewer"],
  "disabledAgents": []
}

{
  "PostToolUse:Edit": {
    "condition": "file.endsWith('.js')",
    "commands": ["npm run lint", "npm test"]
  },
  "TaskComplete": {
    "notify": "Task {{task_name}} completed",
    "store": "agent:{{agent_name}}:last_task"
  }
}

{
  "hooks": {
    "PostToolUse:Edit": [{
      "matcher": "\\.(js|ts|py)$",
      "hooks": [{
        "type": "command",
        "command": "echo 'Consider running /review' >&2"
      }]
    }]
  }
}

{
  "PostToolUse:Edit": {
    "condition": "file.includes('src/')",
    "commands": ["npm test -- --watch=false"]
  }
}

agents/
└── your-agent/
    ├── agent.md       # Agent definition
    ├── metadata.json  # Agent metadata
    └── hooks.json     # Optional hooks

commands/
└── your-command.md

# Enable debug mode to see where agents are being searched
DEBUG=claude-agents claude-agents run project-planner --task "test"

# Check npm global installation path
npm list -g @webdevtoday/claude-agents

# Verify agents are included in the package
ls -la $(npm root -g)/@webdevtoday/claude-agents/agents/

# Check installation
claude-agents list

# Verify agent status
claude-agents info <agent-name>

# Re-enable if disabled
claude-agents enable <agent-name>

# Run Claude with debug output
claude --debug

# Run claude-agents with debug output
DEBUG=claude-agents claude-agents run <agent> --task "test"

Made with ❤️ by WebDev Today Jason

Building AI-powered developer tools to enhance productivity and code quality

Claude Sub-Agents Manager - Your AI-Powered Development Team in Claude Code