AI Crew

A system of autonomous AI agents (Product Owner, Developer, QA, Architect) that collaborate via Discord and GitHub. Built on the Claude Agent SDK.

This is a template repository. Fork it and use Claude Code, Codex, or your favorite AI coding assistant to explore and adapt it to your needs.

Getting Started

1. Fork This Repository

Don't clone directly - fork first so you can customize freely:

1. Click the Fork button at the top right of this page
2. Clone your fork locally:

   git clone https://github.com/YOUR-USERNAME/ai-crew.git
   cd ai-crew

2. Explore with AI

This codebase is designed to be explored and customized with AI assistance. Open the repo with your preferred AI coding tool:

With Claude Code:

claude .

With Codex or other AI assistants: Open the project and start asking questions like:

• "How does the agent system work?"
• "Where are the agent instructions defined?"
• "How do I add a new agent role?"
• "How does Discord integration work?"

3. Customize for Your Use Case

Common customizations:

• Agent personalities: Edit src/agents/*/CLAUDE.md files
• Add new agents: Copy an existing agent folder and modify
• Change workflows: Update the cron schedules in ecosystem.config.cjs
• Integrate different tools: Add MCP servers or modify Discord tools

4. Add New Features with AI

The best way to extend this system is to simply ask your AI assistant to do it for you:

"Add Slack integration alongside Discord"
"Create a new Designer agent that reviews UI mockups"
"Replace GitHub Projects with Jira for work tracking"
"Add email notifications when PRs are merged"
"Create a /deploy command that triggers a deployment pipeline"

Your AI assistant can read the codebase, understand the patterns, and implement new features that integrate with the existing architecture. This is the intended workflow - you describe what you want, and the AI figures out how to add it.

Pro tip: Be specific about your requirements. Instead of "add Slack", try "add Slack integration that mirrors messages from Discord #development channel to a Slack #updates channel".

Overview

Modern LLMs can self-organize and collaborate effectively when given access to standard human collaboration tools (chat, kanban boards, code repos) without requiring explicit workflow orchestration code.

┌─────────────────────────────────────────────────────────────────┐
│                                                                 │
│   ┌──────────┐   ┌──────────┐   ┌──────────┐   ┌──────────┐   │
│   │    PO    │   │   Dev    │   │    QA    │   │ Architect│   │
│   │  Agent   │   │  Agent   │   │  Agent   │   │   Agent  │   │
│   └────┬─────┘   └────┬─────┘   └────┬─────┘   └────┬─────┘   │
│        │              │              │              │          │
│        └──────────────┴──────────────┴──────────────┘          │
│                           │                                     │
│                    ┌──────┴──────┐                              │
│                    │   Discord   │  Communication               │
│                    │   GitHub    │  Work Tracking               │
│                    └─────────────┘                              │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Prerequisites

• Node.js 20+
• pnpm (npm install -g pnpm)
• PM2 for process management (npm install -g pm2)
• GitHub CLI (brew install gh or cli.github.com)
• Discord bot token and server

Installation

# Install dependencies
pnpm install

# Copy environment template
cp .env.example .env

# Edit .env with your credentials
# See "Configuration" section below

Configuration

Create a .env file with:

# Discord Configuration
DISCORD_TOKEN=your-discord-bot-token
DISCORD_GUILD_ID=your-guild-id

# Cost Limits
MAX_DAILY_COST_USD=50.00

Build & Run

# Build TypeScript
pnpm build

# Start all agents with PM2
pm2 start ecosystem.config.cjs

# View status
pm2 status

# View logs
pm2 logs

# Restart all agents
pm2 restart all

Agents

Agent	Role	Discord Role	Primary Channel
PO	Product Owner - Creates tickets, manages backlog, answers questions	@po	#development
Dev	Developer - Implements features, creates PRs	@dev	#dev-chat
QA	QA Engineer - Tests PRs, verifies functionality	@qa	#dev-chat
Architect	Technical Lead - Research, architecture decisions	@architect	#development

Escalation Flow

Dev ──────┐
          │
QA  ──────┼──► PO ──────► Human (@human)
          │
Architect─┘

Only PO escalates to the human. All other agents escalate to PO.

How It Works

Triggers

Agents respond to:

• Discord mentions: @dev can you fix this bug?
• Cron schedules: Periodic checks for work
• GitHub events: PR reviews, issue assignments (via polling)

Workflow Example

1. Human posts in #development: "We need a login feature"
2. PO creates a GitHub issue with acceptance criteria
3. PO moves issue to "Ready for Dev"
4. Dev picks up the ticket, creates a branch, implements
5. Dev creates PR, moves ticket to "In Review"
6. QA tests the PR, approves or requests changes
7. PR is merged, ticket moves to "Done"

Project Structure

ai-crew/
├── src/
│   ├── agents/              # Agent configurations
│   │   ├── po/CLAUDE.md     # PO instructions
│   │   ├── dev/CLAUDE.md    # Dev instructions
│   │   ├── qa/CLAUDE.md     # QA instructions
│   │   └── architect/CLAUDE.md
│   ├── shared/
│   │   ├── runner/          # Agent execution loop
│   │   ├── tools/           # Discord tools
│   │   ├── guardrails/      # Cost tracking, cooldowns
│   │   └── auto-update/     # Self-update mechanism
│   └── index.ts             # Entry point
├── docs/                    # Documentation
├── data/                    # Shared state, journals
├── ecosystem.config.cjs     # PM2 configuration
└── package.json

PM2 Management

# Start all agents
pm2 start ecosystem.config.cjs

# Restart specific agent
pm2 restart dev

# View logs
pm2 logs dev

# Stop all
pm2 stop all

# Set up auto-start on boot
pm2 startup
pm2 save

Documentation

Setup Guides

• Discord Setup - Create bot, configure server
• GitHub Setup - Configure repository, project board
• OpenRouter Setup - Use alternative AI providers (OpenRouter, DeepSeek, etc.)

Development

• Testing Agents - Testing strategy and guidelines
• Creating Skills - How to add agent capabilities
• Discord File Tools - File attachments in Discord

Operations

• Auto-Update - How agents self-update

Reference

• Configuration Reference - All agent config.json options
• PRD.md - Full product requirements document

Testing

# Run all tests
pnpm test

# Watch mode
pnpm test:watch

# With coverage
pnpm test:coverage

Environment Variables

Variable	Description	Required
DISCORD_TOKEN	Discord bot token	Yes
DISCORD_GUILD_ID	Discord server ID	Yes
MAX_DAILY_COST_USD	Daily API cost limit	Yes
AGENT_NAME	Which agent to run (po/dev/qa/architect)	Yes (at runtime)
AUTO_UPDATE_ENABLED	Enable self-updates (default: true)	No

Tech Stack

• Runtime: Node.js 20+ / TypeScript
• Agent Framework: @anthropic-ai/claude-agent-sdk
• Communication: Discord (discord.js)
• Work Tracking: GitHub Projects API
• Process Management: PM2
• Testing: Vitest

Contributing

1. Create a feature branch
2. Make changes
3. Run tests: pnpm test
4. Create a PR

License

MIT