Claude Sub-Agents Manager - AI-Powered Development Assistants for Claude Code

🚀 Enhance Claude Code with Specialized AI Agents - Now Fully Compatible with Claude Code Format

A powerful management tool for Claude Code agents that adds discovery, optimization, and bulk operations

Installation • Quick Start • Available Agents • Documentation • Contributing

🙏 Acknowledgments

This project grab some ideas from https://github.com/webdevtodayjason/sub-agents.git. https://buildermethods.com/agent-os A warm thanks to both projects ada for the excellent project contribution and foundation!

\ud83d\udd04 Major Update: Now fully compatible with Claude Code's native agent format! Use the migrate command to update existing agents.

🎯 What is Claude Sub-Agents Manager?

Claude Sub-Agents Manager is a complementary CLI tool for Claude Code that helps you discover, install, and optimize AI agents. It fully supports Claude Code's native agent format while adding powerful features like bulk operations, description optimization for better auto-delegation, and quality validation. Think of it as a package manager for Claude Code agents.

✨ Why Use This Tool?

• 🧠 Agent Discovery: Browse and install community agents easily
• ⚡ Bulk Operations: Install, update, or validate multiple agents at once
• 🎨 Description Optimization: Improve agent descriptions for better auto-delegation
• 🔍 Quality Validation: Ensure agents follow best practices
• 🔄 Format Migration: Convert legacy agents to Claude Code format
• 📋 Process & Standards Management: Sync development processes and coding standards
• 🛠️ Developer Friendly: Simplifies agent management workflow

🚀 Installation

NPM (Recommended)

npm install -g @zamaz/claude-agents

Yarn

yarn global add @zamaz/claude-agents

From Source

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

🔄 Updating

Check Current Version

claude-agents --version
# or
claude-agents version

Update to Latest

# NPM
npm update -g @zamaz/claude-agents

# Yarn
yarn global upgrade @zamaz/claude-agents

# From source
cd sub-agents
git pull
npm install
npm link --force

Check for Updates

# Manual check
claude-agents version

# Automatic check on every run
# (notifies when updates are available)

⚡ Quick Start

# See what's available
claude-agents list

# Install your first agent interactively
claude-agents install

# Or install all agents at once
claude-agents install --all

# Install specific agents directly
claude-agents install code-reviewer test-runner

# Validate all agents (supports Claude Code format)
claude-agents validate

# Optimize agent descriptions for better auto-delegation
claude-agents optimize --all

# Agents now use description-based auto-delegation
# In Claude Code, just describe what you need:
> "Review my recent code changes"
> "Run the tests and fix any failures"
> "Debug this TypeError in production"

🔄 Keeping Agents in Sync

Claude Code may install agents directly to ~/.claude/agents/. Use the sync command to register these agents and copy them to your project:

# Detect and register externally installed agents
claude-agents sync

# Force copy all agents to project directory (NEW!)
claude-agents sync --force-copy

# Fix YAML parsing issues in Claude Code agents
make fix-yaml

# The sync feature now:
# - Detects agents installed by Claude Code
# - Registers them in configuration
# - Copies them to your project's agents/ directory
# - Preserves Claude Code's complex YAML format

The sync feature ensures all agents are properly tracked, managed, and version-controlled. See SYNC_PROCESS.md for details.

🔑 Key Features

🆕 New in v1.0.4

• Process & Standards Management: Sync development processes and coding standards from ~/.claude/
• Enhanced Sync: Automatically copies Claude Code agents to your project directory
• YAML Compatibility: Full support for Claude Code's complex YAML format
• Bulk Operations: Install, validate, and optimize multiple agents at once
• Smart Command Detection: Automatically finds and copies related slash commands
• Git-Friendly: All agents, processes, and standards are version-controlled in your project

Core Features

• 🔍 Agent Discovery: Browse and install community agents
• 📦 Package Management: Install, update, remove agents like npm packages
• ✨ Description Optimization: Improve agent descriptions for better auto-delegation
• ✅ Quality Validation: Ensure agents follow best practices
• 🔄 Format Migration: Convert legacy agents to Claude Code format
• 🛡️ Security Scanning: Check for sensitive data before commits
• 📊 Update Notifications: Get notified when new versions are available

