czarina

# Czarina: Multi-Agent Orchestration System

**Orchestrate multiple AI coding agents working in parallel on complex software projects**

[![Production Ready](https://img.shields.io/badge/status-production%20ready-green)]() [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE) [![Version](https://img.shields.io/badge/version-0.9.0-blue)]()

Czarina enables autonomous teams of AI coding agents (OpenCode, Cursor, Aider, Cursor, Kilocode, Windsurf, and more) to collaborate on software development with 95-98% autonomy and 3-4x speedup.

---

## How It Works

```mermaid
graph TB
    H[Human<br/>Sets Goals] --> C[Czar<br/>Coordinates]

    C --> W1[Worker 1<br/>OpenCode]
    C --> W2[Worker 2<br/>Aider]
    C --> W3[Worker 3<br/>Cursor]
    C --> Wn[Worker N<br/>...]

    HP[Hopper<br/>Task Queue] -.->|briefs + lessons| W1
    HP -.-> W2
    HP -.-> W3
    HP -.-> Wn

    W1 --> G[Git<br/>Pull Requests]
    W2 --> G
    W3 --> G
    Wn --> G

    G -.->|Review & Merge| H
```

**The Flow:**
1. **Human** writes a project plan
2. **`czarina plan`** uses AI to break it into worker briefs
3. **`czarina init`** creates the orchestration setup
4. **`czarina launch`** registers everything in Hopper and starts workers
5. **Workers** pull their full briefs from Hopper, work in parallel in isolated git worktrees
6. **Hopper** stores instructions persistently — workers recover from crashes without intervention
7. **Git** collects work via pull requests
8. **Human** reviews and merges

---

## Requirements

### Platform
- Linux, macOS, or Windows via WSL
- bash, tmux, git, Python 3.11+, jq

### Required Dependencies

| Dependency | Purpose | Install |
|------------|---------|---------|
| **hopper** | Task queue and persistent instruction store | `pip install hopper-cli` |
| **tmux** | Session management for parallel workers | `sudo apt install tmux` |
| **jq** | JSON processing | `sudo apt install jq` |
| **git** | Version control and worktree management | syste