npm package: @simbahq/simba
Description: Business CEO Agent System - Multi-agent orchestration with human-in-the-loop via Slack and GitHub
Latest version: 1.0.0

# Simba

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D20.0.0-green.svg)](https://nodejs.org/)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.3-blue.svg)](https://www.typescriptlang.org/)
[![Claude SDK](https://img.shields.io/badge/Claude%20Agent%20SDK-Powered-orange.svg)](https://www.anthropic.com/)

**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

```bash
# 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:

```markdown
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`:

```json
{
  "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

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

### Custom Agent Prompts

Customize agent behavior:

```json
{
  "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:

```bash
$ 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

```bash
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](CONTRIBUTING.md) for guidelines.

## License

MIT License - see [LICENSE](LICENSE) for details.

---

Built with [Claude Agent SDK](https://www.anthropic.com/) by Anthropic