📋 Available Sub-Agents

Core Development Agents

| Agent Name | Description | Trigger Examples | |------------|-------------|------------------| | code-reviewer | Automatically reviews code after edits. Checks for quality, security vulnerabilities, performance issues, and best practices. | "Review my code", "Check for security issues" | | code-refactorer | Improves code structure without changing functionality. Applies design patterns and modernizes legacy code. | "Refactor this code", "Apply SOLID principles" | | debugger | Analyzes and fixes errors, crashes, and unexpected behavior. Interprets stack traces and identifies root causes. | "Debug this error", "Fix the crash" | | security-scanner | Scans for security vulnerabilities and compliance issues. Detects exposed secrets and suggests fixes. | "Scan for vulnerabilities", "Check security" | | performance-optimizer | Continuously analyzes and optimizes system performance, code efficiency, and resource usage. | "Optimize performance", "Fix bottlenecks" | | codebase-analyzer | Analyzes codebase structure, dependencies, and architecture. Extracts insights and patterns. | "Analyze this codebase", "Show dependencies" |

Testing Agents

| Agent Name | Description | Trigger Examples | |------------|-------------|------------------| | test-runner | Runs tests when code changes or tests fail. Automatically detects test framework and fixes failing tests. | "Run tests", "Fix failing tests" | | unit-test-writer | Writes comprehensive unit tests using JUnit, Jest, pytest, and other frameworks. Creates test suites with high coverage. | "Write unit tests", "Add test coverage" | | integration-test-writer | Creates end-to-end and integration tests using Playwright, Cypress, Selenium. Tests user flows and API integrations. | "Write integration tests", "Test user flow" |

Documentation Agents

| Agent Name | Description | Trigger Examples | |------------|-------------|------------------| | documentation-writer | Creates and updates technical documentation. Generates API docs, README files, and developer guides. | "Document this API", "Update the README" | | technical-documentation-writer | Creates detailed technical documentation including API references, system architecture docs, and deployment guides. | "Write technical docs", "Document architecture" | | business-documentation-writer | Creates business-focused documentation including user guides, process documentation, and stakeholder reports. | "Write user guide", "Create process docs" |

Design & UX Agents

| Agent Name | Description | Trigger Examples | |------------|-------------|------------------| | ux-optimizer | Optimizes user experience, interactions, and conversion rates through data-driven design decisions. | "Optimize user experience", "Improve conversion rate" | | design-system-creator | Creates and enhances design systems with AI personalization. Implements adaptive interfaces and brand consistency. | "Create design system", "Implement adaptive UI" | | visual-design-enhancer | Enhances visual aesthetics, creates artistic approaches, and develops creative visual solutions. | "Enhance visuals", "Improve aesthetics" | | platform-redesigner | Coordinates comprehensive platform redesigns. Addresses accessibility, conversion rates, and technical debt. | "Redesign platform", "Fix accessibility" |

Architecture & Planning Agents

| Agent Name | Description | Trigger Examples | |------------|-------------|------------------| | system-architect | Designs scalable system architectures using modern patterns. Recommends best practices and technologies. | "Design system architecture", "Plan microservices" | | product-roadmap-planner | Creates strategic product roadmaps, feature prioritization matrices, and release planning. | "Plan product roadmap", "Prioritize features" | | agent-orchestration-strategist | Organizes AI agents into strategic groups, creates specialized roadmaps for each domain. | "Organize agents", "Create agent strategy" | | process-orchestrator | Maps workflows, identifies automation opportunities, and designs orchestration patterns. | "Map workflow", "Automate process" |

Creative & Marketing Agents

| Agent Name | Description | Trigger Examples | |------------|-------------|------------------| | creative-brainstormer | Generates innovative ideas, product names, and creative concepts. Brainstorms features and unique solutions. | "Brainstorm ideas", "Generate product names" | | marketing-strategist | Creates compelling marketing copy, SEO strategies, and campaign ideas. Analyzes competitor messaging. | "Write marketing copy", "Create SEO strategy" |

📚 CLI Commands Reference

Basic Commands

# Install agents
claude-agents install                    # Interactive installation
claude-agents install --all              # Install all available agents
claude-agents install code-reviewer test-runner  # Install specific agents

