@claude-agent-system/core

Multi-agent orchestrator system for Claude Code with parallel execution and workflows.

Pre-Installation Requirements

Before installing, ensure you have:

• Node.js: Version 18.0.0 or higher
• npm: Version 7.0.0 or higher
• Claude Code: Installed and configured
• Git: For version control integration (optional)
• Network Access: For downloading MCP servers during installation

Verify Node.js Version

node --version

Ensure the output shows version 18.0.0 or higher.

Installation

Automatic Installation (Recommended)

Install the package as a development dependency:

npm install @claude-agent-system/core --save-dev

The installation script will automatically run and configure your Claude Code environment.

Manual Installation (Fallback)

If the automatic installation doesn't work, follow these steps:

1. Install the package:

   npm install @claude-agent-system/core --save-dev

2. Run the installation script manually:

   npx @claude-agent-system/core

3. Verify installation:

   • Check that .claude directory was created in your project
   • Verify settings.json exists in your project root
   • Confirm agent files are in .claude/agents/

Local Development Installation

If you're developing the package locally:

1. Navigate to the package directory:

   cd path/to/claude-agent-system

2. Install dependencies:

   npm install

3. Run the installation script:

   node scripts/install.js

4. Or use npx to run the install script:

   npx @claude-agent-system/core

Quick Start

After installation, the system will automatically configure your Claude Code environment with:

• 14 Specialized Agents: Each with unique capabilities for different development tasks
• 9-Stage Workflow: Structured process for complex project development
• MCP Server Integration: Seamless connection to Model Context Protocol servers
• Parallel Execution: Run multiple agents simultaneously for faster development

The installation script will automatically set up all necessary configuration files in your .claude directory.

Features

🤖 Specialized Agents

• Architect: Plan and design system architecture
• Code: Write, modify, and refactor code
• Ask: Get explanations and documentation
• Debug: Troubleshoot issues and diagnose problems
• Orchestrator: Coordinate complex multi-step projects
• QA Specialist: Test code before release and verify bug fixes
• Project Manager: Sync tasks between Notion and GitHub
• Mode Writer: Create custom modes
• Documentation Writer: Create and improve technical documentation
• Project Research: Investigate and understand codebases
• Security Reviewer: Audit code for security vulnerabilities
• DevOps: Deploy applications and manage infrastructure
• User Story Creator: Create user stories and define acceptance criteria
• Frontend Designer: Create and improve UI components
• Git Manager: Handle version control and GitHub operations

🔄 9-Stage Workflow

1. Discovery: Understand requirements and context
2. Planning: Create detailed project plans
3. Architecture: Design system architecture
4. Implementation: Write and integrate code
5. Testing: Verify functionality and quality
6. Review: Code review and optimization
7. Documentation: Create comprehensive documentation
8. Deployment: Deploy to production environments
9. Maintenance: Monitor and maintain the system

⚡ Parallel Execution

Execute multiple agents simultaneously to:

• Speed up development workflows
• Handle independent tasks concurrently
• Reduce overall project completion time

🔌 MCP Integration

Connect to various MCP servers for:

• Extended AI capabilities
• Custom tool integrations
• External service connections
• Enhanced functionality

Documentation

For detailed documentation, see the src/docs/ directory.

License

MIT License - see LICENSE for details.

Contributing

Contributions are welcome! Please read our contributing guidelines before submitting pull requests.

Support

For issues, questions, or suggestions, please open an issue on our GitHub repository.

Troubleshooting

Installation Script Doesn't Run Automatically

Problem: The postinstall script doesn't execute during npm install.

Solutions:

1. Run the installation script manually:

   npx @claude-agent-system/core

2. Or run it directly with node:

   node node_modules/@claude-agent-system/core/scripts/install.js

3. If using a local symlink, run the install script from the package directory:

   cd path/to/claude-agent-system
   node scripts/install.js

Dependencies Not Installed

Problem: Installation fails with "module not found" errors.

Solution: Ensure dependencies are installed in the package directory:

cd path/to/claude-agent-system
npm install

Path Issues on Windows

Problem: Incorrect path separators causing errors in settings.json.

Solution: The installation script now uses path.join() and proper escaping. If you still have issues:

1. Delete the existing settings.json
2. Run the installation script again:

   npx @claude-agent-system/core

MCP Servers Not Starting

Problem: MCP servers fail to start after installation.

Solutions:

1. Ensure you have network access to download MCP servers
2. Check that Node.js version is 18.0.0 or higher
3. Verify npm is working correctly:

   npm --version
   npx --version

.claude Directory Already Exists

Problem: Installation fails because .claude directory already exists.

Solution: The installation script automatically backs up the existing directory to .claude.backup. If you want to start fresh:

rm -rf .claude .claude.backup
npx @claude-agent-system/core

API Keys Not Set

Problem: MCP servers require API keys but they're set as placeholders.

Solution: Set the required environment variables before installation:

# On Windows
set BRAVE_API_KEY=your_key_here
set GITHUB_TOKEN=your_token_here

# On macOS/Linux
export BRAVE_API_KEY=your_key_here
export GITHUB_TOKEN=your_token_here

Then run the installation script again.

Agents Not Available After Installation

Problem: Agents don't appear in Claude Code after installation.

Solutions:

1. Close and restart VSCode completely
2. Check that .claude/agents/ directory contains JSON files
3. Verify settings.json exists in your project root
4. Check Claude Code logs for errors

Known Issues

Postinstall Script with Local Symlinks

When installing a local package via symlink, the postinstall script may not run automatically. Use the manual installation method as a workaround.

Windows Path Escaping

Earlier versions had inconsistent path escaping. This has been fixed in version 1.0.0+ with proper path.join() usage and JSON escaping.

MCP Server Download Failures

If network issues prevent MCP servers from downloading, the installation may fail. Ensure you have a stable internet connection during installation.