OmoiOS
Spec-driven multi-agent orchestration — autonomous development workforce powered by Claude & OpenHands
Install / Use
/learn @kivo360/OmoiOSQuality Score
Category
Development & EngineeringSupported Platforms
README
The Problem
AI coding agents are powerful individually, but using them at scale is a mess. You paste a prompt, wait, review, paste another prompt, fix what broke, repeat. There's no dependency awareness, no parallel execution, no structured handoff between tasks. Agents don't know what other agents are doing. When something fails, you're the orchestrator.
OmoiOS fixes this. It reads your existing codebase, generates specs from what's actually there, builds a task DAG with real dependencies, and runs agent swarms across isolated sandboxes until the work is done. A supervisor agent handles merges and keeps everything on track.
You describe what you want
→ OmoiOS explores your codebase
→ Generates specs (requirements, design, tasks)
→ Builds a dependency DAG
→ Spawns agents in isolated sandboxes
→ Agents execute in parallel, discover new work as they go
→ Supervisor agent merges code and steers stuck agents
→ PRs land on your repo
This isn't prompt chaining. It's a structured runtime for agent swarms — with dependency graphs, sandboxed execution, active supervision, and code that actually merges.
What Makes This Different
Specs from your actual code
OmoiOS doesn't generate generic plans. It reads your repo — file structure, patterns, dependencies — and generates specs grounded in what exists. The SpecStateMachine runs phases (Explore → Requirements → Design → Tasks) where each phase builds on real codebase context.
DAG-based execution, not a task queue
Tasks form a dependency graph (DependencyGraphService). Nothing executes until its dependencies are met. Critical path analysis determines what runs in parallel. This is how you get 5 agents working simultaneously without stepping on each other.
Every agent gets a sandbox
Each agent runs in an isolated Daytona container with its own Git branch, filesystem, and resources. No shared state. No interference. When agents finish, ConvergenceMergeService merges their branches in optimal order, using Claude to resolve conflicts.
Active supervision, not fire-and-forget
IntelligentGuardian analyzes every agent's trajectory every 60 seconds — scoring alignment, detecting drift, and injecting steering interventions mid-task. ConductorService monitors system-wide coherence, detects duplicate work, and coordinates across agents. Agents don't just run. They're watched.
Agents discover work as they go
During execution, agents find bugs, missing requirements, optimization opportunities. DiscoveryService spawns new tasks in the appropriate phase automatically. The DAG grows and adapts — workflows build themselves based on what agents actually encounter.
You approve at gates, not every step
Phase transitions have quality gates. You review at strategic points (phase completions, PRs). Everything between gates runs autonomously. You set direction — the swarm handles execution.
Code Assistant
<p align="center"> <img src="docs/assets/demo-code-assistant.gif" alt="OmoiOS Code Assistant — spawns sandboxes and codes for you" width="960"/> </p>Beyond orchestrating agent swarms, OmoiOS includes a built-in code assistant that understands your entire codebase. Ask it anything — it explores your repo's structure, reads the actual code, and gives grounded answers. When it's time to build, it spawns isolated sandboxes and writes code for you.
Architecture
+---------------------------+
| Frontend (Next.js 15) |
| Dashboard, Kanban Board, |
| Agent Monitor, Spec |
| Workspace, React Flow |
+-------------+-------------+
|
REST + WebSocket
|
+-------------v-------------+
| Backend (FastAPI) |
| |
| 40+ Route Modules |
| 100+ Service Modules |
| 75+ SQLAlchemy Models |
| |
| --- Core Services --- |
| SpecStateMachine |
| OrchestratorWorker |
| TaskQueueService |
| IntelligentGuardian |
| ConductorService |
| DiscoveryService |
| EventBusService |
| MemoryService |
| BillingService |
+---+-----------+--------+--+
| | |
+-------v--+ +----v-----+ +--v--------+
| Postgres | | Redis | | Daytona |
| 16 + | | cache, | | isolated |
| pgvector | | queue, | | sandbox |
| | | pubsub | | exec |
+-----------+ +----------+ +-----------+
How a Feature Gets Built
1. You submit a feature request
└→ API creates a Spec record
2. SpecStateMachine runs phases automatically:
EXPLORE → REQUIREMENTS → DESIGN → TASKS → SYNC
└→ Each phase produces versioned artifacts
3. TaskQueueService assigns work to agents
└→ Priority-based, respects dependencies
4. OrchestratorWorker spawns isolated sandboxes
└→ Each agent gets its own Daytona workspace + Git branch
5. Agents execute, discover, and adapt
└→ Guardian monitors every 60s
└→ Discovery creates new tasks when agents find issues
└→ EventBus publishes progress via WebSocket
6. Phase gates validate quality
└→ Human approval at strategic points
7. Code lands as PRs
└→ Full traceability from spec to commit
Quick Start
Prerequisites
You need Docker, Python 3.12+, Node.js 22+, uv, pnpm, and just. Pick your platform below.
<details open> <summary><b>macOS</b></summary># Docker Desktop
brew install --cask docker
# Python + Node.js
brew install python@3.12 node
# uv (Python package manager)
curl -LsSf https://astral.sh/uv/install.sh | sh
# pnpm (Node.js package manager)
corepack enable && corepack prepare pnpm@latest --activate
# just (command runner)
brew install just
# Docker Engine
sudo apt-get update
sudo apt-get install -y ca-certificates curl gnupg
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin
# Add yourself to docker group (log out + in after this)
sudo usermod -aG docker $USER
# Python 3.12+
sudo apt-get install -y python3.12 python3.12-venv python3.12-dev
# Node.js 22+ (via NodeSource)
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs
# uv (Python package manager)
curl -LsSf https://astral.sh/uv/install.sh | sh
# pnpm (Node.js package manager)
corepack enable && corepack prepare pnpm@latest --activate
# just (command runner) — pick one:
curl --proto '=https' --tlsv1.2 -sSf https://just.systems/install.sh | bash -s -- --to /usr/local/bin
# or: sudo snap install just --classic
# or: sudo apt install just (if available on your release)
# Docker Engine
sudo dnf -y install dnf-plugins-core
sudo dnf config-manager --add-repo https://download.docker.com/linux/fedora/docker-ce.repo
sudo dnf install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin
sudo systemctl start docker && sudo systemctl enable docker
sudo usermod -aG docker $USER
# Python 3.12+
sudo dnf install -y python3.12 python3.12-devel
# Node.js 22+ (via NodeSource)
curl -fsSL https://rpm.nodesource.com/setup_22.x | sudo bash -
sudo dnf install -y nodejs
# uv (Python package manager)
curl -LsSf https://astral.sh/uv/install.sh | sh
# pnpm (Node.js package manager)
corepack enable && corepack prepare pnpm@latest --activate
# just (command runner
