One agent writes code. An entourage ships it.
The orchestration layer that turns solo AI agents into governed, coordinated engineering teams.
MCP-native · Event-sourced · Human-in-the-loop
You absolutely should. Entourage doesn't replace your agent — it gives it a production-grade backbone.
| Solo agent | With Entourage |
|---|---|
| One agent, one chat thread | Multiple agents coordinated across tasks |
| Context window is the only memory | Persistent tasks, events, sessions — survive restarts |
| No spending limits — hope for the best | Per-session and daily budget caps, cost tracking per task |
| Freeform execution — anything goes | State machine enforces valid transitions (can't merge without review) |
| You manually review everything | Structured review cycles with file-anchored comments and verdicts |
| Agent works silently until done | Agent pauses to ask you questions, waits for approval |
| Code goes straight to a branch | Isolated git worktrees per task — agents can't stomp each other |
| Chat history is the audit trail | Every action is an immutable event (who did what, when, why) |
| You trigger work manually | GitHub webhooks auto-create tasks from issues and PRs |
| One project, one person | Multi-tenant: orgs → teams → agents, API key scoping |
In short: Claude is the developer. Entourage is the engineering org that developer works inside — with task boards, code review, access controls, cost tracking, and human oversight.
┌─────────────┐ ┌─────────────┐ ┌──────────────┐
│ AI Agents │──MCP───▶│ Entourage │◀──HTTP──│ Dashboard │
│ (Claude, │ stdio │ Backend │ │ (React) │
│ etc.) │◀────────│ │────────▶│ │
└─────────────┘ └──────┬──────┘ └──────────────┘
│
┌──────────┼──────────┐
│ │ │
PostgreSQL Redis Git
(all state) (pub/sub) (worktrees)
- You define tasks. Entourage assigns them to agents.
- Agents write code in isolated git worktrees via MCP tools.
- When stuck, agents ask humans — and wait for a response.
- Finished work goes through code review with approve/reject/request-changes.
- Approved tasks merge via a managed queue. Every step is event-sourced.
Humans stay in control. Agents stay productive. Nothing ships without oversight.
|
Governed task workflow
Safe git operations
Cost controls
|
Human oversight
Multi-agent coordination
Production-ready integrations
|
# 1. Infrastructure
docker compose up -d # Postgres 16 + Redis 7
# 2. Backend
cd packages/backend
uv sync && uv run alembic upgrade head
uv run uvicorn openclaw.main:app --reload
# 3. MCP server
cd packages/mcp-server
npm install && npm run build
# 4. Frontend dashboard
cd packages/frontend
npm install && npm run dev # http://localhost:5173
# 5. CLI — run an agent
cd packages/backend
uv run entourage login --api-key oc_your_key_here
uv run entourage status # See your team
uv run entourage run AGENT_ID --task 1Prerequisites: Docker Desktop, Python 3.12+ with uv, Node.js 18+
50 tools across 14 categories. Agents discover and call these via the Model Context Protocol.
| Category | Tools | Count |
|---|---|---|
| Platform | ping |
1 |
| Orgs & Teams | list_orgs create_org list_teams create_team get_team |
5 |
| Agents | list_agents create_agent |
2 |
| Repos | list_repos register_repo |
2 |
| Tasks | create_task list_tasks get_task update_task change_task_status assign_task get_task_events |
7 |
| Messages | send_message get_inbox |
2 |
| Git | create_worktree get_worktree remove_worktree get_task_diff get_changed_files read_file get_commits |
7 |
| Sessions | start_session record_usage end_session check_budget get_cost_summary |
5 |
| Human-in-the-loop | ask_human get_pending_requests respond_to_request |
3 |
| Reviews | request_review approve_task reject_task get_merge_status get_review_feedback |
5 |
| Auth | authenticate |
1 |
| Webhooks | create_webhook list_webhooks update_webhook |
3 |
| Settings | get_team_settings update_team_settings get_team_conventions add_team_convention |
4 |
| Orchestration | create_tasks_batch wait_for_task_completion list_team_agents |
3 |
packages/
backend/ Python — FastAPI + SQLAlchemy 2.0 + Alembic
mcp-server/ TypeScript — 47 MCP tool definitions
frontend/ React 19 + Vite + TanStack Query
15 database models, 8 Alembic migrations, 11 API routers, event sourcing throughout.
Entourage dispatches work to pluggable coding agent backends:
| Adapter | CLI | MCP Support | Notes |
|---|---|---|---|
| Claude Code | claude |
✅ Native | Full MCP integration via --mcp-config |
| Codex | codex |
✅ Native | OpenAI's agent with --full-auto --mcp-config |
| Aider | aider |
❌ REST | No MCP; prompt includes curl-based API instructions |
Check adapter availability: entourage adapters
entourage status # Show team status (agents, tasks, requests)
entourage agents # List agents and their current state
entourage tasks [--status STATUS] # List tasks with optional filter
entourage run AGENT_ID [--task N] # Dispatch an agent to work on a task
entourage adapters # Show available adapters + readiness
entourage respond REQUEST_ID MSG # Respond to a human-in-the-loop request
entourage login [--api-key KEY] # Authenticate (JWT or API key)
entourage logout # Remove stored credentialscd packages/backend
uv run pytest tests/ -v # 167 tests, ~21s
uv run pytest tests/ --run-e2e # Include live agent E2E testsPer-test savepoint rollback — fully isolated, no cleanup, runs against real Postgres. Includes a full lifecycle integration test exercising: task creation → assignment → human-in-the-loop → code review → approval → merge → done.
Learn how to actually use Entourage day-to-day:
| Guide | What you'll learn |
|---|---|
| Getting Started | Zero to a working AI team in 5 minutes |
| Daily Workflow | What a typical day looks like with governed agents |
| Multi-Agent Teams | Manager + engineers coordinating on complex features |
| Cost Control | Budget caps, per-task tracking, preventing runaway spend |
| Webhook Automation | GitHub issues auto-create tasks for your agents |
Runnable scripts you can try right now (examples/). All examples handle auth automatically — each run registers a fresh user and authenticates via JWT.
python examples/quickstart.py # Full lifecycle in 30 seconds
python examples/multi_agent.py # Batch task DAG + two agents coordinating
python examples/human_in_the_loop.py # Agent pauses, asks human, continues
python examples/code_review_flow.py # Review → comments → approve → merge
python examples/webhook_automation.py # GitHub webhook + HMAC verification
python examples/batch_orchestration.py # DAG decomposition + 4 specialist agents| Doc | What's inside |
|---|---|
| Architecture | System design, data flow, subsystems |
| Database Schema | 15 tables, relationships, migrations |
| Task State Machine | Transitions, DAG, review flow, event types |
| MCP Tools Reference | All 47 tools with parameters |
| Development Guide | Setup, testing, patterns, project structure |
| Phase | What | Status |
|---|---|---|
| 0 | Project skeleton + MCP | ✅ |
| 1 | Orgs, teams, agents, repos | ✅ |
| 2 | Tasks, state machine, messages, events | ✅ |
| 3 | Git integration (worktrees, branch-per-task) | ✅ |
| 4 | Agent sessions + cost controls | ✅ |
| 5 | Real-time dashboard (WebSocket + Redis) | ✅ |
| 6 | Multi-agent dispatch (PG LISTEN/NOTIFY) | ✅ |
| 7 | Human-in-the-loop (approvals, questions) | ✅ |
| 8 | Code review + merge worker | ✅ |
| 9 | Auth + multi-tenant (JWT, API keys) | ✅ |
| 10 | Webhooks + team settings | ✅ |
| 11 | Agent adapters + CLI + runner | ✅ |
| 12 | Codex + Aider adapters | ✅ |
| 13 | Merge worker (git merge/rebase/squash) | ✅ |
| 14 | Auth on all API routes + CLI login | ✅ |
| 15 | Dashboard polish (human requests, reviews, agent status) | ✅ |
| 16 | Multi-agent orchestration (batch tasks, wait, team agents) | ✅ |
| 17 | Full-flow E2E test + docs | ✅ |
MIT