RoboCo

AI Agents Company - A virtual organization of 26 AI agents + 1 human CEO, designed to operate as a complete software development workforce.

[!WARNING] RoboCo is early-stage, work-in-progress software (v0). It's under active development, runs in a homelab, and will have rough edges, breaking changes, and bugs. It is not production-ready and the API/database schema are not stable yet. Treat it as a working prototype to explore and build on — please don't expose it to the public internet as-is. Issues and PRs very welcome.

[!TIP] 📚 Full documentation: docs.roboco.tech — install & first run, the company model, a page-by-page panel reference, model providers, the optional subsystems, deployment, and the API.

Overview

RoboCo implements a structured organizational hierarchy with formal communication protocols, task management, and quality controls. The system enables a single human (CEO) to orchestrate complex multi-project development at scale.

CEO (You, the human)
    │
    ├── Intake (on-demand interviewer: chats only with you to draft a task)
    ├── Secretary (on-demand chief-of-staff: reads company state, runs gated directives)
    ├── PR Reviewer (read-only main reviewer: inbound external/fork + internal PRs, and the root→master in-path gate)
    │
    └── Board (3 agents)
         ├── Product Owner
         ├── Head of Marketing
         └── Auditor (silent observer, reports to you)
              │
              └── Main PM (coordinates all cells)
                   │
                   ├── Backend Cell (6 agents: 2 Devs, 1 QA, 1 PM, 1 Documenter, 1 PR Reviewer)
                   ├── Frontend Cell (6 agents: 2 Devs, 1 QA, 1 PM, 1 Documenter, 1 PR Reviewer)
                   └── UX/UI Cell (6 agents: 2 Devs, 1 QA, 1 PM, 1 Documenter, 1 PR Reviewer)

The 26 agents = Intake + Secretary + PR Reviewer + DevOps + the Board (3) + Main PM + the three 6-agent cells (18). Agents run on Anthropic Claude by default, or on xAI Grok, OpenAI Codex, Google Gemini, or Moonshot Kimi K3 (each on its own official CLI and subscription, no metered API key) — see the provider note under Configuration.

How it works

You hand a task to the company; it runs through a real build → review → document → merge pipeline and comes back to you to approve.

One full loop, put simply:

1. You give the Board a task — they review it. The Product Owner and Head of Marketing turn your ask into requirements and acceptance criteria.
2. You approve — the Main PM starts the work. A notification asks for your Approve & Start decision; approve, and the Main PM breaks it into per-cell subtasks.
3. Each cell's PM delegates, supports, and triages its developers (UX/UI, Frontend, Backend).
4. Developers build it, QA verifies and gates it, Documenters keep the books.
5. Cell PMs merge their PRs into the Main PM's branch.
6. The Main PM opens the final PR and notifies you "It's done!" — you approve and merge, or send it back for rework. (Only you ever merge to master.)

— Full circle —

See the full walkthrough, with screenshots →

Or watch the full panel walkthrough (video) →

Project Structure

roboco/
├── roboco/                      # Main Python package
│   ├── api/                     # FastAPI routes & schemas
│   │   ├── routes/              # API endpoints (tasks, git, agents, etc.)
│   │   └── schemas/             # Pydantic request/response models
│   ├── services/                # Business logic services
│   │   ├── task.py              # Task lifecycle management
│   │   ├── workspace.py         # Multi-agent workspace management
│   │   ├── messaging.py         # Agent communication
│   │   └── optimal.py           # RAG/Knowledge base (in-house pgvector)
│   ├── models/                  # Pydantic domain models
│   ├── db/                      # SQLAlchemy ORM & session
│   ├── enforcement/             # Task lifecycle state machine
│   ├── runtime/                 # Orchestrator for agent spawning
│   ├── agents/                  # Agent base classes
│   ├── mcp/                     # MCP server implementations
│   └── config.py                # Application configuration
├── agents/
│   └── prompts/                 # Agent system prompts (roles, teams, identities)
├── docs/
│   ├── rag/                     # Agent knowledge base (indexed into RAG)
│   └── map/                     # Exhaustive codebase map (agent-facing)
├── alembic/                     # Database migrations
├── motion/                      # Video/motion-graphics toolchain
├── panel/                       # Next.js 16 control panel (served on :3000 via nginx)
├── scripts/                     # Bootstrap and utility scripts (bootstrap.sh for make quickstart)
├── CLAUDE.md                    # Claude Code guidance
├── docker-compose.yml           # Full stack, built from source
└── docker-compose.registry.yml  # Full stack, pulled from the image registry

Running RoboCo

You need Docker + Docker Compose and a Claude Code auth directory on the host (~/.claude, mounted into the orchestrator so agents can reach the model). Copy .env.example to .env and set at least ROBOCO_ENCRYPTION_KEY and ROBOCO_AGENT_AUTH_SECRET (that file shows how to generate each). However you start it, the whole company is reachable at one origin: http://localhost:3000.

This is the beginning of the README. Read the rest at the original. Read the full README ↗