# List agents
claude-agents list                       # Show all agents
claude-agents list --installed           # Show only installed agents
claude-agents list --available           # Show available to install

# Manage agents
claude-agents enable <agent>             # Enable an agent
claude-agents disable <agent>            # Disable an agent
claude-agents remove <agent>             # Remove an agent
claude-agents info <agent>               # Show agent details

Advanced Commands

# Sync and manage external agents
claude-agents sync                       # Detect and register external agents
claude-agents sync --force-copy          # Copy all agents to project directory

# Sync processes and standards
claude-agents sync-processes             # Sync processes from ~/.claude/processes
claude-agents sync-processes --force-copy # Copy all processes to project
claude-agents sync-standards             # Sync standards from ~/.claude/standards
claude-agents sync-standards --force-copy # Copy all standards to project

# Quality and optimization
claude-agents validate                   # Validate all agents
claude-agents validate <agent>           # Validate specific agent
claude-agents optimize --all             # Optimize all agent descriptions
claude-agents optimize <agent>           # Optimize specific agent

# Migration and maintenance
claude-agents migrate                    # Convert to Claude Code format
claude-agents migrate --cleanup          # Migrate and remove old files

Development Commands (with Makefile)

# Quick commands
make list-agents                         # List all installed agents
make sync                               # Sync external agents
make sync-copy                          # Force copy all agents to project
make sync-processes                     # Sync processes from ~/.claude/processes
make sync-standards                     # Sync standards from ~/.claude/standards
make validate                           # Validate all agents
make fix-yaml                           # Fix YAML frontmatter issues

# Publishing (for contributors)
make publish-info                       # Show publishing instructions
make publish-quick                      # Quick publish helper

🤖 Featured Agent Examples

🔍 Code Reviewer

Your personal code quality guardian

• Comprehensive security analysis
• Best practices enforcement
• Performance optimization suggestions
• Clean code principles

# Install
claude-agents install code-reviewer

# Use in Claude Code (auto-delegation)
> "I need to review my recent changes for security issues"

🧪 Unit Test Writer

Comprehensive test creation specialist

• Creates test suites with high coverage
• Supports Jest, pytest, JUnit, and more
• Implements mocking and edge cases
• Follows testing best practices

# Install
claude-agents install unit-test-writer

# Use
> "Write unit tests for my authentication module"
> "Add test coverage for the payment service"

🎨 UX Optimizer

User experience enhancement expert

• Data-driven design decisions
• Conversion rate optimization
• Accessibility improvements
• User flow analysis

# Install
claude-agents install ux-optimizer

# Use
> "Optimize the checkout flow for better conversion"
> "Improve accessibility of our forms"

🚀 Performance Optimizer

System performance specialist

• Identifies bottlenecks
• Optimizes resource usage
• Improves code efficiency
• Continuous performance monitoring

# Install
claude-agents install performance-optimizer

# Use
> "Optimize our API response times"
> "Find and fix performance bottlenecks"

📊 Product Roadmap Planner

Strategic planning expert

• Feature prioritization matrices
• Release planning
• Business alignment
• Technical debt management

# Install
claude-agents install product-roadmap-planner

# Use
> "Plan our Q2 product roadmap"
> "Prioritize features for next sprint"

💡 Creative Brainstormer

Innovation catalyst

• Generates product names
• Feature ideation
• Creative problem solving
• Market differentiation

# Install
claude-agents install creative-brainstormer

# Use
> "Brainstorm names for our new AI tool"
> "Generate innovative feature ideas"

📖 Documentation

📚 Command Reference

| Command | Description | Example | |---------|-------------|---------| | 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/uninstall an agent | claude-agents remove debugger | | info <agent> | Show agent details | claude-agents info debugger | | create | Create a custom agent | claude-agents create | | migrate | Migrate to Claude Code format | claude-agents migrate | | optimize [agent] | Optimize descriptions | claude-agents optimize | | validate [agent] | Validate agent quality | claude-agents validate | | update [agent] | Update agent configurations | claude-agents update | | update --all | Update all installed agents | claude-agents update --all | | update --force | Force update without confirmation | claude-agents update --force |

🔄 Updating Agents

Keep your agents up-to-date with the latest improvements and features:

Update Commands

# Interactive update - select which agents to update
claude-agents update

