Simba

Your AI-Powered Development Team — Multi-agent orchestration using GitHub Issues as your task queue.

What is Simba?

Simba is an AI agent orchestrator that manages a team of specialized AI agents to handle software development tasks. It uses GitHub Issues as the task queue, making it easy to assign work, track progress, and maintain human oversight.

┌─────────────────────────────────────────────────────────────────┐
│                         GitHub Issues                           │
│               (Task Queue + Human Interface)                    │
└─────────────────────────────────────────────────────────────────┘
                               │
                        ┌──────┴──────┐
                        │   Simba CLI  │
                        │  (Daemon)    │
                        └──────┬──────┘
                               │
          ┌────────────────────┼────────────────────┐
          ▼                    ▼                    ▼
    ┌──────────┐        ┌──────────┐        ┌──────────┐
    │ PM Agent │        │Dev Agent │        │ QA Agent │
    │ Planning │        │  Coding  │        │ Testing  │
    └──────────┘        └──────────┘        └──────────┘

Key Features

• GitHub Issues as Task Queue - Create issues, add labels, and agents pick up work automatically
• Multi-Agent System - CEO, PM, Developer, QA, and Marketing agents work together
• Git Worktrees - Each task gets an isolated worktree for safe parallel development
• Agent Handoffs - Agents can hand off work to each other (e.g., Dev → QA)
• Metrics & Reporting - Track task completion, success rates, and agent performance
• Multi-Repo Support - Manage tasks across multiple repositories
• Custom Prompts - Customize agent behavior through configuration

Quick Start

Prerequisites

• Node.js >= 20.0.0
• GitHub CLI authenticated (gh auth login)

Installation

# Clone the repository
git clone https://github.com/banyudu/simba.git
cd simba

# Install dependencies
npm install

# Build
npm run build

# Initialize Simba for your project
npx simba init

# Start the daemon
npx simba start

CLI Commands

| Command | Description | |---------|-------------| | simba init | Initialize Simba for your project (creates config and labels) | | simba start | Start the Simba daemon | | simba status | Show current task queue and agent status | | simba stop | Stop the Simba daemon | | simba metrics | Show performance metrics and statistics |

How It Works

1. Create a GitHub Issue

Create an issue and add labels to assign it to an agent:

Title: [Task] Add user authentication

Body:
Implement JWT-based authentication for the API endpoints.

Labels: agent:dev, priority:p1, status:ready

2. Labels Control Everything

Agent Assignment:

• agent:dev - Developer agent
• agent:pm - Project manager agent
• agent:qa - QA/testing agent
• agent:marketing - Documentation/marketing agent
• ceo - CEO orchestrator

Status:

• status:ready - Ready to be picked up
• status:in-progress - Currently being worked on
• status:blocked - Waiting for human input
• status:review - Completed, awaiting review

Priority:

• priority:p0 - Critical
• priority:p1 - High
• priority:p2 - Medium

3. Agents Execute Tasks

When you run simba start, agents poll for issues with their label and status:ready:

🦁 Starting Simba - AI Agent Orchestrator

✓ Loaded config for: my-project
✓ GitHub authenticated
✓ Worktree manager initialized
✓ GitHub task queue initialized (1 repo(s), strategy: priority)
✓ Agents initialized: ceo, pm, dev, qa, marketing

📊 Queue Status:
   Ready: 3
   In Progress: 1
   Blocked: 0
   Review: 2

🚀 Simba is running! Polling every 10s
   Press Ctrl+C to stop

🤖 [DEV] Starting: Add user authentication
✅ [DEV] Completed with PR: Add user authentication

4. Code Changes Create PRs

When a Dev or QA agent completes a task with file changes, Simba automatically:

1. Commits the changes
2. Pushes to a feature branch
3. Creates a pull request

Configuration

simba.config.json

Created by simba init:

{
  "version": "1.0.0",
  "project": {
    "name": "My Project",
    "description": "Project description"
  },
  "github": {
    "owner": "your-org",
    "repo": "your-repo"
  },
  "agents": {
    "enabled": ["ceo", "pm", "dev", "qa", "marketing"],
    "concurrency": 2,
    "prompts": {
      "dev": {
        "append": "Use TypeScript strict mode. Follow our coding standards.",
        "context": ["docs/ARCHITECTURE.md"]
      }
    }
  },
  "scheduling": {
    "strategy": "priority",
    "maxConcurrentTasks": 10,
    "priorityEscalationMinutes": 60
  },
  "workflow": {
    "autoAssign": true,
    "requireApproval": {
      "codeChanges": false,
      "deployments": true
    }
  }
}

Multi-Repository Support

{
  "repositories": [
    {
      "owner": "your-org",
      "repo": "frontend",
      "agents": ["dev", "qa"]
    },
    {
      "owner": "your-org",
      "repo": "backend",
      "agents": ["dev", "qa", "pm"]
    }
  ]
}

Custom Agent Prompts

Customize agent behavior:

{
  "agents": {
    "prompts": {
      "dev": {
        "append": "Always use TypeScript strict mode.",
        "context": ["docs/CONTRIBUTING.md"]
      },
      "qa": {
        "prepend": "Use Jest for unit tests and Playwright for E2E."
      }
    }
  }
}

Metrics

View task completion metrics:

$ simba metrics

📊 Simba Metrics (Last 7 days)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📋 Tasks:
   Completed:       45
   Failed:          3
   Success Rate:    93.8%
   Avg Duration:    12m 30s

👥 Agents:
   CEO        15 tasks, ✅ 98% success, 5m avg
   PM         10 tasks, ✅ 95% success, 8m avg
   DEV        25 tasks, ⚠️ 92% success, 15m avg

🔄 Handoffs:
   Total: 12
   Top routes:
     pm → dev: 8
     dev → qa: 4

Agent Handoffs

Agents can hand off work to each other:

1. PM → Dev: PM breaks down requirements and hands to Dev
2. Dev → QA: Dev completes implementation and hands to QA
3. QA → Dev: QA finds bugs and hands back to Dev

Handoffs preserve the work context and Git worktree.

Development

Build Commands

npm run build          # Compile TypeScript
npm run dev            # Run with hot-reload
npm start              # Run compiled code
npm run lint:fix       # ESLint auto-fix
npm run format         # Prettier formatting
npm test               # Run tests in watch mode
npm run test:run       # Run tests once

Project Structure

src/
├── cli/
│   ├── commands/        # CLI commands (init, start, status, etc.)
│   └── config-loader.ts # Config file handling
├── core/
│   ├── agents/          # PM, Dev, QA, Marketing agents
│   ├── github-task-queue.ts  # GitHub Issues as task queue
│   ├── worktree-manager.ts   # Git worktree management
│   ├── scheduler/       # Task scheduling and prioritization
│   ├── metrics/         # Metrics collection (SQLite)
│   ├── session/         # Agent session management
│   └── state/           # State persistence
├── integrations/
│   ├── claude-sdk/      # Claude Agent SDK wrapper
│   └── github/          # GitHub API client
├── types/               # TypeScript type definitions
└── utils/               # Logger, errors, retry logic

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

License

MIT License - see LICENSE for details.

Built with Claude Agent SDK by Anthropic