OmoiOS

---

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

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.

# 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) — pick one:
curl --proto '=https' --tlsv1.2 -sSf https://just.systems/install.sh | bash -s -- --to /usr/local/bin
# or: sudo dnf install just

sudo pacman -S docker docker-compose python nodejs pnpm just
sudo systemctl start docker && sudo systemctl enable docker
sudo usermod -aG docker $USER

# uv (Python package manager)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install WSL2 + Ubuntu, then follow the Ubuntu instructions above
wsl --install

# Or native Windows:
winget install Docker.DockerDesktop
winget install Python.Python.3.12
winget install OpenJS.NodeJS
winget install --id Casey.Just --exact

# Then in PowerShell:
irm https://astral.sh/uv/install.ps1 | iex
corepack enable && corepack prepare pnpm@latest --activate

just is available in most package managers. If your platform wasn't listed above:

Method	Command
Installer script	curl --proto '=https' --tlsv1.2 -sSf https://just.systems/install.sh | bash -s -- --to /usr/local/bin
Cargo	cargo install just
Conda	conda install -c conda-forge just
npm	npm install -g rust-just
pipx	pipx install rust-just
Snap	sudo snap install --edge --classic just
Nix	nix-env -iA nixpkgs.just
Chocolatey	choco install just
Scoop	scoop install just
FreeBSD	pkg install just

Full list: github.com/casey/just — Packages