# Update a specific agent
claude-agents update code-reviewer

# Update all installed agents at once
claude-agents update --all

# Force update without confirmation prompt
claude-agents update --all --force

# Preserve custom modifications during update
claude-agents update --all --preserve-custom

Using Make

# Update all agents quickly
make update-agents

# Update specific agent
make update-agent AGENT=code-reviewer

# List installed agents first
make list-agents

What Gets Updated

• Agent Definitions - Latest prompts and configurations
• Metadata - Version information and timestamps
• Hooks - Any associated automation hooks
• Slash Commands - Corresponding command files

🔄 New Features for Claude Code Compatibility

Migrate Existing Agents

# Convert old format to Claude Code format
claude-agents migrate

# With options
claude-agents migrate --cleanup  # Remove old directories after migration

Optimize Agent Descriptions

# Improve descriptions for better auto-delegation
claude-agents optimize

# Optimize specific agent
claude-agents optimize code-reviewer

Validate Agent Quality

# Check agent format and quality
claude-agents validate

# Detailed validation
claude-agents validate --verbose

Creating Custom Agents

Simple Agent Creation

Create ~/.claude/agents/my-agent.md:

---
name: my-agent
description: Automatically handles X when Y occurs. Use when dealing with Z tasks.
tools: Read, Edit, Grep  # Optional - inherits all if omitted
---

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

## Process
When invoked, immediately:
1. [STEP 1]
2. [STEP 2]
3. [STEP 3]

\ud83d\udcdd Agent Format (Claude Code Compatible)

Agents are now single .md files with YAML frontmatter:

---
name: agent-name
description: Clear description with trigger words for auto-delegation
tools: Read, Grep, Glob  # Optional - inherits all if omitted
---

Agent system prompt here...

Key Points:

• No more slash commands - uses description-based auto-delegation
• No separate metadata.json or hooks.json files
• Tools are optional - agents inherit all tools if not specified
• Descriptions should include trigger words for better matching

Installation Scopes

User Scope (~/.claude/agents/)

• Available in all projects
• Personal agents
• Default installation location

Project Scope (.claude/agents/)

• Project-specific agents
• Shared with team via version control
• Use --project flag

Advanced Configuration

State Management

Agent states are tracked in .claude-agents.json:

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

Hook Integration

Trigger agents automatically with hooks:

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Edit|Write",
      "hooks": [{
        "type": "command",
        "command": "echo 'Consider running /review' >&2"
      }]
    }]
  }
}

📋 Process & Standards Management

Managing Development Processes

Store reusable development processes in ~/.claude/processes/:

# Sync processes to your project
claude-agents sync-processes

# Force copy all processes
claude-agents sync-processes --force-copy

# Using Make
make sync-processes

Example process file (~/.claude/processes/code-review.md):

---
name: code-review
type: process
version: 1.0.0
description: Standard code review process
---

# Code Review Process
[Process content...]

Managing Coding Standards

Store coding standards in ~/.claude/standards/:

# Sync standards to your project
claude-agents sync-standards

# Force copy all standards
claude-agents sync-standards --force-copy

# Using Make
make sync-standards

Example standard file (~/.claude/standards/api-design.md):

---
name: api-design
type: standard
version: 1.0.0
description: RESTful API design standards
---

# API Design Standards
[Standards content...]

Benefits

• Consistency: Share processes and standards across projects
• Version Control: Track changes to processes and standards
• Team Collaboration: Ensure everyone follows the same guidelines
• Claude Integration: Reference processes and standards in conversations

🌟 Our Ecosystem

Check out our other tools for Claude Code:

🪝 Claude Hooks Manager

Powerful hook management system for Claude Code automation

🔨 Context Forge

Our flagship tool for intelligent context generation and management

🚫 Gitignore Support

Claude agents now respect gitignore patterns to avoid processing unnecessary files:

Automatic Exclusions

Agents automatically ignore:

• node_modules/ - Dependencies
• .git/ - Version control
• dist/, build/ - Build outputs
• .env files - Secrets
• IDE configurations
• OS-specific files

Custom Ignore Patterns

Create a .claude-ignore file in your project root:

# Example .claude-ignore
*.log
coverage/
temp/
secrets/

