{"id":51253363,"url":"https://github.com/rennf93/roboco","last_synced_at":"2026-06-29T08:30:25.990Z","repository":{"id":362526495,"uuid":"1112644870","full_name":"rennf93/roboco","owner":"rennf93","description":"Not a loop. Not a harness. Not a worflow. Not a framework. An AI Agents Organization. RoboCo: 25-agent software company with role-gated lifecycle. Self-hosted. AGPL.","archived":false,"fork":false,"pushed_at":"2026-06-26T01:01:53.000Z","size":16262,"stargazers_count":44,"open_issues_count":1,"forks_count":8,"subscribers_count":2,"default_branch":"master","last_synced_at":"2026-06-26T01:11:58.408Z","etag":null,"topics":["agentic-ai","agentic-workflow","claude","state-machine"],"latest_commit_sha":null,"homepage":"https://rennf93.github.io/roboco/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rennf93.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":"CLA.md"},"funding":{"github":"rennf93","custom":["https://paypal.me/renzof93"]}},"created_at":"2025-12-08T22:59:51.000Z","updated_at":"2026-06-26T00:59:02.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/rennf93/roboco","commit_stats":null,"previous_names":["rennf93/roboco"],"tags_count":14,"template":false,"template_full_name":null,"purl":"pkg:github/rennf93/roboco","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rennf93%2Froboco","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rennf93%2Froboco/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rennf93%2Froboco/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rennf93%2Froboco/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rennf93","download_url":"https://codeload.github.com/rennf93/roboco/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rennf93%2Froboco/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34919882,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-29T02:00:05.398Z","response_time":58,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agentic-ai","agentic-workflow","claude","state-machine"],"created_at":"2026-06-29T08:30:25.364Z","updated_at":"2026-06-29T08:30:25.977Z","avatar_url":"https://github.com/rennf93.png","language":"Python","funding_links":["https://github.com/sponsors/rennf93","https://paypal.me/renzof93"],"categories":[],"sub_categories":[],"readme":"# RoboCo\n\nAI Agents Company - A virtual organization of 25 AI agents + 1 human CEO, designed to operate as a complete software development workforce.\n\n\u003ctable align=\"center\"\u003e\n\u003ctr\u003e\n\u003ctd width=\"50%\" align=\"center\"\u003e\n  \u003ca href=\"https://www.youtube.com/watch?v=t1QNqJgBmkM\"\u003e\n    \u003cimg src=\"https://img.youtube.com/vi/t1QNqJgBmkM/maxresdefault.jpg\" alt=\"Watch the 26-minute RoboCo intro on YouTube — what it is, a walkthrough, and how to use it\" width=\"100%\"\u003e\n  \u003c/a\u003e\n  \u003cbr\u003e\n  \u003csub\u003e▶ \u003cb\u003e\u003ca href=\"https://www.youtube.com/watch?v=t1QNqJgBmkM\"\u003eWatch the 26-min intro\u003c/a\u003e\u003c/b\u003e\u003cbr\u003ewhat it is, a walkthrough, and how to use it\u003c/sub\u003e\n\u003c/td\u003e\n\u003ctd width=\"50%\" align=\"center\"\u003e\n  \u003ca href=\"https://www.youtube.com/watch?v=xige_EUIjIA\"\u003e\n    \u003cimg src=\"https://img.youtube.com/vi/xige_EUIjIA/maxresdefault.jpg\" alt=\"Watch the 2.5-hour Working with RoboCo build session on YouTube — taking a conversation all the way to a shipped feature\" width=\"100%\"\u003e\n  \u003c/a\u003e\n  \u003cbr\u003e\n  \u003csub\u003e▶ \u003cb\u003e\u003ca href=\"https://www.youtube.com/watch?v=xige_EUIjIA\"\u003eWatch the 2.5-hour build session\u003c/a\u003e\u003c/b\u003e\u003cbr\u003ea conversation → a shipped feature\u003c/sub\u003e\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/videos/panel-teaser.gif\" alt=\"Twelve-second looping preview of the RoboCo control panel — the org tree, a task in progress, and an approval queue.\" width=\"80%\"\u003e\n  \u003cbr\u003e\n  \u003csub\u003e\u003ca href=\"docs/videos/panel-full-walkthrough.mp4\"\u003eWatch the full 2:33 walkthrough (.mp4) →\u003c/a\u003e\u003c/sub\u003e\n\u003c/p\u003e\n\n\u003e [!WARNING]\n\u003e **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.\n\n\u003e [!TIP]\n\u003e 📚 **Full documentation:** **[rennf93.github.io/roboco](https://rennf93.github.io/roboco/)** — install \u0026 first run, the company model, a page-by-page panel reference, model providers, the optional subsystems, deployment, and the API.\n\n## Overview\n\nRoboCo 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.\n\n```\nCEO (You, the human)\n    │\n    ├── Intake (on-demand interviewer: chats only with you to draft a task)\n    ├── Secretary (on-demand chief-of-staff: reads company state, runs gated directives)\n    ├── PR Reviewer (read-only main reviewer: inbound external/fork + internal PRs, and the root→master in-path gate)\n    │\n    └── Board (3 agents)\n         ├── Product Owner\n         ├── Head of Marketing\n         └── Auditor (silent observer, reports to you)\n              │\n              └── Main PM (coordinates all cells)\n                   │\n                   ├── Backend Cell (6 agents: 2 Devs, 1 QA, 1 PM, 1 Documenter, 1 PR Reviewer)\n                   ├── Frontend Cell (6 agents: 2 Devs, 1 QA, 1 PM, 1 Documenter, 1 PR Reviewer)\n                   └── UX/UI Cell (6 agents: 2 Devs, 1 QA, 1 PM, 1 Documenter, 1 PR Reviewer)\n```\n\nThe 25 agents = Intake + Secretary + PR Reviewer + the Board (3) + Main PM + the three 6-agent cells (18). Agents run on Anthropic Claude by default, or on xAI Grok (the official `grok` CLI on a SuperGrok subscription) — see the provider note under Configuration.\n\n## How it works\n\nYou hand a task to the company; it runs through a real *build → review → document → merge* pipeline and comes back to you to approve.\n\nOne full loop, put simply:\n\n1. **You give the Board a task — they review it.** The Product Owner and Head of Marketing turn your ask into requirements and acceptance criteria.\n2. **You approve — the Main PM starts the work.** A notification asks for your *Approve \u0026 Start* decision; approve, and the Main PM breaks it into per-cell subtasks.\n3. **Each cell's PM delegates, supports, and triages** its developers (UX/UI, Frontend, Backend).\n4. **Developers build it, QA verifies and gates it, Documenters keep the books.**\n5. **Cell PMs merge their PRs into the Main PM's branch.**\n6. **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`.)*\n\n**— Full circle —**\n\n**[See the full walkthrough, with screenshots →](docs/how-to/README.md)**\n\n**[Or watch the full panel walkthrough (video) →](docs/videos/panel-full-walkthrough.mp4)**\n\n## Project Structure\n\n```\nroboco/\n├── roboco/                      # Main Python package\n│   ├── api/                     # FastAPI routes \u0026 schemas\n│   │   ├── routes/              # API endpoints (tasks, git, agents, etc.)\n│   │   └── schemas/             # Pydantic request/response models\n│   ├── services/                # Business logic services\n│   │   ├── task.py              # Task lifecycle management\n│   │   ├── workspace.py         # Multi-agent workspace management\n│   │   ├── messaging.py         # Agent communication\n│   │   └── optimal.py           # RAG/Knowledge base (in-house pgvector)\n│   ├── models/                  # Pydantic domain models\n│   ├── db/                      # SQLAlchemy ORM \u0026 session\n│   ├── enforcement/             # Task lifecycle state machine\n│   ├── runtime/                 # Orchestrator for agent spawning\n│   ├── agents/                  # Agent base classes\n│   ├── mcp/                     # MCP server implementations\n│   └── config.py                # Application configuration\n├── agents/\n│   └── prompts/                 # Agent system prompts (roles, teams, identities)\n├── docs/\n│   ├── how-to/                 # Visual walkthrough — 5-chapter guide (start at README.md)\n│   └── rag/                     # Agent knowledge base (indexed into RAG)\n├── alembic/                     # Database migrations\n├── CLAUDE.md                    # Claude Code guidance\n├── docker-compose.yml           # Full stack, built from source\n└── docker-compose.registry.yml  # Full stack, pulled from the image registry\n```\n\n## Running RoboCo\n\nYou 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**.\n\n**Optional — run agents on xAI Grok instead of Claude.** RoboCo can spawn agents on xAI's official `grok` CLI authenticated by a SuperGrok subscription (no metered API key). Run `grok login` once on the host and point `ROBOCO_HOST_GROK_DIR` at the resulting `~/.grok` so it mounts into Grok agents; the orchestrator keeps the ~6h token refreshed for you. See the Grok block in `.env.example` (`ROBOCO_HOST_GROK_DIR`, `ROBOCO_GROK_AGENT_IMAGE`, `ROBOCO_GROK_CLI_MODEL`, `ROBOCO_GROK_REASONING_EFFORT`).\n\n### Option 1 — Run the pre-built images (quickest)\n\nEvery release publishes all RoboCo images to both the GitHub Container Registry and Docker Hub, so you can run the full stack without building anything. Use the registry compose:\n\n```bash\ngit clone https://github.com/rennf93/roboco.git \u0026\u0026 cd roboco\ncp .env.example .env                                   # then edit in your secrets\ndocker compose -f docker-compose.registry.yml pull\ndocker compose -f docker-compose.registry.yml up -d\n```\n\nChoose the registry and version with two env vars (defaults shown):\n\n```bash\nROBOCO_REGISTRY=ghcr.io/rennf93   # or docker.io/renzof93\nROBOCO_VERSION=latest             # or a pinned release, e.g. 0.14.0\n```\n\nThe orchestrator spawns the matching pre-built agent images on demand — no build toolchain or source compile on your host.\n\n### Option 2 — Build from source\n\nThe same full stack, built locally from the Dockerfiles instead of pulled:\n\n```bash\ngit clone https://github.com/rennf93/roboco.git \u0026\u0026 cd roboco\ncp .env.example .env              # then edit in your secrets\ndocker compose up -d              # builds images on first run, then starts everything\n```\n\n### Option 3 — Local development (no full stack)\n\nFor hacking on the code itself, run only the backing services in Docker and the API on your host. RoboCo's own code requires **Python 3.13+** (`uv` will fetch it if needed):\n\n```bash\nuv sync\ndocker compose up -d postgres redis ollama   # backing services only\nuv run alembic upgrade head                   # migrate the database\nuv run python -m roboco.cli                   # API + orchestrator\n\n# Or just the API without the orchestrator:\nuv run uvicorn roboco.api.app:app --reload --host 0.0.0.0 --port 8000\n```\n\n## Configuration\n\nKey environment variables (see `roboco/config.py` for all options):\n\n```bash\n# API Server\nROBOCO_HOST=0.0.0.0\nROBOCO_PORT=8000\n\n# Database\nROBOCO_DATABASE_HOST=localhost\nROBOCO_DATABASE_PORT=5432\nROBOCO_DATABASE_NAME=roboco\n\n# Workspaces (Multi-Agent Git)\nROBOCO_WORKSPACES_ROOT=/data/workspaces\nROBOCO_WORKSPACE_AUTO_CLONE=true\n\n# RAG/LLM\nROBOCO_LOCAL_LLM_BASE_URL=http://roboco-ollama:11434/v1\nROBOCO_LOCAL_LLM_MODEL=glm-5.2:cloud\n\n# Feature flags (default-off unless noted; toggle from Settings → Feature Flags)\nROBOCO_CONVENTIONS_ENABLED=false        # per-project architectural conventions standard\nROBOCO_TOOLCHAIN_MATCH_ENABLED=false    # build each target project under its own Python\nROBOCO_OVERLOAD_BREAK_ENABLED=true      # park a provider on a persistent model-API overload\n```\n\n## Multi-Agent Workspace Structure\n\nEach agent gets their own git clone for parallel development:\n\n```\n{ROBOCO_WORKSPACES_ROOT}/\n└── {project-slug}/\n    └── {team}/\n        └── {agent-slug}/\n            └── [git repository]\n\nExample:\n/data/workspaces/roboco/backend/be-dev-1/\n/data/workspaces/roboco/backend/be-dev-2/\n```\n\n## Task Lifecycle\n\n```\nbacklog → pending → claimed → in_progress → verifying → awaiting_qa\n    ↓                              ↓              ↓           ↓\ncancelled                      blocked      needs_revision   awaiting_documentation\n                               paused                              ↓\n                                                           awaiting_pm_review\n                                                                   ↓\n                                                           awaiting_ceo_approval\n                                                                   ↓\n                                                              completed\n```\n\nAssembled, PR-bearing tasks pass through one extra stage — the in-path PR-review gate — before the PM merges:\n\n```\nin_progress → awaiting_pr_review → awaiting_pm_review\n   (submit_up /      (pr_pass)\n    submit_root)     (pr_fail → needs_revision)\n```\n\nThe cell PM's `submit_up` (cell→root PR) and the Main PM's `submit_root` (root→master PR) open the assembled PR and enter the gate; a PR reviewer `pr_pass`es it on to the PM merge or `pr_fail`s it back. Leaf dev tasks (reviewed by QA) and branchless coordination roots skip the gate.\n\n## API Endpoints\n\nDomain routes are mounted under `/api`:\n\n| Route Group | Description |\n|-------------|-------------|\n| `/api/tasks` | Task CRUD, lifecycle, claiming |\n| `/api/agents` | Agent management |\n| `/api/git` | Git operations (status, commit, push, PR) |\n| `/api/sessions` | Communication sessions |\n| `/api/messages` | Agent messages |\n| `/api/projects` | Project (repo) management |\n| `/api/work-sessions` | Git work session tracking |\n| `/api/optimal` | RAG/Knowledge base queries |\n| `/api/journals` | Agent journals/reflections |\n| `/api/orchestrator/status` | Orchestrator / dispatcher status |\n\nThe agent **gateway** verbs are served separately under `/api/v1/flow/{role}/{verb}` (intent verbs) and `/api/v1/do` (content tools) — see the [Agent Gateway](CLAUDE.md#agent-gateway).\n\n## Development\n\n```bash\n# Install dev dependencies\nuv sync --all-extras\n\n# Run tests\nuv run pytest\n\n# Format and lint\nuv run ruff format .\nuv run ruff check .\nuv run mypy roboco/\n\n# Type checking\nuv run mypy roboco/\n```\n\n## Core Principles\n\n1. **Everything is a task** - All work is tracked and documented\n2. **No work without a task** - Create task record first\n3. **No task without acceptance criteria** - How do we know it's done?\n4. **No closure without documentation** - Future agents need context\n5. **Communication is constant** - Stream reasoning, log everything\n6. **The Auditor sees all** - Quality monitored silently\n7. **CEO approves major changes** - Human-in-the-loop for critical decisions\n\n## Technology Stack\n\n| Layer | Technology |\n|-------|------------|\n| API Framework | FastAPI |\n| Database | PostgreSQL + SQLAlchemy (async) |\n| Vector Store | PostgreSQL + pgvector (in-house engine) |\n| Cache/Queue | Redis |\n| RAG Engine | in-house (asyncpg + pgvector, hybrid retrieval) |\n| Embeddings | qwen3-embedding:0.6b (Ollama) |\n| Local LLM | Ollama (glm-5.2:cloud) |\n| Cloud LLM | Claude API (Anthropic) + xAI Grok (official `grok` CLI, SuperGrok subscription) |\n| Package Manager | uv |\n\n## Status\n\n**Core Infrastructure** (Complete)\n- [x] Data models (Pydantic)\n- [x] Database ORM (SQLAlchemy async)\n- [x] Task lifecycle state machine\n- [x] Multi-agent workspace management\n- [x] Agent prompts (25 agents)\n- [x] Messaging API\n- [x] Task API with full lifecycle\n- [x] Git operations API\n- [x] RAG/Knowledge base (in-house pgvector engine)\n- [x] Agent orchestrator\n- [x] CEO approval workflow\n- [x] Pluggable agent providers (Claude Code + xAI Grok on the official `grok` CLI)\n- [x] Inbound PR review (read-only PR-reviewer + CEO supersede/dismiss queue)\n- [x] Self-healing CI loop for RoboCo's own repo (default-off, CEO-gated)\n- [x] Business Goals tab with a live Company Scorecard (delivery, spend-vs-budget, lead time)\n\n**In Progress**\n- [x] Frontend panel (vendored under `panel/`, served through nginx on :3000)\n- [ ] Full agent autonomy testing\n\n## Security\n\n\u003e [!IMPORTANT]\n\u003e **Do not expose RoboCo to the public internet as-is.** It is designed to run on a trusted private network (homelab / LAN).\n\n**Agent authentication.** Requests identify the caller with `X-Agent-Id` / `X-Agent-Role` headers. The orchestrator issues each spawned agent an HMAC token (`X-Agent-Token`, signed with `ROBOCO_AGENT_AUTH_SECRET`) that binds its id, role and team. Token enforcement is gated by `ROBOCO_AGENT_AUTH_REQUIRED`:\n\n- **`ROBOCO_AGENT_AUTH_REQUIRED` unset/false (default):** *header-trust mode* — the role headers are accepted without a token, so any client that can reach the API may claim any role (including `ceo`). The API logs a warning at startup in this mode. Acceptable only on a trusted network.\n- **`ROBOCO_AGENT_AUTH_REQUIRED=true`:** every request must carry a valid token; an agent cannot spoof another agent's role. The control panel keeps working because **nginx** — the only trusted hop between the browser and the API — injects the CEO token (`X-Agent-Token`) on `/api` and `/ws`, so the browser never holds the signing secret. Generate that token with `make panel-token` and set it as `ROBOCO_PANEL_AGENT_TOKEN` in `.env` before enabling secure mode.\n\n**WebSocket streams.** Token enforcement is currently REST-only. The `/ws/*` endpoints authenticate by `agent_id` query param at most and do not yet validate `X-Agent-Token`, even in secure mode — nginx injects the token so the panel works, but a direct WebSocket connection that bypasses nginx is not rejected. In particular the operator stream `/ws/system` (rate-limit lifecycle + token-usage snapshots for the dashboard) is unauthenticated. These streams are read-only — no control surface, secrets, or task content — but treat the orchestrator port as trusted-network-only until WebSocket auth lands.\n\n**Secrets** (the Fernet `ROBOCO_ENCRYPTION_KEY`, GitHub PATs) live encrypted in the database and in gitignored env files — never in the repo. Per-project git tokens are Fernet-encrypted at rest and never returned by the API.\n\n## License\n\nCopyright (c) 2026 Renzo Franceschini\n\nRoboCo is licensed under the **GNU Affero General Public License v3.0** (AGPL-3.0). See [`LICENSE`](./LICENSE) for the full text.\n\nThe AGPL's network-use clause (section 13) means that if you run a modified version of RoboCo as a network service, you must make your modified source available to its users. This keeps the project open while preventing closed, hosted re-distributions.\n\n## Contributing\n\nContributions are welcome. All contributors must sign the Contributor License Agreement ([`CLA.md`](./CLA.md)) — this is automated on your first pull request. See [`CONTRIBUTING.md`](./CONTRIBUTING.md) for the workflow and why the CLA exists.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frennf93%2Froboco","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frennf93%2Froboco","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frennf93%2Froboco/lists"}