{"id":50931324,"url":"https://github.com/yurymkomarov/opencode-agent-orchestration","last_synced_at":"2026-06-17T04:31:06.563Z","repository":{"id":363182569,"uuid":"1262196056","full_name":"yurymkomarov/opencode-agent-orchestration","owner":"yurymkomarov","description":"OpenCode-based multi-agent orchestration setup using ai-cli-mcp with Codex CLI, Claude Code, and Gemini CLI workers.","archived":false,"fork":false,"pushed_at":"2026-06-07T18:59:53.000Z","size":23,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-07T20:22:17.598Z","etag":null,"topics":["ai-agents","ai-cli-mcp","antigravity","claude-code","codex","coding-agents","developer-tools","gemini-cli","mcp","multi-agent","opencode"],"latest_commit_sha":null,"homepage":"","language":"Shell","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/yurymkomarov.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"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":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-06-07T17:37:24.000Z","updated_at":"2026-06-07T19:57:53.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/yurymkomarov/opencode-agent-orchestration","commit_stats":null,"previous_names":["yurymkomarov/opencode-agent-orchestration"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/yurymkomarov/opencode-agent-orchestration","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yurymkomarov%2Fopencode-agent-orchestration","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yurymkomarov%2Fopencode-agent-orchestration/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yurymkomarov%2Fopencode-agent-orchestration/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yurymkomarov%2Fopencode-agent-orchestration/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/yurymkomarov","download_url":"https://codeload.github.com/yurymkomarov/opencode-agent-orchestration/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yurymkomarov%2Fopencode-agent-orchestration/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34434492,"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-17T02:00:05.408Z","response_time":127,"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":["ai-agents","ai-cli-mcp","antigravity","claude-code","codex","coding-agents","developer-tools","gemini-cli","mcp","multi-agent","opencode"],"created_at":"2026-06-17T04:31:05.824Z","updated_at":"2026-06-17T04:31:06.554Z","avatar_url":"https://github.com/yurymkomarov.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# OpenCode Agent Orchestration Setup Guide\n\nA practical setup for using OpenCode as the main AI coding interface with ai-cli-mcp workers for Codex CLI, Claude Code, and Google Gemini / Antigravity.\n\n## Why this exists\n\nModern AI coding tools are fragmented:\n\n- Codex CLI is useful for implementation and tests.\n- Claude Code is strong for deep reasoning and refactoring.\n- Gemini / Antigravity is useful for broad context and documentation review.\n- OpenCode can act as the main terminal interface.\n\nThis repository wires them together through ai-cli-mcp so OpenCode can orchestrate local CLI agents as MCP workers.\n\n\u003e **Status:** Ready for implementation  \n\u003e **Audience:** Developers using OpenCode as the main AI coding interface and local CLI agents as workers  \n\u003e **Scope:** macOS and Linux  \n\u003e **Assumption:** OpenAI, Anthropic, and Google accounts already exist  \n\u003e **Last verified:** 2026-06-07\n\n\u003e [!WARNING]\n\u003e This setup can run local coding agents with elevated/non-interactive permissions.\n\u003e Use a disposable workspace, worktree, devcontainer, or VM.\n\u003e Do not run it in `$HOME` or in repositories containing real secrets.\n\n---\n\n## Table of Contents\n\n1. [Target Architecture](#target-architecture)\n2. [Prerequisites](#prerequisites)\n3. [Create a Safe Workspace](#create-a-safe-workspace)\n4. [Recommended Script Workflow](#recommended-script-workflow)\n5. [Install and Configure OpenCode](#install-and-configure-opencode)\n6. [Install and Configure Codex CLI](#install-and-configure-codex-cli)\n7. [Install and Configure Claude Code CLI](#install-and-configure-claude-code-cli)\n8. [Install and Configure Antigravity CLI and Gemini Compatibility](#install-and-configure-antigravity-cli-and-gemini-compatibility)\n9. [Install and Validate ai-cli-mcp](#install-and-validate-ai-cli-mcp)\n10. [Connect ai-cli-mcp to OpenCode](#connect-ai-cli-mcp-to-opencode)\n11. [Create Agent Profiles](#create-agent-profiles)\n12. [Create OpenCode Commands](#create-opencode-commands)\n13. [Run Smoke Tests](#run-smoke-tests)\n14. [Recommended Workflow](#recommended-workflow)\n15. [Security Rules](#security-rules)\n16. [Troubleshooting](#troubleshooting)\n17. [Final Readiness Checklist](#final-readiness-checklist)\n18. [Recommended Repository Structure](#recommended-repository-structure)\n19. [Upstream References](#upstream-references)\n\n---\n\n## Target Architecture\n\nThe goal is to use **OpenCode** as the main interface and orchestrator, while **ai-cli-mcp** exposes local CLI agents as MCP tools.\n\n```text\nOpenCode\n  └── MCP server: ai-cli-mcp\n        ├── Codex CLI\n        ├── Google Antigravity CLI / Gemini compatibility\n        └── Claude Code CLI\n```\n\n### Responsibility Model\n\n| Component                                     | Role                                                                                             |\n| --------------------------------------------- | ------------------------------------------------------------------------------------------------ |\n| OpenCode                                      | Main interface; should run on a Codex/OpenAI model by default                                    |\n| ai-cli-mcp                                    | MCP bridge that starts local CLI agents as background workers                                    |\n| Codex / OpenAI model in OpenCode              | Default operator model through ChatGPT/OpenAI                                                    |\n| Codex CLI                                     | Implementation, tests, bug fixing, security review                                               |\n| Claude Code CLI                               | Mandatory deep reasoning, architecture review, complex refactoring worker                        |\n| Google Antigravity CLI / Gemini compatibility | Mandatory long-context overview, documentation review, broad repository analysis, second opinion |\n\n\u003e **Important:** This setup does not create one shared context across all agents. Each worker receives a prompt and a working directory, then returns a result to OpenCode.\n\n### Version and Source Notes\n\nThis guide intentionally prefers package-manager installs that stay easy to upgrade:\n\n```text\n1. Homebrew first where an official or project-recommended formula/cask exists\n2. curl installer second where the upstream project documents one\n3. npm/npx as fallback or where it is the only documented install path\n```\n\nAs of 2026-06-07, the local validation environment used:\n\n```text\nOpenCode CLI: 1.16.2\nCodex CLI: 0.137.0\nClaude Code CLI: 2.1.153\nAntigravity CLI: available as `agy`\nGemini CLI: 0.45.2\nai-cli-mcp: 2.21.0\n```\n\n### Google CLI Transition Note\n\nGoogle announced on 2026-05-19 that Gemini CLI is transitioning to Antigravity CLI. Antigravity CLI is available now, and Gemini CLI / Gemini Code Assist IDE requests for consumer free, Google AI Pro, and Google AI Ultra users stop being served on 2026-06-18. Enterprise and paid API-key usage remains supported according to Google's announcement.\n\nThis setup therefore installs **Antigravity CLI** as the future Google CLI. It also keeps **Gemini CLI** installed for now because `ai-cli-mcp@2.21.0` still exposes Google worker models through the `gemini` backend. Once `ai-cli-mcp` adds an Antigravity/`agy` adapter, the Google worker commands should move from Gemini compatibility to Antigravity directly.\n\nDo not hard-code these versions in a team setup unless you need reproducibility. Prefer checking current versions with the commands in the readiness checklist.\n\n---\n\n## Prerequisites\n\nThis document assumes:\n\n```text\nOS: macOS or Linux\nShell: zsh or bash\nNode.js: installed\nnpm/npx: installed\ngit: installed\nAccounts: OpenAI, Anthropic, and Google accounts are available\n```\n\nCheck the local environment:\n\n```bash\nnode --version\nnpm --version\nnpx --version\ngit --version\n```\n\nRecommended Node.js version:\n\n```text\nNode.js 20+\n```\n\nNode.js 20+ is recommended because the current Gemini compatibility backend requires Node.js 20 or higher. Claude Code's npm path requires Node.js 18 or higher. If you use only native Homebrew/curl installers for OpenCode, Codex, Claude, and Antigravity, Node is still useful for `ai-cli-mcp`, Gemini compatibility, and `npx`-based MCP startup.\n\n### Install Node.js on macOS\n\n```bash\nbrew install node\n```\n\n### Install Node.js on Ubuntu / Debian\n\n```bash\nsudo apt update\nsudo apt install -y nodejs npm git\n```\n\n---\n\n## Create a Safe Workspace\n\nDo not run AI agents directly in the home directory or in folders containing credentials.\n\nCreate a dedicated workspace:\n\n```bash\nmkdir -p ~/ai-workspaces\ncd ~/ai-workspaces\n```\n\nClone the target repository into a safe agent workspace:\n\n```bash\ngit clone \u003cYOUR_REPO_URL\u003e my-project-agent\ncd my-project-agent\n```\n\nAlternatively, create a Git worktree from an existing repository:\n\n```bash\ncd ~/projects/my-project\ngit worktree add ~/ai-workspaces/my-project-agent agent-playground\ncd ~/ai-workspaces/my-project-agent\n```\n\n\u003e **Security note:** Prefer a copy, Git worktree, devcontainer, ephemeral VM, or separate local user account for AI-agent experimentation.\n\n---\n\n## Recommended Script Workflow\n\nThis repository includes two scripts:\n\n```text\ninstall.sh  machine-level installation and global OpenCode MCP setup under $HOME\ninit.sh     project-level agent instructions and OpenCode commands in the target repository\n```\n\nRun `install.sh` once per machine:\n\n```bash\n./install.sh\n```\n\nPreview machine-level changes without installing packages or writing config:\n\n```bash\n./install.sh --dry-run\n```\n\nWhat `install.sh` does:\n\n```text\n- checks Node.js, npm, npx, OpenCode, Codex CLI, Claude Code CLI, Antigravity CLI, Gemini CLI compatibility, and ai-cli-mcp\n- installs missing tools using Homebrew first, curl second where documented, and npm as fallback\n- installs Claude, Antigravity CLI, and Gemini CLI compatibility as required worker tooling\n- sets npm global prefix to $HOME/.local so npm-installed worker tooling stays under $HOME\n- adds $HOME/.local/bin to the current shell rc file if needed\n- creates or updates $HOME/.config/opencode/opencode.jsonc with OpenAI/Codex model defaults and the ai-cli-mcp MCP server\n- prints version and diagnostic output\n- supports `--dry-run` to preview package installs, PATH changes, and OpenCode config updates without writing files\n```\n\nOptional environment overrides:\n\n```bash\nAI_CLI_MCP_PACKAGE=ai-cli-mcp@2.21.0 ./install.sh\nNPM_GLOBAL_PREFIX=\"$HOME/.local\" ./install.sh\nOPENCODE_CONFIG_FILE=\"$HOME/.config/opencode/opencode.jsonc\" ./install.sh\nOPENCODE_MODEL=\"openai/gpt-5.5\" ./install.sh\nOPENCODE_SMALL_MODEL=\"openai/gpt-5.5\" OPENCODE_SMALL_MODEL_VARIANT=\"fast\" ./install.sh\n```\n\nRun `init.sh` once per project workspace:\n\n```bash\ncd ~/ai-workspaces/my-project-agent\n/path/to/opencode-agent-orchestration/init.sh\n```\n\nOr pass the project path explicitly:\n\n```bash\n./init.sh ~/ai-workspaces/my-project-agent\n```\n\nPreview project-level file changes without writing files:\n\n```bash\n./init.sh --dry-run ~/ai-workspaces/my-project-agent\n```\n\nWhat `init.sh` does:\n\n```text\n- creates or updates AGENTS.md\n- creates or updates CLAUDE.md\n- creates or updates GEMINI.md\n- creates or updates .agents/codex-worker.md\n- creates or updates .agents/claude-worker.md\n- creates or updates .agents/gemini-worker.md\n- creates or updates .opencode/command/*.md\n- supports `--dry-run` to preview which files would be created or updated\n```\n\nIf a file already exists, `init.sh` writes the managed block at the beginning of the file and keeps existing content below it. Re-running `init.sh` replaces the previous managed block instead of duplicating it.\n\n---\n\n## Install and Configure OpenCode\n\nInstall OpenCode with Homebrew first:\n\n```bash\nbrew install anomalyco/tap/opencode\n```\n\nThe OpenCode docs recommend the OpenCode tap for the most up-to-date Homebrew releases. The plain Homebrew formula may lag.\n\nAlternatively, install with the official curl installer:\n\n```bash\ncurl -fsSL https://opencode.ai/install | bash\n```\n\nFallback via npm:\n\n```bash\nnpm install -g opencode-ai\n```\n\nVerify installation:\n\n```bash\nopencode --version\nopencode --help\n```\n\nStart OpenCode for the first time:\n\n```bash\nopencode\n```\n\nInside OpenCode, connect a provider:\n\n```text\n/connect\n```\n\nSelect the provider you want to use as the main OpenCode backend, for example:\n\n```text\nOpenAI / ChatGPT\nAnthropic\nGitHub Copilot\n```\n\nThen select a model:\n\n```text\n/models\n```\n\nExit OpenCode:\n\n```text\n/q\n```\n\nRun a basic one-shot test:\n\n```bash\nopencode run \"Summarize this repository in 5 bullet points.\"\n```\n\nRun with an explicit model:\n\n```bash\nopencode models openai\nopencode run -m openai/\u003cMODEL_FROM_LIST\u003e \"Summarize this repository.\"\n```\n\nor:\n\n```bash\nopencode models anthropic\nopencode run -m anthropic/\u003cMODEL_FROM_LIST\u003e \"Summarize this repository.\"\n```\n\nList available models:\n\n```bash\nopencode models\nopencode models openai\nopencode models anthropic\n```\n\n---\n\n## Install and Configure Codex CLI\n\nInstall Codex CLI with Homebrew first:\n\n```bash\nbrew install --cask codex\n```\n\nAlternatively, install with the official curl installer:\n\n```bash\ncurl -fsSL https://chatgpt.com/codex/install.sh | sh\n```\n\nFallback via npm:\n\n```bash\nnpm install -g @openai/codex\n```\n\nVerify installation:\n\n```bash\ncodex --version\ncodex --help\n```\n\nAuthenticate:\n\n```bash\ncodex login\n```\n\nOn remote or headless machines, use device-code authentication if browser login cannot complete:\n\n```bash\ncodex login --device-auth\n```\n\nFor diagnostics:\n\n```bash\ncodex doctor\n```\n\nRun a smoke test:\n\n```bash\ncd ~/ai-workspaces/my-project-agent\ncodex \"Summarize this repository in 5 bullet points.\"\n```\n\nRun a non-interactive smoke test:\n\n```bash\ncodex exec \"Summarize this repository in 5 bullet points.\"\n```\n\nRecommended Codex model defaults currently start with `gpt-5.5` for complex coding work. For OpenCode's lightweight helper agents, this setup uses `openai/gpt-5.5` with `variant: fast` instead of a separate mini model. To pin the default local Codex CLI model:\n\n```toml\nmodel = \"gpt-5.5\"\n```\n\n\u003e **Supply-chain warning:** Avoid unofficial npm packages or wrappers with names similar to Codex. Install only official packages or documented entrypoints.\n\n---\n\n## Install and Configure Claude Code CLI\n\nInstall Claude Code CLI with Homebrew first:\n\n```bash\nbrew install --cask claude-code\n```\n\nFor the latest release channel rather than the stable cask:\n\n```bash\nbrew install --cask claude-code@latest\n```\n\nAlternatively, install with the official curl installer:\n\n```bash\ncurl -fsSL https://claude.ai/install.sh | bash\n```\n\nFallback via npm:\n\n```bash\nnpm install -g @anthropic-ai/claude-code\n```\n\nTo upgrade an npm install, use:\n\n```bash\nnpm install -g @anthropic-ai/claude-code@latest\n```\n\nAvoid `sudo npm install -g`; fix npm permissions instead.\n\nVerify installation:\n\n```bash\nclaude --version\nclaude --help\n```\n\nAuthenticate:\n\n```bash\nclaude auth login\n```\n\nComplete the login flow in the browser or terminal. Check auth state:\n\n```bash\nclaude auth status\n```\n\nRun a smoke test:\n\n```bash\ncd ~/ai-workspaces/my-project-agent\nclaude -p \"Summarize this repository in 5 bullet points.\"\n```\n\n### Non-interactive Permission Setup\n\nFor use through `ai-cli-mcp`, Claude Code may need to be initialized once in a non-interactive mode.\n\nRun this only inside the safe workspace:\n\n```bash\ncd ~/ai-workspaces/my-project-agent\nclaude --dangerously-skip-permissions\n```\n\nAccept the required prompts, verify that the command starts correctly, then exit.\n\n\u003e **Warning:** `--dangerously-skip-permissions` is risky. Never run this in a directory containing production secrets, real kubeconfigs, SSH keys, or cloud credentials.\n\n---\n\n## Install and Configure Antigravity CLI and Gemini Compatibility\n\nInstall Antigravity CLI with Homebrew first:\n\n```bash\nbrew install --cask antigravity-cli\n```\n\nAlternatively, install with the official curl installer:\n\n```bash\ncurl -fsSL https://antigravity.google/cli/install.sh | bash\n```\n\nThe curl installer installs the `agy` binary under `~/.local/bin/agy`.\n\nVerify installation:\n\n```bash\nagy --version\nagy --help\n```\n\nAuthenticate:\n\n```bash\nagy\n```\n\nAntigravity CLI uses Google sign-in and secure local token storage. On a local machine it can open the browser automatically; over SSH it prints an authorization URL and asks you to paste back the resulting code.\n\n### Gemini CLI Compatibility\n\nFor now, install Gemini CLI as a compatibility backend for `ai-cli-mcp`.\n\nInstall with Homebrew first:\n\n```bash\nbrew install gemini-cli\n```\n\nFallback via npm:\n\n```bash\nnpm install -g @google/gemini-cli@latest\n```\n\nRun without installing:\n\n```bash\nnpx https://github.com/google-gemini/gemini-cli\n```\n\nVerify installation:\n\n```bash\ngemini --version\ngemini --help\n```\n\nAuthenticate:\n\n```bash\ngemini\n```\n\nChoose Google sign-in and complete the browser login flow. Alternative authentication options include `GEMINI_API_KEY` and Vertex AI environment variables.\n\n\u003e **Transition note:** For consumer free, Google AI Pro, and Google AI Ultra usage, Gemini CLI request serving ends on 2026-06-18. Keep Gemini CLI here only while `ai-cli-mcp` still requires the `gemini` binary for Google worker models. Treat Antigravity CLI as the forward-looking Google CLI.\n\nRun a smoke test:\n\n```bash\ncd ~/ai-workspaces/my-project-agent\ngemini -p \"Summarize this repository in 5 bullet points.\"\n```\n\nRun with a specific model:\n\n```bash\ngemini -m gemini-2.5-flash -p \"Summarize this repository in 5 bullet points.\"\n```\n\n---\n\n## Install and Validate ai-cli-mcp\n\n`ai-cli-mcp` is currently distributed through npm. There is no official Homebrew formula or curl installer documented for this package.\n\nInstall globally for easier diagnostics:\n\n```bash\nnpm install -g ai-cli-mcp\n```\n\nVerify installation:\n\n```bash\nai-cli --help\n```\n\nDo not use `ai-cli-mcp --help` as a help check. The `ai-cli-mcp` binary starts the MCP server over stdio.\n\nRun diagnostics:\n\n```bash\nai-cli doctor\n```\n\nList available model aliases:\n\n```bash\nai-cli models\n```\n\nCurrent `ai-cli-mcp@2.21.0` model groups include:\n\n```text\nClaude: sonnet, sonnet[1m], opus, opusplan, haiku\nCodex: gpt-5.4, gpt-5.5, gpt-5.4-mini, gpt-5.3-codex, gpt-5.3-codex-spark, gpt-5.2\nGemini: gemini-2.5-pro, gemini-2.5-flash, gemini-3.1-pro-preview, gemini-3-pro-preview, gemini-3-flash-preview\nAliases: claude-ultra, codex-ultra, gemini-ultra\nOptional adapters may also appear in `ai-cli models`, depending on the installed `ai-cli-mcp` release.\n```\n\nAlways run `ai-cli models` after install because these aliases can change between releases.\n\n### Validate Workers Without OpenCode\n\nBefore connecting anything to OpenCode, verify that `ai-cli` can launch each local CLI agent.\n\nEnter the workspace:\n\n```bash\ncd ~/ai-workspaces/my-project-agent\n```\n\nTest Claude worker:\n\n```bash\nai-cli run \\\n  --cwd \"$PWD\" \\\n  --model sonnet \\\n  --prompt \"Summarize this repository in 5 bullet points.\"\n```\n\nTest Codex worker:\n\n```bash\nai-cli run \\\n  --cwd \"$PWD\" \\\n  --model gpt-5.5 \\\n  --prompt \"Summarize this repository in 5 bullet points.\"\n```\n\nTest Gemini worker:\n\n```bash\nai-cli run \\\n  --cwd \"$PWD\" \\\n  --model gemini-2.5-pro \\\n  --prompt \"Summarize this repository in 5 bullet points.\"\n```\n\nOptional OpenCode-as-worker test:\n\n```bash\nai-cli run \\\n  --cwd \"$PWD\" \\\n  --model opencode \\\n  --prompt \"Summarize this repository in 5 bullet points.\"\n```\n\nInspect running jobs:\n\n```bash\nai-cli ps\n```\n\nRead a result:\n\n```bash\nai-cli result \u003cPID\u003e\n```\n\nPeek at a running process:\n\n```bash\nai-cli peek \u003cPID\u003e --time 10\n```\n\nWait for completion:\n\n```bash\nai-cli wait \u003cPID\u003e --timeout 300\n```\n\nRead verbose result:\n\n```bash\nai-cli result \u003cPID\u003e --verbose\n```\n\nKill a stuck job:\n\n```bash\nai-cli kill \u003cPID\u003e\n```\n\nClean completed jobs:\n\n```bash\nai-cli cleanup\n```\n\n---\n\n## Connect ai-cli-mcp to OpenCode\n\nThe recommended setup is global user-level OpenCode configuration under `$HOME`, not a project-local `opencode.json`.\n\nUse `install.sh` for the normal path:\n\n```bash\n./install.sh\n```\n\nIt creates or updates:\n\n```text\n$HOME/.config/opencode/opencode.jsonc\n```\n\nThere are also two manual patterns: interactive registration through OpenCode CLI, or direct user-level config editing.\n\n### Option A: Add MCP Server Interactively\n\nRun:\n\n```bash\nopencode mcp add\n```\n\nChoose a local MCP server and provide:\n\n```text\nName: ai-cli-mcp\nCommand: npx\nArgs: -y ai-cli-mcp@latest\n```\n\nFor reproducible team setup, pin the version you validated, for example:\n\n```text\nArgs: -y ai-cli-mcp@2.21.0\n```\n\nThen start OpenCode in the project:\n\n```bash\ncd ~/ai-workspaces/my-project-agent\nopencode\n```\n\nAsk OpenCode:\n\n```text\nWhat MCP tools are available?\n```\n\nOpenCode should list tools exposed by `ai-cli-mcp`.\n\n### Option B: Configure Global OpenCode Config\n\nCreate or edit the user-level OpenCode config file:\n\n```bash\nmkdir -p ~/.config/opencode\ntouch ~/.config/opencode/opencode.jsonc\n```\n\nMinimal example:\n\n```jsonc\n{\n  \"$schema\": \"https://opencode.ai/config.json\",\n  \"model\": \"openai/gpt-5.5\",\n  \"small_model\": \"openai/gpt-5.5\",\n  \"agent\": {\n    \"title\": {\n      \"model\": \"openai/gpt-5.5\",\n      \"variant\": \"fast\",\n    },\n    \"summary\": {\n      \"model\": \"openai/gpt-5.5\",\n      \"variant\": \"fast\",\n    },\n    \"compaction\": {\n      \"model\": \"openai/gpt-5.5\",\n      \"variant\": \"fast\",\n    },\n  },\n  \"enabled_providers\": [\"openai\"],\n  \"mcp\": {\n    \"ai-cli-mcp\": {\n      \"type\": \"local\",\n      \"command\": [\"npx\", \"-y\", \"ai-cli-mcp@latest\"],\n      \"enabled\": true,\n    },\n  },\n}\n```\n\nPinned example:\n\n```jsonc\n{\n  \"$schema\": \"https://opencode.ai/config.json\",\n  \"model\": \"openai/gpt-5.5\",\n  \"small_model\": \"openai/gpt-5.5\",\n  \"agent\": {\n    \"title\": {\n      \"model\": \"openai/gpt-5.5\",\n      \"variant\": \"fast\",\n    },\n    \"summary\": {\n      \"model\": \"openai/gpt-5.5\",\n      \"variant\": \"fast\",\n    },\n    \"compaction\": {\n      \"model\": \"openai/gpt-5.5\",\n      \"variant\": \"fast\",\n    },\n  },\n  \"enabled_providers\": [\"openai\"],\n  \"mcp\": {\n    \"ai-cli-mcp\": {\n      \"type\": \"local\",\n      \"command\": [\"npx\", \"-y\", \"ai-cli-mcp@2.21.0\"],\n      \"enabled\": true,\n    },\n  },\n}\n```\n\n\u003e **Compatibility note:** If your OpenCode version expects a different MCP config shape, use `opencode mcp add` and then inspect the generated config.\n\nOpenCode's top-level `small_model` value is a model string. Provider-specific speed or reasoning modes belong in `variant` fields, so `install.sh` applies `variant: fast` to the built-in `title`, `summary`, and `compaction` agents.\n\nProject-local `opencode.json` can still be used for project-specific overrides, but the MCP server itself should usually live in `$HOME/.config/opencode/opencode.jsonc` so every workspace can use the same worker bridge.\n\n---\n\n## Create Agent Profiles\n\nThe goal is to route work to the right tool:\n\n```text\nCodex/OpenAI in OpenCode → default operator\nCodex CLI                  → implementation, tests, bug fixing, security review\nClaude                     → mandatory deep refactor, architecture reasoning, complex code changes\nGoogle/Gemini compatibility → mandatory long-context overview, documentation, alternative review\n```\n\nOpenCode remains the interface and orchestrator. Run OpenCode on a Codex/OpenAI model by default, then use Codex CLI, Claude, and the Google worker as specialized workers through `ai-cli-mcp`. Today that Google worker is still the Gemini compatibility backend.\n\n---\n\n### Create Common Instructions for All Agents\n\nCreate `AGENTS.md` in the repository root:\n\n```bash\ncd ~/ai-workspaces/my-project-agent\ntouch AGENTS.md\n```\n\nRecommended `AGENTS.md`:\n\n```md\n# Project Agent Instructions\n\n## Mission\n\nThis repository is managed through OpenCode with ai-cli-mcp workers:\n\n- Codex as the default operator and implementation worker\n- Gemini for long-context analysis, documentation, and alternative review\n- Claude as a mandatory worker for deep refactoring and architecture reasoning\n\nAgent-specific worker profiles:\n\n- Codex worker: `.agents/codex-worker.md`\n- Claude worker: `.agents/claude-worker.md`\n- Gemini worker: `.agents/gemini-worker.md`\n\n## Safety Rules\n\n- Do not access or modify files outside this repository.\n- Do not read or print secrets.\n- Do not modify `.env`, `.env.*`, private keys, kubeconfigs, production credentials, or deployment secrets.\n- Do not run destructive commands unless explicitly requested.\n- Do not run `kubectl`, `terraform apply`, `helm upgrade`, or production deployment commands unless explicitly requested.\n- Prefer read-only analysis unless the user asks for implementation.\n\n## Work Style\n\n- Before changing code, inspect the relevant files.\n- For non-trivial changes, produce a short plan first.\n- Prefer small, reviewable changes.\n- Keep diffs focused.\n- Do not mix refactoring and feature changes unless explicitly requested.\n- Run relevant tests, linters, and type checks before claiming success.\n- If tests cannot be run, explain exactly why.\n\n## Output Format for Reviews\n\nWhen reviewing code, return:\n\n1. Confirmed issues\n2. Potential issues\n3. False positives / things that look okay\n4. Suggested implementation order\n5. Commands that should be run to verify the result\n\n## Output Format for Implementation\n\nWhen implementing, return:\n\n1. Summary of changes\n2. Files changed\n3. Tests run\n4. Remaining risks\n5. Suggested next step\n\n## Codex Worker Profile\n\nUse Codex for:\n\n- concrete implementation tasks\n- bug fixing\n- test generation\n- security review\n- code cleanup\n- type errors\n- failing tests\n- small-to-medium scoped changes\n\nCodex should avoid:\n\n- broad architecture rewrites without a plan\n- speculative abstractions\n- changing public behavior without tests\n- touching deployment credentials or production configs\n\nWhen Codex receives an implementation task:\n\n1. Inspect the relevant files.\n2. Identify the minimal change.\n3. Edit only the necessary files.\n4. Run the most relevant tests.\n5. Run formatter/linter/typecheck if available.\n6. Report exact commands run.\n\nWhen Codex receives a review task:\n\n1. Do not edit files.\n2. Focus on correctness, security, tests, and maintainability.\n3. Rank findings by severity.\n4. Include file paths and concrete examples.\n5. Avoid vague advice.\n```\n\n---\n\n### Create Claude Code Instructions\n\nClaude is best suited for:\n\n```text\n- deep refactoring\n- complex changes across multiple files\n- architecture reasoning\n- legacy code explanation\n- migration planning\n```\n\nCreate `CLAUDE.md`:\n\n```bash\ntouch CLAUDE.md\n```\n\nRecommended `CLAUDE.md`:\n\n```md\n# Claude Code Instructions\n\n## Role\n\nYou are the deep reasoning and refactoring agent for this repository.\n\nRead this file together with:\n\n- `AGENTS.md`\n- `.agents/claude-worker.md`\n\nUse Claude for:\n\n- architecture analysis\n- complex refactoring\n- multi-file reasoning\n- migration planning\n- identifying hidden coupling\n- explaining trade-offs\n\nAvoid using Claude for:\n\n- quick mechanical edits\n- simple formatting\n- trivial one-line fixes\n- repetitive low-context tasks\n\n## Refactoring Rules\n\n- Preserve existing behavior unless explicitly asked to change it.\n- Do not introduce broad abstractions without clear benefit.\n- Prefer incremental refactoring over large rewrites.\n- Keep public APIs stable unless the task explicitly asks to change them.\n- When refactoring, identify tests that protect the changed behavior.\n- If tests are missing, suggest minimal tests before changing risky code.\n\n## Architecture Review Checklist\n\nWhen asked to review architecture, check:\n\n- module boundaries\n- dependency direction\n- hidden coupling\n- duplicated business logic\n- state management\n- error handling\n- observability\n- testability\n- deployment/runtime assumptions\n\n## Implementation Discipline\n\nBefore editing:\n\n1. Read relevant files.\n2. Summarize the current design.\n3. Identify the smallest safe change.\n4. Ask for confirmation only if the task is ambiguous or destructive.\n\nAfter editing:\n\n1. Show changed files.\n2. Explain why each change was needed.\n3. Run or suggest tests.\n4. Call out risks honestly.\n\n## Forbidden Actions\n\n- Do not access secrets.\n- Do not run production deployment commands.\n- Do not modify infrastructure state.\n- Do not rewrite large areas of code without an explicit plan.\n```\n\nValidate Claude instructions:\n\n```bash\ncd ~/ai-workspaces/my-project-agent\nclaude\n```\n\nInside Claude Code:\n\n```text\nRead AGENTS.md, CLAUDE.md, and `.agents/claude-worker.md`. Summarize how you should behave in this repository.\n```\n\n---\n\n### Create Claude Worker Prompt\n\nCreate a dedicated prompt file:\n\n```bash\nmkdir -p .agents\ntouch .agents/claude-worker.md\n```\n\nRecommended `.agents/claude-worker.md`:\n\n```md\n# Claude Worker Prompt\n\nYou are Claude Code running as a worker through ai-cli-mcp.\n\nYour strengths:\n\n- architecture analysis\n- complex refactoring\n- multi-file reasoning\n- migration planning\n- identifying hidden coupling\n- explaining trade-offs\n\nDefault mode:\n\n- Think through architecture and dependencies before proposing changes.\n- Prefer incremental refactoring over broad rewrites.\n- Preserve behavior unless asked otherwise.\n- Identify tests that protect changed behavior.\n- Return concrete risks, trade-offs, and implementation order.\n\nFor review-only tasks, do not modify files. Focus on architecture, coupling, testability, and maintainability.\nFor planning tasks, produce a step-by-step plan with risks and verification strategy.\n```\n\n---\n\n### Create Codex Worker Prompt\n\nCreate a dedicated prompt file:\n\n```bash\nmkdir -p .agents\ntouch .agents/codex-worker.md\n```\n\nRecommended `.agents/codex-worker.md`:\n\n```md\n# Codex Worker Prompt\n\nYou are Codex running as a worker through ai-cli-mcp.\n\nYour strengths:\n\n- implementation\n- bug fixing\n- test writing\n- security review\n- mechanical code changes\n- verifying behavior with commands\n\nDefault mode:\n\n- Be concrete.\n- Prefer patches over abstract advice.\n- Keep changes minimal.\n- Run tests when possible.\n- Return exact commands and results.\n\nFor review-only tasks:\n\n- Do not modify files.\n- Return findings with severity.\n- Include file paths.\n- Include suggested fixes.\n\nFor implementation tasks:\n\n- Modify only necessary files.\n- Preserve behavior unless asked otherwise.\n- Add or update tests when appropriate.\n- Run relevant verification commands.\n```\n\nSmoke test:\n\n```bash\nai-cli run \\\n  --cwd \"$PWD\" \\\n  --model gpt-5.5 \\\n  --prompt \"$(cat .agents/codex-worker.md)\n\nTask:\nReview this repository for missing tests. Do not modify files.\"\n```\n\n---\n\n### Create Gemini Worker Prompt\n\nGemini is best suited for:\n\n```text\n- long-context repository overview\n- documentation review\n- broad codebase analysis\n- independent second opinion\n- finding inconsistencies between documentation and code\n```\n\nCreate `GEMINI.md`:\n\n```bash\ntouch GEMINI.md\n```\n\nRecommended `GEMINI.md`:\n\n```md\n# Gemini CLI Instructions\n\nYou are the long-context analysis and documentation-review agent for this repository.\n\nRead this file together with:\n\n- `AGENTS.md`\n- `.agents/gemini-worker.md`\n\nUse Gemini for:\n\n- broad repository understanding\n- documentation review\n- long-context analysis\n- comparing code against docs\n- identifying unclear boundaries\n- producing structured summaries\n\nDefault mode:\n\n- Prefer analysis over edits.\n- Do not modify files unless explicitly asked.\n- Read broadly before concluding.\n- Look for inconsistencies across modules and documentation.\n```\n\nCreate a prompt file:\n\n```bash\nmkdir -p .agents\ntouch .agents/gemini-worker.md\n```\n\nRecommended `.agents/gemini-worker.md`:\n\n```md\n# Gemini Worker Prompt\n\nYou are Gemini running as a long-context analysis worker through ai-cli-mcp.\n\nYour strengths:\n\n- broad repository understanding\n- documentation review\n- long-context analysis\n- comparing code against docs\n- identifying unclear boundaries\n- producing structured summaries\n\nDefault mode:\n\n- Prefer analysis over edits.\n- Do not modify files unless explicitly asked.\n- Read broadly before concluding.\n- Look for inconsistencies across modules and documentation.\n- Produce concise, structured output.\n\nUse Gemini for:\n\n- system overview\n- architecture map\n- module boundary review\n- documentation gaps\n- onboarding guides\n- alternative second opinion\n\nAvoid using Gemini for:\n\n- risky production changes\n- narrow mechanical edits\n- secrets handling\n- deployment execution\n\nOutput format:\n\n1. High-level summary\n2. Important modules\n3. Data/control flow\n4. Inconsistencies\n5. Documentation gaps\n6. Suggested follow-up tasks\n```\n\nSmoke test:\n\n```bash\nai-cli run \\\n  --cwd \"$PWD\" \\\n  --model gemini-2.5-pro \\\n  --prompt \"$(cat .agents/gemini-worker.md)\n\nTask:\nCreate a high-level architecture overview of this repository. Do not modify files.\"\n```\n\n---\n\n## Create OpenCode Commands\n\nCreate a command directory:\n\n```bash\nmkdir -p .opencode/command\n```\n\nThese commands make it easier to launch workers from OpenCode with consistent instructions.\n\n---\n\n### Codex Security Review\n\nCreate `.opencode/command/codex-security.md`:\n\n```bash\ncat \u003e .opencode/command/codex-security.md \u003c\u003c'EOF'\n---\ndescription: Run Codex security review through ai-cli-mcp\n---\n\nUse ai-cli-mcp to run Codex in the current repository.\n\nWorker profile:\nRead AGENTS.md and `.agents/codex-worker.md`.\n\nTask:\nPerform a security-focused review of the current repository.\n\nRules:\n- Do not modify files.\n- Focus on authentication, authorization, secrets, input validation, dependency risks, unsafe shell execution, and deployment risks.\n- Return findings with severity: critical, high, medium, low.\n- Include file paths and concrete examples.\n- Ignore purely stylistic issues.\n\nAfter Codex finishes:\n- Wait for the result.\n- Summarize confirmed findings.\n- Separate likely false positives.\n- Propose a safe implementation order.\nEOF\n```\n\n---\n\n### Codex Test Review\n\nCreate `.opencode/command/codex-tests.md`:\n\n```bash\ncat \u003e .opencode/command/codex-tests.md \u003c\u003c'EOF'\n---\ndescription: Ask Codex to find missing tests and propose implementation\n---\n\nUse ai-cli-mcp to run Codex in the current repository.\n\nWorker profile:\nRead AGENTS.md and `.agents/codex-worker.md`.\n\nTask:\nFind the highest-value missing tests in this repository.\n\nRules:\n- Do not modify files unless I explicitly ask in the next message.\n- Identify risky untested behavior.\n- Recommend specific test files and test cases.\n- Include likely commands to run tests.\n- Prioritize small tests with high value.\n\nAfter Codex finishes:\n- Wait for the result.\n- Produce a prioritized test implementation plan.\nEOF\n```\n\n---\n\n### Claude Refactor Review\n\nClaude is a mandatory worker in the default workflow. `init.sh` creates this command by default.\n\nCreate `.opencode/command/claude-refactor.md`:\n\n```bash\ncat \u003e .opencode/command/claude-refactor.md \u003c\u003c'EOF'\n---\ndescription: Run Claude deep refactor review through ai-cli-mcp\n---\n\nUse ai-cli-mcp to run Claude Code in the current repository.\n\nWorker profile:\nRead AGENTS.md, CLAUDE.md, and `.agents/claude-worker.md`.\n\nTask:\nPerform a deep refactoring review of the current repository.\n\nRules:\n- Do not modify files.\n- Focus on architecture, coupling, module boundaries, duplicated business logic, testability, and maintainability.\n- Avoid cosmetic comments.\n- Prefer incremental refactoring suggestions.\n- Identify risky rewrites that should be avoided.\n\nAfter Claude finishes:\n- Wait for the result.\n- Summarize the top refactoring opportunities.\n- Group them into safe incremental steps.\nEOF\n```\n\n---\n\n### Claude Implementation Plan\n\nClaude is a mandatory worker in the default workflow. `init.sh` creates this command by default.\n\nCreate `.opencode/command/claude-plan.md`:\n\n```bash\ncat \u003e .opencode/command/claude-plan.md \u003c\u003c'EOF'\n---\ndescription: Ask Claude to produce a deep implementation plan\n---\n\nUse ai-cli-mcp to run Claude Code in the current repository.\n\nWorker profile:\nRead AGENTS.md, CLAUDE.md, and `.agents/claude-worker.md`.\n\nTask:\nCreate a detailed implementation plan for the task I describe.\n\nRules:\n- Do not modify files.\n- Inspect relevant files.\n- Produce a step-by-step plan.\n- Identify risks and test strategy.\n- Prefer small, reviewable commits.\n- Mark each task with [ ] checkboxes.\n\nAfter Claude finishes:\n- Wait for the result.\n- Compress the plan into an actionable checklist.\nEOF\n```\n\n---\n\n### Gemini Architecture Overview\n\nCreate `.opencode/command/gemini-architecture.md`:\n\n```bash\ncat \u003e .opencode/command/gemini-architecture.md \u003c\u003c'EOF'\n---\ndescription: Run Gemini long-context architecture overview through ai-cli-mcp\n---\n\nUse ai-cli-mcp to run Gemini in the current repository.\n\nWorker profile:\nRead AGENTS.md, GEMINI.md, and `.agents/gemini-worker.md`.\n\nTask:\nCreate a long-context architecture overview of this repository.\n\nRules:\n- Do not modify files.\n- Read broadly.\n- Identify main modules, data flow, runtime assumptions, and unclear boundaries.\n- Compare docs against actual code where possible.\n- Highlight missing or outdated documentation.\n\nAfter Gemini finishes:\n- Wait for the result.\n- Summarize the architecture in a concise way.\n- List documentation gaps and follow-up questions.\nEOF\n```\n\n---\n\n### Multi-Agent Review\n\nCreate `.opencode/command/multi-review.md`:\n\n```bash\ncat \u003e .opencode/command/multi-review.md \u003c\u003c'EOF'\n---\ndescription: Run Codex, Claude, and Gemini in parallel and compare results\n---\n\nUse ai-cli-mcp to run three workers in parallel in the current repository:\n\n1. Codex:\n   Task: security and correctness review.\n   Use AGENTS.md and `.agents/codex-worker.md`.\n\n2. Claude:\n   Task: deep refactoring and architecture review.\n   Use AGENTS.md, CLAUDE.md, and `.agents/claude-worker.md`.\n\n3. Gemini:\n   Task: long-context architecture and documentation review.\n   Use AGENTS.md, GEMINI.md, and `.agents/gemini-worker.md`.\n\nRules for all workers:\n- Do not modify files.\n- Do not access secrets.\n- Include file paths where relevant.\n- Prefer concrete findings over generic advice.\n\nAfter all workers finish:\n1. Wait for all results.\n2. Deduplicate findings.\n3. Separate confirmed issues from weak signals.\n4. Highlight disagreements between agents.\n5. Produce one prioritized action plan.\n6. Suggest which agent should handle each follow-up task.\nEOF\n```\n\n---\n\n## Run Smoke Tests\n\nStart OpenCode:\n\n```bash\ncd ~/ai-workspaces/my-project-agent\nopencode\n```\n\nList MCP tools:\n\n```text\nWhat MCP tools are available?\n```\n\nRun Codex from OpenCode:\n\n```text\nUse ai-cli-mcp to run Codex on this repository.\nTask: summarize the architecture and identify the 5 riskiest files.\nDo not modify files.\n```\n\nRun Claude from OpenCode:\n\n```text\nUse ai-cli-mcp to run Claude Code on this repository.\nTask: review the current codebase for maintainability issues.\nDo not modify files.\n```\n\nRun Gemini from OpenCode:\n\n```text\nUse ai-cli-mcp to run Gemini on this repository.\nTask: produce a high-level system overview and point out unclear module boundaries.\nDo not modify files.\n```\n\nRun the multi-agent command:\n\n```text\n/multi-review\n\nUse the configured Codex, Claude, and Gemini worker profiles.\nEach worker should first state which profile instructions it used.\nDo not modify files.\nReturn a combined action plan.\n```\n\nExpected result:\n\n```text\n- Codex provides security/correctness findings\n- Claude provides refactor/architecture findings\n- Gemini provides architecture/docs findings\n- OpenCode deduplicates and prioritizes all results\n```\n\n---\n\n## Recommended Workflow\n\nUse this flow for serious work:\n\n```text\n1. Google/Gemini compatibility → broad overview\n2. Claude → deep plan\n3. Codex → concrete implementation/test suggestions\n4. OpenCode → final aggregation\n5. Human → approve scope\n6. OpenCode or Codex → implement\n7. Codex → test/lint verification\n8. Claude → final refactor sanity check\n```\n\nExample OpenCode prompt:\n\n```text\nUse the multi-agent workflow.\n\nGoal:\nRefactor the authentication module to make session handling easier to test.\n\nSteps:\n1. Ask Gemini for a broad overview of the auth/session flow.\n2. Ask Claude for a safe refactoring plan.\n3. Ask Codex for concrete test cases.\n4. Compare the outputs.\n5. Do not modify files yet.\n6. Return a final plan with risks and test commands.\n```\n\n### Routing Matrix\n\n| Task                  | Best Worker                          | Reason                                                   |\n| --------------------- | ------------------------------------ | -------------------------------------------------------- |\n| Implement small fix   | Codex                                | Fast, concrete, good for scoped edits                    |\n| Fix failing test      | Codex                                | Can iterate with test output                             |\n| Add missing tests     | Codex                                | Strong at test-focused implementation                    |\n| Security review       | Codex + Claude                       | Codex finds concrete issues, Claude reasons about design |\n| Deep refactor         | Claude                               | Better for multi-file reasoning and trade-offs           |\n| Migration plan        | Claude                               | Better for step-by-step architecture planning            |\n| Architecture overview | Google/Gemini compatibility          | Good for broad long-context analysis                     |\n| Documentation gaps    | Google/Gemini compatibility          | Good at comparing docs and code                          |\n| Second opinion        | Google/Gemini compatibility or Codex | Useful disagreement signal                               |\n| Final implementation  | OpenCode or Codex                    | Keep one agent responsible for final edits               |\n\n---\n\n## Security Rules\n\nThis stack intentionally gives agents the ability to run other local coding agents. Treat it as a privileged automation setup.\n\n`ai-cli-mcp` starts worker CLIs in automation-friendly modes. Current package behavior includes:\n\n```text\nClaude Code: uses --dangerously-skip-permissions\nCodex CLI: uses --dangerously-bypass-approvals-and-sandbox\nGemini CLI: uses automatic approval mode\nOpenCode CLI: uses non-interactive run mode\n```\n\nTherefore, rely on external containment before relying on individual agent prompts:\n\n```text\nsafe copy of the repository\nGit worktree without secrets\ndevcontainer\nephemeral VM\nseparate local user account\nleast-privilege cloud credentials\n```\n\nDo not run this setup in:\n\n```text\n~\n~/.ssh\n~/.kube\n~/Library\n/etc\nproduction repository with real .env files\ndirectories containing cloud credentials\n```\n\nPreferred execution locations:\n\n```text\n~/ai-workspaces/\u003cproject\u003e\ndevcontainer\nseparate user account\nephemeral VM\ngit worktree without secrets\n```\n\nRecommended ignore patterns:\n\n```text\n.env\n.env.*\n.npmrc\n.pypirc\n.netrc\n*.pem\n*.key\nid_rsa\nid_ed25519\nkubeconfig\nconfig\nsecrets.yaml\nvalues-prod.yaml\n```\n\nFor Kubernetes or home lab repositories:\n\n```text\n- Do not expose a real kubeconfig to AI agents by default.\n- Do not allow agents to run kubectl against production contexts.\n- Use read-only or fake configs for analysis.\n- Keep production Helm values and secrets outside the agent workspace.\n```\n\n---\n\n## Troubleshooting\n\n### OpenCode Does Not See MCP Tools\n\nCheck MCP configuration:\n\n```bash\nopencode mcp\nopencode mcp list\n```\n\nRe-add the MCP server:\n\n```bash\nopencode mcp add\n```\n\nCheck whether the MCP server starts manually:\n\n```bash\nnpx -y ai-cli-mcp@latest\n```\n\nThis command should print setup lines and `AI CLI MCP server running on stdio`, then wait for MCP input.\n\n---\n\n### ai-cli Does Not See Codex / Claude / Gemini Compatibility\n\nCheck PATH:\n\n```bash\nwhich codex\nwhich claude\nwhich agy\nwhich gemini\n```\n\nCheck versions:\n\n```bash\ncodex --version\nclaude --version\nagy --version\ngemini --version\n```\n\nRun diagnostics:\n\n```bash\nai-cli doctor\n```\n\n---\n\n### Codex Is Not Authenticated\n\nRun:\n\n```bash\ncodex login\n```\n\nThen test:\n\n```bash\ncodex \"Say hello\"\n```\n\n---\n\n### Claude Is Not Authenticated\n\nRun:\n\n```bash\nclaude\n```\n\nThen initialize non-interactive mode inside a safe workspace:\n\n```bash\ncd ~/ai-workspaces/my-project-agent\nclaude --dangerously-skip-permissions\n```\n\n---\n\n### Antigravity / Gemini Compatibility Is Not Authenticated\n\nRun:\n\n```bash\nagy\ngemini\n```\n\nChoose Google login and complete authentication. `agy` is the forward-looking Google CLI; `gemini` is currently still needed by `ai-cli-mcp` for the Google worker backend.\n\n---\n\n### Worker Job Is Stuck\n\nList jobs:\n\n```bash\nai-cli ps\n```\n\nPeek at output:\n\n```bash\nai-cli peek \u003cPID\u003e --time 10\n```\n\nKill the job:\n\n```bash\nai-cli kill \u003cPID\u003e\n```\n\nClean completed jobs:\n\n```bash\nai-cli cleanup\n```\n\n---\n\n### Unknown or Wrong Model Names\n\nList available aliases and models:\n\n```bash\nai-cli models\nopencode models\nopencode models openai\nopencode models anthropic\n```\n\n---\n\n## Final Readiness Checklist\n\nThe setup is ready when all of these pass:\n\n```bash\nopencode --version\ncodex --version\nclaude --version\nagy --version\ngemini --version\nai-cli doctor\n```\n\n`ai-cli doctor` checks binary availability and path resolution. It does not prove that every CLI is authenticated or that first-run terms were accepted.\n\nVerify authentication separately:\n\n```bash\ncodex doctor\nclaude auth status\nagy\ngemini -p \"Say hello.\"\n```\n\nAnd these smoke tests work:\n\n```bash\ncd ~/ai-workspaces/my-project-agent\n\nopencode run \"Summarize this repository.\"\n\nai-cli run --cwd \"$PWD\" --model sonnet --prompt \"Summarize this repository.\"\nai-cli run --cwd \"$PWD\" --model gpt-5.5 --prompt \"Summarize this repository.\"\nai-cli run --cwd \"$PWD\" --model gemini-2.5-pro --prompt \"Summarize this repository.\"\n```\n\nFinal OpenCode test:\n\n```text\nUse ai-cli-mcp to run Codex, Claude, and Gemini in parallel.\nAsk each to summarize this repository.\nWait for all results and compare their answers.\n```\n\nUntil `ai-cli-mcp` exposes an Antigravity/`agy` backend, the Google worker in the final OpenCode test still uses the Gemini compatibility backend.\n\n---\n\n## Recommended Repository Structure\n\nThis orchestration repository should contain:\n\n```text\nopencode-agent-orchestration/\n  install.sh\n  init.sh\n  README.md\n```\n\nAfter running `init.sh`, the target project workspace should look like this:\n\n```text\nmy-project-agent/\n  AGENTS.md\n  CLAUDE.md\n  GEMINI.md\n  .agents/\n    codex-worker.md\n    claude-worker.md\n    gemini-worker.md\n  .opencode/\n    command/\n      codex-security.md\n      codex-tests.md\n      claude-refactor.md\n      claude-plan.md\n      gemini-architecture.md\n      multi-review.md\n  docs/\n    architecture.md\n    local-dev.md\n    deployment.md\n  src/\n  tests/\n```\n\nThe OpenCode MCP server config should live outside the project:\n\n```text\n~/.config/opencode/opencode.jsonc\n```\n\n---\n\n## Practical Summary\n\nAfter this setup:\n\n```text\n- You work in OpenCode.\n- OpenCode can edit the project directly.\n- OpenCode can call ai-cli-mcp as an MCP server.\n- ai-cli-mcp can run Codex, Claude, and the Gemini compatibility backend as local CLI workers.\n- Antigravity CLI is installed as the forward-looking Google CLI.\n- Worker outputs return to OpenCode.\n- OpenCode aggregates results and performs the final implementation when requested.\n```\n\nThe key limitation remains:\n\n```text\nThis is not a single shared context across all agents.\nEach worker receives a task-specific prompt and working directory, then returns a result.\n```\n\nTherefore, make worker prompts explicit and ask OpenCode to aggregate, compare, and deduplicate results.\n\n---\n\n## License\n\nLicensed under the MIT License. See [LICENSE](LICENSE) for details.\n\n---\n\n## Upstream References\n\nUse these as the source of truth when refreshing this guide:\n\n```text\nOpenCode docs: https://dev.opencode.ai/docs/\nCodex manual: https://developers.openai.com/codex/codex-manual.md\nCodex GitHub README: https://github.com/openai/codex\nClaude Code install docs: https://code.claude.com/docs/en/installation\nClaude Code CLI docs: https://code.claude.com/docs/en/cli-usage\nGoogle Gemini CLI to Antigravity CLI announcement: https://developers.googleblog.com/an-important-update-transitioning-gemini-cli-to-antigravity-cli/\nAntigravity CLI install docs: https://antigravity.google/docs/cli-install\nAntigravity CLI migration docs: https://antigravity.google/docs/gcli-migration\nGemini CLI docs: https://google-gemini.github.io/gemini-cli/\nai-cli-mcp package docs: https://www.npmjs.com/package/ai-cli-mcp\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyurymkomarov%2Fopencode-agent-orchestration","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyurymkomarov%2Fopencode-agent-orchestration","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyurymkomarov%2Fopencode-agent-orchestration/lists"}