How It Works

• Agents read both .gitignore and .claude-ignore
• File searches automatically exclude ignored patterns
• Improves performance by skipping irrelevant files
• Prevents accidental exposure of sensitive data

🤝 Contributing

We love contributions! Here's how you can help:

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-agent)
3. Commit your changes (git commit -m 'Add amazing agent')
4. Push to the branch (git push origin feature/amazing-agent)
5. Open a Pull Request

Adding New Agents

1. Create agent structure:

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

2. Add slash command:

commands/
└── your-command.md

3. Submit PR with description

🐛 Troubleshooting

Agent Not Working?

# Check installation
claude-agents list

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

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

Debug Mode

# Run Claude with debug output
claude --debug

Common Issues

• Permission denied: Use sudo for global install
• Agent not found: Check spelling and installation
• Command not working: Ensure Claude Code is updated

📊 Release Notes

🐛 Troubleshooting

Common Issues and Solutions

YAML Parsing Errors

If you see "Invalid YAML frontmatter" errors:

# Fix YAML issues automatically
make fix-yaml
# Or manually
node scripts/fix-yaml-frontmatter.js

Agents Not Showing After Claude Code Installation

# Sync externally installed agents
claude-agents sync
# Copy all agents to your project
claude-agents sync --force-copy

Git Push Rejected

# Sync with remote before pushing
git fetch origin
git pull --rebase origin main
git push origin main

NPM Publishing Issues

# Version already exists
npm version patch  # Bump version first
# OTP required
npm publish --otp=123456  # Use your authenticator code

Agent Not Working

# Verify installation
claude-agents list
claude-agents info <agent-name>
# Validate format
claude-agents validate <agent-name>
# Re-enable if needed
claude-agents enable <agent-name>

Debug Mode

# Run with debug logging
LOG_LEVEL=DEBUG claude-agents sync
# Check configuration
cat ~/.claude-agents.json

📊 Release Notes

Version 1.0.4 (Latest)

• Added process and standards management
• Sync development processes from ~/.claude/processes
• Sync coding standards from ~/.claude/standards
• New commands: sync-processes and sync-standards
• Separate configuration files for processes and standards

Version 1.0.3

• Enhanced sync with automatic project copying
• Full Claude Code YAML format support
• Fixed YAML parsing for complex descriptions
• Improved command detection
• Cleaned up Makefile

Version 1.0.2

• Added requirements-analyst agent
• Improved sync functionality
• Better error handling

Version 1.0.0

• 🎉 Initial release
• 6 production-ready agents
• Interactive CLI interface
• Custom agent creation
• Project/user scope support
• Comprehensive documentation

📄 License

MIT License - see LICENSE file for details

🙏 Acknowledgments

• Claude Code team at Anthropic
• Our amazing community of developers
• All contributors and testers
• Special thanks to webdevtodayjason for the original project

🔧 Development & Testing

Running Tests

# Run all tests
npm test

# Watch mode
npm run test:watch

# Coverage report
npm run test:coverage

Code Quality

# Lint code
npm run lint

# Fix linting issues
npm run lint:fix

# Format code
npm run format

Security

# Run security audit
npm audit

# Fix vulnerabilities
npm run audit:fix

See IMPROVEMENTS.md for detailed documentation on:

• 🧪 Testing framework setup
• 🔒 Security enhancements
• 📊 Type safety with JSDoc
• 🚀 CI/CD pipelines
• 📦 Dependency management

📬 Connect

• 🐛 Report Issues
• 💡 Request Features
• 🐦 Follow Updates
• ⭐ Star on GitHub

🔍 SEO Keywords & Use Cases

Perfect for developers who want to:

• Automate code reviews with AI-powered analysis
• Fix failing tests automatically using intelligent test runners
• Debug complex issues with expert error analysis
• Generate documentation from existing code
• Scan for security vulnerabilities proactively
• Refactor legacy code with modern patterns
• Enhance Claude Code with specialized capabilities
• Create custom AI agents for specific workflows

Technologies & Integrations:

• Works with Claude Code by Anthropic
• Supports all major programming languages
• Integrates with existing development workflows
• Compatible with Git, npm, yarn, and more
• Extensible through custom agent creation

Made with ❤️ by lsendel

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

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