{"id":47671927,"url":"https://github.com/cloga/optimus-code","last_synced_at":"2026-05-29T07:18:42.179Z","repository":{"id":342726560,"uuid":"1174844155","full_name":"cloga/optimus-code","owner":"cloga","description":"Universal multi-agent orchestrator (MCP Server) for any AI coding tool — VS Code Copilot, Cursor, Windsurf, Claude Code, and more.","archived":false,"fork":false,"pushed_at":"2026-03-31T11:46:02.000Z","size":24844,"stargazers_count":2,"open_issues_count":53,"forks_count":2,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-04-03T01:05:42.580Z","etag":null,"topics":["claude-code","github-copilot","mcp","multi-agent","orchestrator"],"latest_commit_sha":null,"homepage":"https://cloga.github.io/optimus-code","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cloga.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"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":null}},"created_at":"2026-03-06T22:48:17.000Z","updated_at":"2026-03-31T11:36:53.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/cloga/optimus-code","commit_stats":null,"previous_names":["cloga/optimus-code"],"tags_count":90,"template":false,"template_full_name":null,"purl":"pkg:github/cloga/optimus-code","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloga%2Foptimus-code","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloga%2Foptimus-code/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloga%2Foptimus-code/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloga%2Foptimus-code/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cloga","download_url":"https://codeload.github.com/cloga/optimus-code/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloga%2Foptimus-code/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31426194,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-05T02:22:46.605Z","status":"ssl_error","status_checked_at":"2026-04-05T02:22:33.263Z","response_time":75,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["claude-code","github-copilot","mcp","multi-agent","orchestrator"],"created_at":"2026-04-02T12:59:52.787Z","updated_at":"2026-05-29T07:18:42.147Z","avatar_url":"https://github.com/cloga.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\r\n  \u003ch1\u003eOptimus Code\u003c/h1\u003e\r\n  \u003cp\u003e\u003cb\u003eUniversal Multi-Agent Orchestrator for any MCP-compatible AI coding tool.\u003c/b\u003e\u003c/p\u003e\r\n\r\n  [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)\r\n  [![Framework: Model Context Protocol](https://img.shields.io/badge/MCP-Native-brightgreen.svg)](#)\r\n\r\n  [Landing Page](https://cloga.github.io/optimus-code/) · [Architecture Whitepaper](docs/ARCHITECTURE.md)\r\n\u003c/div\u003e\r\n\r\n---\r\n\r\n## What is Optimus Code?\r\n\r\nOptimus Code is a **Multi-Agent Orchestration Engine** built on the [Model Context Protocol (MCP)](https://modelcontextprotocol.io). It works with **any MCP-compatible client** — VS Code (GitHub Copilot), Cursor, Windsurf, Claude Code, Goose, Roo Cline, and more.\r\n\r\nIt transforms a single AI assistant into a coordinated swarm of specialized agents (Architect, PM, QA, Dev…) that can collaborate, debate, and execute complex software engineering tasks.\r\n\r\n\u003e **100% editor-agnostic.** Pure Node.js MCP Server. No VS Code extension required.\r\n\r\n---\r\n\r\n## Quick Start\r\n\r\n\u003e **For AI Coding Agents:** Follow these steps exactly. All commands should run in the user's target project directory.\r\n\r\n### Step 1: Initialize workspace\r\n\r\n```bash\r\nnpx -y github:cloga/optimus-code init\r\n```\r\n\r\nThis creates a `.optimus/` folder with agent definitions, skills, and config in the current directory. It also writes a canonical MCP source file at `.optimus/config/mcp-servers.json` and generates client configs for:\r\n\r\n- VS Code / GitHub Copilot: `.vscode/mcp.json`\r\n- GitHub Copilot CLI: `.copilot/mcp-config.json`\r\n- Claude Code: `.mcp.json`\r\n\r\nFor GitHub Copilot CLI, Optimus also generates launcher scripts so you do not need to remember `--additional-mcp-config`:\r\n\r\n- Windows PowerShell: `copilot-optimus.ps1`\r\n- Windows cmd.exe: `copilot-optimus.cmd`\r\n- macOS / Linux: `copilot-optimus`\r\n\r\n### Step 2: (Optional) Configure MCP for non-VS-Code clients\r\n\r\n\u003e **VS Code and Claude Code users:** Skip this step. `optimus init` already generated the project-local MCP files those clients expect.\r\n\u003e\r\n\u003e **GitHub Copilot CLI users:** Start Copilot CLI through one of the generated `copilot-optimus*` launchers so the project-local `.copilot/mcp-config.json` is always loaded.\r\n\r\nFor Cursor, Windsurf, Roo Cline, or other MCP clients, configure manually:\r\n\r\n#### Cursor / Windsurf / Roo Cline\r\n\r\nCreate or edit `.cursor/mcp.json` (or equivalent) in the project root:\r\n\r\n```json\r\n{\r\n  \"mcpServers\": {\r\n    \"optimus-swarm\": {\r\n      \"command\": \"npx\",\r\n      \"args\": [\"-y\", \"github:cloga/optimus-code\", \"serve\"],\r\n      \"type\": \"stdio\"\r\n    }\r\n  }\r\n}\r\n```\r\n\r\n#### Any other MCP client\r\n\r\nUse these values in your client's MCP server configuration:\r\n\r\n| Field | Value |\r\n|---|---|\r\n| **name** | `optimus-swarm` |\r\n| **command** | `npx` |\r\n| **args** | `[\"-y\", \"github:cloga/optimus-code\", \"serve\"]` |\r\n| **transport** | `stdio` |\r\n\r\n### Upgrading an existing workspace\r\n\r\nIf you've previously initialized and want to update to the latest skills, roles, and config:\r\n\r\n```bash\r\nnpx -y github:cloga/optimus-code upgrade\r\nnpx -y github:cloga/optimus-code upgrade --disable-project-available-agents\r\n```\r\n\r\nThis force-updates skills, roles, and config from the latest release while preserving your agents (`.optimus/agents/`), runtime data (`.optimus/state/`), and memory. It also regenerates `.vscode/mcp.json`, `.copilot/mcp-config.json`, `.mcp.json`, and the `copilot-optimus*` launchers from `.optimus/config/mcp-servers.json`.\r\n\r\nIn other words, `optimus upgrade` upgrades the current workspace. When you run it via `npx github:cloga/optimus-code upgrade`, you also pick up the latest published CLI package itself, including `optimus go`.\r\n\r\nIf you want to adopt the new user-level `available-agents.json` default after previously using a project-level override, pass `--disable-project-available-agents`. Upgrade will rename `.optimus/config/available-agents.json` to a non-active backup such as `.optimus/config/available-agents.project.disabled.json`, then refresh the project sample file so user-level config becomes authoritative again.\r\n\r\n### Jumping between Optimus projects\r\n\r\nOptimus keeps a global registry of initialized workspaces at `~/.optimus/projects.json`. Every `optimus init` and `optimus upgrade` automatically registers the current project there.\r\n\r\nUse `optimus go` to launch an agent CLI (Copilot or Claude) for any registered Optimus workspace without manually `cd`-ing first:\r\n\r\n```bash\r\noptimus go                              # interactive project picker\r\noptimus go FlightReview                 # launch with default CLI (copilot)\r\noptimus go FR --cli claude              # override CLI for this launch\r\noptimus go FR --continue                # pass-through flags to the CLI\r\noptimus go --scan                       # discover and register projects\r\n```\r\n\r\nThe CLI periodically checks GitHub releases and prints an update notice when a newer version is available. The notice is skipped for `optimus serve` so MCP stdio output stays clean.\r\n\r\n#### Multi-CLI support\r\n\r\n`optimus go` supports both GitHub Copilot CLI and Claude Code CLI. Each project can have a preferred CLI, and you can override it per-launch:\r\n\r\n```bash\r\n# Set global default CLI\r\noptimus go set-default-cli claude\r\n\r\n# Set per-project preferred CLI\r\noptimus go set-cli FlightReview copilot\r\noptimus go set-cli SydneyEvaluation claude\r\n\r\n# Override at launch time (always wins)\r\noptimus go FR --cli claude\r\n```\r\n\r\nResolution order: `--cli` flag → project `preferredCli` → global `defaults.cli` → `copilot`\r\n\r\n### MCP configuration model\r\n\r\nOptimus now treats `.optimus/config/mcp-servers.json` as the single source of truth for workspace MCP server definitions. Edit that file when you want to customize the local Optimus server entry, then run `optimus upgrade` (or regenerate via init in a fresh workspace) to project the same server into each supported client config.\r\n\r\n### Runtime model\r\n\r\nOptimus currently treats the runtime as a **user-level HTTP daemon**. The preferred auto-start target is `~/.optimus/dist/http-runtime.js`, and the daemon serves **multiple workspaces** by carrying `workspace_path` in request bodies (or `X-Optimus-Workspace` for status/stream lookups). In other words, workspace is a **request/session scope**, not the daemon's process identity.\r\n\r\nThis is the current completion target for the runtime architecture: **HTTP per-user multi-workspace daemon with warm pool reuse and explicit workspace routing**. Transports such as named pipes or WebSockets remain future evolution options; they are not required for the current runtime slice.\r\n\r\n### Step 3: (Optional) Enable GitHub integration\r\n\r\nCreate a `.env` file in your project root:\r\n\r\n```bash\r\nGITHUB_TOKEN=ghp_your_token_here\r\n```\r\n\r\nThis enables automated Issue tracking and PR creation via the built-in PM agent.\r\n\r\n### Step 3b: (Optional) Enable Azure DevOps integration\r\n\r\nCreate `.optimus/config/vcs.json`:\r\n\r\n```json\r\n{\r\n  \"provider\": \"azure-devops\",\r\n  \"ado\": {\r\n    \"organization\": \"your-org\",\r\n    \"project\": \"your-project\",\r\n    \"auth\": \"env:ADO_PAT\",\r\n    \"defaults\": {\r\n      \"work_item_type\": \"User Story\",\r\n      \"area_path\": \"Project\\\\Team\\\\Area\",\r\n      \"iteration_path\": \"Project\\\\Sprint 1\",\r\n      \"assigned_to\": \"user@example.com\",\r\n      \"auto_tags\": [\"created-by:optimus-code\"]\r\n    }\r\n  }\r\n}\r\n```\r\n\r\nThe `defaults` section is optional. Any field not provided will use ADO project defaults. All defaults can be overridden per-call via MCP tool parameters.\r\n\r\n---\r\n\r\n## Available MCP Tools\r\n\r\nOnce the server is running, your AI assistant gains these tools:\r\n\r\n| Tool | Description |\r\n|---|---|\r\n| `roster_check` | List all available agent roles (T1 local + T2 project + T3 dynamic) and engine/model bindings |\r\n| `explain_available_agents` | Show the resolved runtime behavior of `available-agents.json`, including candidate transports, selected protocol, and fallback reasons |\r\n| `run_agent` | Run an application-facing Agent Runtime request synchronously and return a normalized envelope |\r\n| `start_agent_run` | Start an application-facing Agent Runtime request asynchronously |\r\n| `get_agent_run_status` | Read the normalized status/result envelope for an Agent Runtime run |\r\n| `resume_agent_run` | Resume a run blocked on manual intervention by supplying the human answer directly |\r\n| `cancel_agent_run` | Cancel an active Agent Runtime run |\r\n| `delegate_task` | Assign a task to a specialized agent with structured role info |\r\n| `delegate_task_async` | Same as above, non-blocking (preferred for a single already-scoped worker task) |\r\n| `optimus_orchestrate` | **Preferred entry point for broad or multi-step requests** — analyze the task, choose delegate/council/plan automatically, and dispatch the best async orchestration path |\r\n| `dispatch_plan_async` | Execute a known dependency-aware plan directly inside Optimus when the work items are already decomposed |\r\n| `dispatch_council` | Spawn parallel expert review (Map-Reduce pattern) |\r\n| `dispatch_council_async` | Same as above, non-blocking (preferred) |\r\n| `check_task_status` | Poll async task/council completion |\r\n| `append_memory` | Save learnings to persistent agent memory |\r\n| `write_blackboard_artifact` | Write artifacts to `.optimus/` (specs, tasks, reports). See routing table in system-instructions |\r\n| `vcs_create_work_item` | Create a work item (GitHub Issue / ADO Work Item) via unified VCS abstraction |\r\n| `vcs_create_pr` | Create a Pull Request via unified VCS abstraction |\r\n| `vcs_merge_pr` | Merge a Pull Request via unified VCS abstraction |\r\n| `vcs_add_comment` | Add a comment to a work item or PR (requires `item_type`) |\r\n| `vcs_update_work_item` | Update an existing work item title/state/labels, plus ADO description, assignee, and priority |\r\n| `vcs_list_work_items` | List work items with state/label filters |\r\n| `vcs_list_pull_requests` | List pull requests with state filter, mergeable status |\r\n| `request_human_input` | Pause execution and ask the human for input |\r\n| `quarantine_role` | Quarantine/unquarantine a misbehaving role |\r\n| `register_meta_cron` | Register a scheduled recurring task |\r\n| `list_meta_crons` | List all registered scheduled tasks |\r\n| `remove_meta_cron` | Remove a scheduled task |\r\n\r\n### Agent Runtime tools\r\n\r\nThe Agent Runtime layer is the application-facing abstraction above raw delegation and transport. It is intended for host applications that want a stable runtime contract without coupling service code to `delegate_task`, CLI transport details, or task-manifest internals.\r\n\r\nTypical flow:\r\n\r\n1. `run_agent` for synchronous request/response execution\r\n2. `start_agent_run` for async execution\r\n3. `get_agent_run_status` to poll a normalized envelope\r\n4. `resume_agent_run` when status is `blocked_manual_intervention`\r\n5. `cancel_agent_run` to stop an active run\r\n\r\n### Choosing the orchestration entry point\r\n\r\nWhen integrating Optimus into an agent workflow, prefer Optimus's own orchestration surfaces over any external built-in sub-agent feature:\r\n\r\n- **Broad or multi-step request** → start with `optimus_orchestrate`\r\n- **Already decomposed dependency graph** → use `dispatch_plan_async`\r\n- **Single already-scoped worker task** → use `delegate_task_async`\r\n\r\nThis keeps the master agent aligned with the same delegate-first orchestration model that Optimus exposes to end users.\r\n\r\n### delegate_task Extended Parameters\r\n\r\n| Parameter | Required | Description |\r\n|---|---|---|\r\n| `role` | ✅ | Role name (e.g., `security-auditor`) |\r\n| `role_description` | | What this role does — used to generate T2 template |\r\n| `role_engine` | | Which engine (e.g., `claude-code`, `github-copilot`, `qwen-code`) |\r\n| `role_model` | | Which model (e.g., `claude-opus-4.6-1m`, `qwen3-coder`) |\r\n| `task_description` | ✅ | Detailed task instructions |\r\n| `output_path` | ✅ | Where to write results |\r\n| `workspace_path` | ✅ | Project root path |\r\n| `context_files` | | Files the agent must read |\r\n| `required_skills` | | Skills the agent needs (pre-flight checked) |\r\n\r\n---\r\n\r\n## Features\r\n\r\n### v1.0.0 Highlights\r\n\r\n- **ACP Protocol Support** — Universal [Agent Client Protocol](https://github.com/anthropics/agent-protocol) adapter enables integration with domestic AI coding agents (Qwen Code, Kimi, Cursor, etc.) via JSON-RPC over NDJSON.\r\n- **Multi-Vendor Engine Architecture** — Engine config uses `protocol` field (`cli` | `acp`) to route adapters. Add new ACP vendors with zero code changes — just a JSON config entry.\r\n- **Problem-First SDLC Workflow** — New lifecycle: PROBLEM → PROPOSAL → SOLUTION → EXECUTE replaces the old proposal-first approach. Experts propose independently before synthesis.\r\n- **Artifact Directory Routing** — Centralized routing table in system-instructions defines where every artifact type goes (`specs/`, `results/`, `reviews/`, `reports/`, `tasks/`).\r\n- **Format Templates** — 7 artifact types with standardized YAML frontmatter and required sections for cross-agent consistency.\r\n- **Cross-Model Council Diversity** — Automatic round-robin assignment of engine:model combinations to council participants, maximizing model diversity by default.\r\n- **Customizable VERDICT Template** — Council verdict format loaded from `.optimus/config/verdict-template.md` instead of hardcoded in code.\r\n- **Clean Artifact Output** — Tool-call traces stripped from output files, ensuring downstream agents receive clean content.\r\n- **Engine Health Tracking** — Per engine:model health monitoring with automatic fallback on consecutive failures.\r\n\r\n### v0.4.0 Highlights\r\n\r\n- **Agent Pause/Resume** — Human-in-the-loop input via `request_human_input` tool.\r\n- **Project Patrol** — Automated cron-based project monitoring with `project-patrol` skill.\r\n- **Mandatory Council Review** — High-impact changes require expert council review before implementation.\r\n\r\n### v0.3.0 Highlights\r\n\r\n- **Plan Mode** — Orchestrator roles (PM, Architect) run with `mode: plan`, cannot write source code, and must delegate implementation to dev roles.\r\n- **Delegation Depth Control** — Maximum 3 layers of nested agent delegation, tracked via `OPTIMUS_DELEGATION_DEPTH` to prevent infinite recursion.\r\n- **Issue Lineage Tracking** — `OPTIMUS_PARENT_ISSUE` is automatically injected into child agent processes, maintaining parent-child relationships across GitHub Issues.\r\n- **`write_blackboard_artifact` Tool** — Allows plan-mode agents to write proposals, requirements, and reports to `.optimus/` without source code write access.\r\n- **`optimus upgrade` Command** — Safe incremental upgrade that refreshes skills, roles, and config while preserving user agents and runtime data.\r\n- **Enhanced ADO Work Items** — `vcs_create_work_item` supports `area_path`, `iteration_path`, `assigned_to`, `parent_id`, `priority` with `vcs.json` defaults, Markdown→HTML conversion, and auto-tagging.\r\n- **Engine/Model Validation** — Engine and model names are validated against `available-agents.json` before being persisted to role templates.\r\n- **Auto-Skill Genesis** — Skills are auto-generated after successful T3 role execution.\r\n- **Rich T3→T2 Precipitation** — New roles get professional-grade role definitions via `role-creator` instead of thin fallback templates.\r\n\r\n## How It Works\r\n\r\n### Self-Evolving Agent Lifecycle (T3→T2→T1)\r\n\r\n```\r\nUser request → Master Agent\r\n                   │\r\n                   ├─① Choose entry point\r\n                   │     ├─ broad / multi-step → optimus_orchestrate\r\n                   │     ├─ explicit dependency graph → dispatch_plan_async\r\n                   │     └─ single scoped task → delegate_task_async\r\n                   │\r\n                   ├─② roster_check (see who's available)\r\n                   │\r\n                   ├─③ Select/create role (role-creator meta-skill)\r\n                   │     └─ T3 first use → auto-creates T2 role template\r\n                   │\r\n                   ├─④ Check/create skills (skill-creator meta-skill)\r\n                   │     └─ Missing? → delegate to skill-creator → retry\r\n                   │\r\n                   ├─⑤ delegate_task_async / dispatch_plan_async executes\r\n                   │\r\n                   └─⑥ Session captured → T2 instantiates to T1\r\n```\r\n\r\n| Tier | Location | What It Is | Created By |\r\n|------|----------|-----------|------------|\r\n| **T3** | *(ephemeral)* | Zero-shot dynamic worker, no file | Master Agent names it |\r\n| **T2** | `.optimus/roles/\u003cname\u003e.md` | Role template with engine/model binding | Auto-precipitated on first use, Master can evolve it |\r\n| **T1** | `.optimus/agents/\u003cname\u003e.md` | Frozen instance snapshot + session state | Auto-created when task completes with session_id |\r\n\r\n**Key invariants:**\r\n- T2 ≥ T1 (every agent instance has a role template)\r\n- T1 is frozen — only `session_id` updates on re-use\r\n- T2 is alive — Master Agent evolves it over time\r\n\r\n### Bootstrap Meta-Skills\r\n\r\nThe system ships with 5 pre-installed skills. Two are **meta-skills** that enable self-evolution:\r\n\r\n| Skill | Type | Purpose |\r\n|-------|------|---------|\r\n| `role-creator` | 🧬 Meta | Teaches Master how to build \u0026 evolve the team |\r\n| `skill-creator` | 🧬 Meta | Teaches Master how to create new skills |\r\n| `delegate-task` | Core | Async-first task delegation protocol |\r\n| `council-review` | Core | Parallel expert review (Map-Reduce) |\r\n| `git-workflow` | Core | Issue First + PR workflow |\r\n\r\n### Supported Adapters\r\n\r\n| Adapter | Protocol | Compatible Agents |\r\n|---------|----------|-------------------|\r\n| `github-copilot` | Copilot CLI text parsing | GitHub Copilot |\r\n| `claude-code` | Claude Code CLI text parsing | Claude Code |\r\n| `acp` | ACP (Agent Client Protocol) — JSON-RPC over stdio | claude-agent-acp, Claude Code, GitHub Copilot (`copilot --acp`), Kimi CLI, Qwen Code, Gemini CLI, and any ACP-compliant agent |\r\n\r\nThe **ACP adapter** is the universal protocol layer that standardizes communication with any agent supporting the [Agent Client Protocol](https://github.com/cloga/optimus-code/issues/319). It uses JSON-RPC over stdio with LSP-style `Content-Length` framing, replacing legacy CLI text parsing with structured session lifecycle messages (`initialize` → `session/new` → `session/prompt` → `session/update` → response).\r\n\r\nTo configure an ACP-based agent for all projects by default, add an entry to `~/.optimus/config/available-agents.json` (or `OPTIMUS_USER_AVAILABLE_AGENTS_PATH`). If a repository needs its own override, copy `.optimus/config/available-agents.project.sample.json` to `.optimus/config/available-agents.json` and edit it there:\r\n\r\n```json\r\n{\r\n  \"id\": \"qwen-acp\",\r\n  \"name\": \"Qwen Code (ACP)\",\r\n  \"adapter\": \"acp\",\r\n  \"executable\": \"qwen\",\r\n  \"args\": [\"--acp\"],\r\n  \"enabled\": true\r\n}\r\n```\r\n\r\nOther examples:\r\n\r\n```json\r\n{ \"id\": \"copilot-acp\", \"name\": \"Copilot (ACP)\", \"adapter\": \"acp\", \"executable\": \"copilot\", \"args\": [\"--acp\"], \"enabled\": true }\r\n{ \"id\": \"gemini-acp\", \"name\": \"Gemini CLI (ACP)\", \"adapter\": \"acp\", \"executable\": \"gemini\", \"args\": [\"--acp\"], \"enabled\": true }\r\n```\r\n\r\n### Engine/Model Resolution\r\n\r\nWhen delegating a task, engine and model are resolved in priority order:\r\n1. Master-provided `role_engine` / `role_model`\r\n2. T2 role frontmatter `engine` / `model`\r\n3. `available-agents.json` (first non-demo engine)\r\n4. Hardcoded fallback: `claude-code`\r\n\r\n### Multi-Engine Configuration\r\n\r\nThe default engine registry lives in `~/.optimus/config/available-agents.json`. Project-level `.optimus/config/available-agents.json` is optional and only needed when a repository should override the user-level defaults. The `protocol` field determines which adapter handles the engine:\r\n\r\nOptimus resolves engine settings in three layers: built-in defaults, then the user-level `~/.optimus/config/available-agents.json` (or `OPTIMUS_USER_AVAILABLE_AGENTS_PATH`), then the project-level `.optimus/config/available-agents.json` if you explicitly opt into a repository-specific override. Nested objects merge deeply, while arrays such as `available_models` or capability lists are replaced instead of concatenated.\r\n\r\nDuring migration, `optimus upgrade --disable-project-available-agents` disables the active project override without deleting it, which is useful when you want to standardize on the user-level registry across repositories.\r\n\r\n```json\r\n{\r\n  \"engines\": {\r\n    \"claude-code\": {\r\n      \"protocol\": \"auto\",\r\n      \"preferred_protocol\": \"acp\",\r\n      \"available_models\": [\"claude-opus-4.6-1m\"],\r\n      \"cli_flags\": \"--model\",\r\n      \"automation\": { \"mode\": \"auto-approve\" },\r\n      \"timeout\": { \"heartbeat_ms\": 600000, \"activity_ms\": 1200000 },\r\n      \"acp\": {\r\n        \"path\": \"claude-agent-acp\",\r\n        \"cli_flags\": \"--model\",\r\n        \"capabilities\": { \"automation_modes\": [\"auto-approve\"] }\r\n      },\r\n      \"cli\": {\r\n        \"path\": \"claude\",\r\n        \"cli_flags\": \"--model\",\r\n        \"capabilities\": { \"automation_modes\": [\"interactive\", \"plan\", \"accept-edits\", \"deny-unapproved\", \"auto-approve\"] }\r\n      }\r\n    },\r\n    \"github-copilot\": {\r\n      \"protocol\": \"cli\",\r\n      \"path\": \"copilot\",\r\n      \"available_models\": [\"gemini-3-pro-preview\", \"gpt-5.5\"],\r\n      \"cli_flags\": \"-m\",\r\n      \"automation\": { \"mode\": \"auto-approve\", \"continuation\": \"autopilot\", \"max_continues\": 8 },\r\n      \"timeout\": { \"heartbeat_ms\": 600000 }\r\n    },\r\n    \"qwen-code\": {\r\n      \"protocol\": \"acp\",\r\n      \"path\": \"auto\",\r\n      \"args\": [\"--acp\"],\r\n      \"available_models\": [\"qwen3-coder\"],\r\n      \"cli_flags\": \"--model\",\r\n      \"timeout\": { \"heartbeat_ms\": 600000 }\r\n    }\r\n  }\r\n}\r\n```\r\n\r\nWhen `protocol` is set to `auto`, Optimus evaluates the requested `automation.mode` and `automation.continuation` against each configured transport's declared capabilities, then selects the first compatible protocol in the preferred order.\r\n\r\nTo inspect the resolved behavior directly, use `explain_available_agents`. This returns the requested automation policy, each candidate transport, the selected protocol, and the fallback reason when a preferred transport is rejected.\r\n\r\n- **`cli`** (default) — Text-based structured output via CLI (Claude Code, GitHub Copilot)\r\n- **`acp`** — JSON-RPC 2.0 over NDJSON stdio (Qwen Code, and any future ACP-compliant agent)\r\n- **`auto`** — Choose ACP or CLI at runtime based on the declared automation intent and transport capabilities\r\n- **`timeout.heartbeat_ms`** — Engine-level heartbeat timeout (default: 10 min). Tasks with no heartbeat update beyond this threshold are marked failed. Can be overridden per-task via `heartbeat_timeout_ms` on `delegate_task_async`.\r\n\r\n### ACP vs Autopilot\r\n\r\nDo not conflate **ACP** with **autopilot**:\r\n\r\n- **ACP** is a transport protocol. In Optimus config it belongs to `protocol`, `preferred_protocol`, and transport blocks such as `acp.path`.\r\n- **`autopilot`** is a Copilot continuation policy. In Optimus config it belongs to `automation.continuation`, not `protocol`.\r\n- `auto-approve` controls approval behavior. `autopilot` controls whether Copilot keeps spending additional turns to continue the task.\r\n\r\nFor GitHub Copilot specifically, the official docs separate these concerns too:\r\n\r\n- **Copilot CLI via ACP** is documented as a **public preview** server mode started with `copilot --acp`.\r\n- **Copilot autopilot** is documented as a CLI execution mode that keeps iterating until completion, typically combined with `--allow-all` and optionally `--max-autopilot-continues`.\r\n\r\nOne practical nuance: the top-level `copilot --help` output may only show `--acp`, while the official ACP reference documents additional ACP server options such as `--stdio` and `--port`. Treat the GitHub ACP reference as the source of truth for Copilot ACP transport details rather than inferring capability limits from the summary help text alone.\r\n\r\n### Automation Policy\r\n\r\n`automation.mode` is an intent enum. Do not write raw vendor strings like `dontAsk`, `bypassPermissions`, or `autopilot` into new configs.\r\n\r\n- **`interactive`** — Use the vendor default approval flow\r\n- **`plan`** — Read-only planning mode\r\n- **`accept-edits`** — Auto-approve edits while keeping command side effects guarded where supported\r\n- **`deny-unapproved`** — Never ask interactively; reject tools unless pre-approved\r\n- **`auto-approve`** — Run autonomously by auto-approving or bypassing permission prompts where supported\r\n\r\n`automation.continuation` is separate from approval policy:\r\n\r\n- **`single`** — Execute one agent run without automatic continuation\r\n- **`autopilot`** — Enable Copilot CLI autopilot continuation when supported\r\n\r\nLegacy aliases such as `dontAsk`, `bypassPermissions`, and `autopilot` are still parsed for backward compatibility, but new configs should use the normalized enum values above.\r\n\r\nTo add a new ACP vendor, just add an entry with `\"protocol\": \"acp\"` — zero code changes required.\r\n\r\n### Skill Pre-Flight\r\n\r\nIf `required_skills` is specified, the system verifies all skills exist before execution. Missing skills cause a rejection with actionable error — Master creates them via `skill-creator`, then retries.\r\n\r\n### Hybrid SDLC\r\n\r\n- **Local AI Blackboard**: Agents use `.optimus/` markdown files for drafting, debating, and long-term memory.\r\n- **GitHub Integration**: All Issues/PRs auto-tagged with `[Optimus]` prefix and `optimus-bot` label for traceability.\r\n\r\n---\r\n\r\n## Alternative: Global Install\r\n\r\n```bash\r\nnpm install -g github:cloga/optimus-code\r\noptimus init\r\noptimus serve\r\n```\r\n\r\n## CLI Reference\r\n\r\n```\r\noptimus init        Bootstrap .optimus/ workspace in current directory\r\noptimus serve       Start MCP server (stdio transport)\r\noptimus upgrade [--disable-project-available-agents]\r\n                    Update skills, roles, and config to latest version\r\n                    (preserves agents and runtime data)\r\noptimus version     Print version\r\noptimus help        Show help\r\n```\r\n\r\n---\r\n\r\n## Example Prompts\r\n\r\nOnce configured, try these in your AI coding tool:\r\n\r\n- *\"Run roster_check to see what agents are available.\"*\r\n- *\"Use dispatch_council to have the Chief Architect and QA Engineer review our design.\"*\r\n- *\"Delegate to the PM to create a GitHub Issue for the auth refactor.\"*\r\n\r\n---\r\n\r\n\u003e *Stop prompting. Start orchestrating.*\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcloga%2Foptimus-code","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcloga%2Foptimus-code","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcloga%2Foptimus-code/lists"}