-
Notifications
You must be signed in to change notification settings - Fork 0
Architecture Evaluation
Make opencode-environment-bootstrap more scalable by splitting it into three layers:
- Agent system — generic, works with any AI coding CLI
- OpenCode integration — the default CLI that consumes the generic config
- Adapters — extendable to also install for Claude Code CLI or Copilot CLI
The current codebase bundles everything into one opencode-shaped box:
| Problem | What it means |
|---|---|
| All agent skills and MCP configs live inside opencode-specific templates | You can't reuse the agent methodology with another CLI |
| MCP servers (context7, firecrawl, etc.) are only defined in opencode.json format | Every new CLI target means re-declaring them manually |
| The installer hardcodes opencode CLI's install URL and config path | No option to pick a different CLI at install time |
Verification only checks for the opencode binary |
Won't detect if other CLIs are configured |
Generic config (agent rules + MCP definitions)
↓
Adapter per CLI (translates to that CLI's format)
↓
Installed config (~/.config/opencode/, ~/.claude/, ~/.copilot/)
CLI-agnostic markdown files describing what each agent role does (planner, coder, reviewer, etc.), how sessions work, and what rules to follow. No references to any specific CLI's APIs.
One YAML file per MCP server (context7, firecrawl, duckdb, etc.) as the single source of truth. Each file declares {command, args, type, env, enabled}.
A small Python script per CLI that reads Layers 1 + 2 and generates the CLI's native config format:
-
cli/opencode/→opencode.json(agents + MCPs + commands + plugins) -
cli/claude/→.claude/agents/*.agent.md+CLAUDE.md+.mcp.json -
cli/copilot/→~/.copilot/agents/*.agent.md+mcp-config.json+copilot-instructions.md
All three CLIs support MCP servers with very similar schemas. Translation is just renaming keys:
| OpenCode | Claude CLI | Copilot CLI |
|---|---|---|
{ type: "local", command: ["npx", ...], environment: {...} } |
{ type: "stdio", command: "npx", args: [...], env: {...} } |
{ type: "local", command: "npx", args: [...], env: {...} } |
{ type: "remote", url, headers } |
{ type: "http", url, headers } |
{ type: "http", url, headers } |
Reference:
Each CLI has its own way of defining agents:
| CLI | Format | Where agents live |
|---|---|---|
| OpenCode | JSON block in opencode.json
|
opencode.json agent key |
| Claude CLI | YAML frontmatter + Markdown body | ~/.claude/agents/*.agent.md |
| Copilot CLI | YAML frontmatter + Markdown body | ~/.copilot/agents/*.agent.md |
The concepts overlap (description, tools allowed/denied, model selection, system prompt), so the adapter maps generic config → CLI-specific format. The main gotchas:
-
Model names differ — need a translation table (~15–20 entries across all adapters):
opencode-go/deepseek-v4-pro→sonnet(Claude) →gpt-5.2(Copilot). Unmapped model names should fall back to the CLI's default model rather than erroring out. - Copilot has a 30,000 character limit per agent prompt — long role files may need trimming
-
Writing to
~/.claude.jsonis risky — Anthropic treats it as an auto-managed state file. Better to use.mcp.json(project-scoped) instead.
Reference:
There are two separate questions that our analysis initially conflated:
| Question | Answer |
|---|---|
Can other CLIs replicate OpenCode's in-CLI task() spawning? |
❌ No — task() is a unique primitive. No other CLI lets an agent spawn a sub-agent in the same process. |
| Can DAG orchestration work at all with other CLIs? | ✅ Yes — via an external orchestrator that runs each CLI step sequentially. |
The /delegate command works because OpenCode provides a task() tool — the running agent programmatically spawns sub-agents and chains them in a DAG, with automatic context injection via prompt.
Other CLIs don't have task(), but they can still participate in a DAG — just not inside the CLI runtime itself.
| Tool | External DAG method | Fidelity |
|---|---|---|
| OpenCode | Native task() in-process |
High — real-time, interactive, auto context |
| Claude Code | Shell: claude --agent planner "..." && claude --agent coder "..." with file-based artifact passing |
Medium — sequential, no interactivity, manual context |
| Copilot CLI | ACP daemon — external driver calls Copilot's ACP API | Medium-High — ACP is built for this but requires a daemon (speculative — not confirmed production-ready) |
| Goose (AAIF) | ACP provider mode or goose run -t with --with-extension MCP passthrough |
Medium-High — ACP support confirmed, but DAG chaining via goose run -t is speculative |
| Continue | Headless CLI mode + JSON config | Medium — headless exists but is secondary to editor |
| Aider | Python API subprocess (undocumented) | Low-Medium — works but no standard protocol |
| OpenHands | SDK-based orchestrator | Medium — SDK exists, web-native |
| MetaGPT | Python library: await agent.run()
|
Medium — fully programmable library |
| ChatDev | Web platform runtime | Low — not CLI-based at all |
| Dimension | OpenCode task() (in-CLI) |
External orchestration |
|---|---|---|
| Real-time interactivity | ✅ Sub-agent runs in same session; can redirect mid-flow | ❌ Each step is a separate process; no mid-flow intervention |
| Automatic context passing | ✅ Prompts + outputs flow between agents automatically | ❌ Must manually serialize/deserialize artifacts between steps |
| Latency per step | ✅ Minimal — in-process, no re-initialization | ❌ Each step re-loads model context and tool configuration |
| Error recovery | ✅ Can handle errors within the DAG flow | ❌ External orchestrator must implement retries/state management |
| Approach | What it does | Works for | Fidelity |
|---|---|---|---|
| A. Simplified single-agent | Install MCPs + agent rules but no orchestration. User picks role at launch (claude --agent planner) |
All CLIs | Medium — no DAG, but all tools/rules work |
| B. External orchestrator | A script (bash, Python, Temporal) runs each CLI step in sequence, passing context via files/artifacts | All CLIs with headless/subprocess mode | Medium-High — full DAG possible, no interactivity |
| C. ACP orchestrator | A daemon that implements DAG logic externally via Agent Client Protocol | Copilot, Goose, Claude (via ACP adapters) | High — ACP is built for external orchestration |
The real architectural question is: does orchestration belong inside the CLI runtime or above it?
Answer: both — in-CLI for interactive, real-time DAGs; above-CLI for automation, CI/CD pipelines, and cross-CLI workflows.
- OpenCode's
task()is the only in-CLI option — useful for interactive, real-time DAGs where the user intervenes mid-flow - Approach B (external orchestrator) works for every CLI and is simpler to build — ideal for scripted, non-interactive pipelines
- Approach C (ACP) is the long-term winner if ACP adoption grows — it externalizes orchestration and standardizes agent execution, reducing the value of CLI-native primitives
Recommendation: Ship Approach A as the install-time default. Provide Approach B as a companion script for users who want DAG workflows outside OpenCode. Watch ACP (Approach C) as the long-term strategic direction.
| What | Is it worth building? | Effort |
|---|---|---|
| MCP catalog + translation | ✅ Yes — single source of truth, all three CLIs support it | ~20 lines per adapter |
| Agent role extraction | ✅ Yes — makes the methodology reusable | ~50 lines per adapter |
| OpenCode adapter | ✅ Yes — cleaner architecture, same output | ~150 lines |
| Claude adapter | ✅ Yes — config generation is straightforward | ~250 lines |
| Copilot adapter | ✅ Yes — same approach, plus ACP for future orchestration | ~300 lines |
| DAG orchestration (in-CLI) | ❌ OpenCode-only via task() — other CLIs can achieve DAGs via external orchestration
|
See below |
| DAG orchestration (external) | ✅ All CLIs with headless/subprocess mode — companion script recommended | ~150 lines |
Bottom line: The three-layer architecture is a clear improvement. It cleans up the monolithic structure, creates a single source of truth for MCP servers, and makes the agent methodology available to other CLIs. OpenCode's native task()-based DAG is a genuine differentiator, but DAG orchestration isn't a hard blocker for other CLIs — an external orchestrator script (Approach B) can sequence any CLI with headless mode, at the cost of slower steps and manual context passing. Ship Approach A (single-agent adapters) at install time, provide Approach B (orchestration script) as an optional companion.
Below is a comprehensive evaluation of 12 AI coding CLI tools across three dimensions: MCP support (config adapters), agent role definitions, and multi-agent DAG orchestration (Planner→Coder→Reviewer→Tester).
| Dimension | Verdict |
|---|---|
| MCP translation | ✅ Native — JSON agent/MCP config in opencode.json. Direct format, no adapter needed. |
| Agent role definition | ✅ Full support — custom agents in opencode.json with model, permissions, system prompt. |
| DAG orchestration | ✅ Native — task() tool for programmatic subagent spawning, /delegate command for annotation-driven DAGs. |
Verdict: The reference implementation. The only CLI with a task() primitive that enables the full Planner→Coder→Reviewer→Tester DAG with automatic context passing.
| Dimension | Verdict |
|---|---|
| MCP translation | ✅ Supported via .mcp.json (project-scoped). Schema maps 1:1 with OpenCode's local/remote types. |
| Agent role definition | ✅ Supported via ~/.claude/agents/*.agent.md (YAML frontmatter + Markdown body). Subagents exist but cannot nest (hard limit). |
| DAG orchestration | ❌ No task() equivalent. Subagents can't spawn sub-subagents. --agent flag selects one role at launch. Shell wrapper approach (sequential claude --agent X "...") possible but no interactivity or context passing. |
Key numbers: Agents defined as Markdown files; model names differ (sonnet vs opencode-go/deepseek...); writing to ~/.claude.json is risky (auto-managed).
Verdict: Strong adapter candidate — MCP and subagent support are mature. DAG orchestration is limited to single-agent mode or external shell wrapper since subagents cannot nest.
| Dimension | Verdict |
|---|---|
| MCP translation | ✅ Supported via mcp-config.json or ~/.copilot/mcp.json. Schema compatible. |
| Agent role definition | ✅ Supported via ~/.copilot/agents/*.agent.md (YAML frontmatter + Markdown). 30,000 character limit per agent prompt — long role files need trimming. |
| DAG orchestration | ❌ Delegation is model-driven (AI decides when to delegate), not user-directed. No task() tool. ACP (Agent Client Protocol) exists for external orchestration — a daemon could implement DAG logic externally. No custom slash commands or user-defined workflows. |
Key numbers: 30k char agent prompt limit; ACP support opens door for external orchestration (~2-3 days to build ACP-based DAG driver).
Verdict: Strong adapter candidate — MCP and agent formats align well with the three-layer architecture. Key constraints: 30k-char agent prompt limit and model-driven (not user-directed) delegation.
| Dimension | Verdict |
|---|---|
| MCP translation | ❌ No MCP support. Aider uses its own tool system (file editing, shell, etc.) — no standard MCP interface. |
| Agent role definition | ❌ No custom agent roles. Architect/Code mode is hardcoded as a 2-stage process, not user-configurable roles. |
| DAG orchestration | ❌ No subagent spawning. 2-stage Architect→Code is the only built-in multi-step flow. Python API exists but is undocumented and unstable for external orchestration. |
Verdict: Aider is not a viable adapter target. No MCP, no custom agents, no DAG. The README for gpt-engineer even recommends aider as a "well maintained hackable CLI" but for code-gen, not for multi-agent workflows.
| Dimension | Verdict |
|---|---|
| MCP translation | ✅ Supported — Amazon Q Developer supports MCP servers. |
| Agent role definition | ✅ /agent generate for creating custom agents. Agent descriptions and tool configurations are supported. |
| DAG orchestration | ❌ No agent-to-agent chaining. Hooks system exists for custom logic. No task() equivalent. MCP support enables tool integration but not subagent spawning. |
Key features: Hooks system for event-driven custom logic; /dev for development tasks; /transform for code transformations; MCP support is relatively recent.
Verdict: Marginal — MCP and agent support exist but DAG chaining is absent. Only worth building an adapter if targeting AWS-ecosystem teams.
| Dimension | Verdict |
|---|---|
| MCP translation | ✅ Native MCP support — first-class citizen in the Continue ecosystem. |
| Agent role definition | ✅ Hub-based agent slugs. Custom agents via ~/.continue/config.json. Model, tools, and prompt are configurable. |
| DAG orchestration | ❌ No agent-to-agent chaining. Headless mode available for scripting but no subagent spawning. Hub agents are single-instance. Could be scripted externally via headless mode + Python shell wrapper. |
Key features: Open source; headless mode for non-interactive use; JetBrains/VS Code extensions alongside CLI; config is JSON-based similar to OpenCode.
Verdict: Marginal — MCP-native and flexible agent config, but CLI is secondary to the editor extension. Headless mode enables external orchestration but with no interactivity.
| Dimension | Verdict |
|---|---|
| MCP translation | |
| Agent role definition | ✅ Micro-agents concept — small, focused agent specifications. Role definitions are composable. |
| DAG orchestration |
Key features: Micro-agents for composable roles; SDK for programmatic control; primarily a web platform with CLI secondary; strongest DAG potential after OpenCode.
Verdict: Low priority — most interesting DAG potential after OpenCode (micro-agents + SDK), but web-platform-first architecture makes CLI integration secondary.
Note: "Block" refers to Block, Inc. (formerly Square), the company backing Goose. "AAIF" = Agentic AI Innovation Framework, a Linux Foundation project. Goose is hosted under the AAIF umbrella.
| Dimension | Verdict |
|---|---|
| MCP translation | ✅ Excellent MCP support — 70+ extensions via MCP standard. Config via goose configure or environment variables. Native CLI + Desktop + API. |
| Agent role definition | ✅ Has AGENTS.md, skills system, CLAUDE.md support. Supports .goosehints for project-level configuration. Provider-agnostic (15+ LLM providers). |
| DAG orchestration | ❌ No task() equivalent for subagent spawning. However — ACP support is a notable exception. Goose itself can act as an ACP provider, meaning it can be driven by external orchestrators. Also can use Claude ACP / Codex ACP as backends. But no native Planner→Coder→Reviewer→Tester chaining with context passing. |
Key numbers: 48.3k stars; Rust-based (performance); v1.37.0 (very active); Linux Foundation (AAIF); MCP + ACP dual protocol support; Desktop + CLI + API triple interface; single-agent focused by design.
Verdict: Worth an adapter — strongest CLI candidate after OpenCode for MCP and agent support. DAG orchestration would need an ACP-based external driver.
| Dimension | Verdict |
|---|---|
| MCP translation | ❌ No MCP support. Uses its own tool system — LLM generates and runs code (Python, JS, Shell) locally. No standard protocol integration. |
| Agent role definition | ❌ Single-agent only. No multi-agent concept, no custom agent roles, no specialized system prompts per role. A single LLM + tool-calling loop. |
| DAG orchestration | ❌ No subagent concept at all. A single interpreter session runs one loop. Code execution is its primary function, not multi-step orchestration. |
Verdict: Not viable as an adapter target. Single-agent code executor with no role specialization, no MCP, no orchestration. The project has also been less active — its value is as a local code execution sandbox, not an agent framework.
| Dimension | Verdict |
|---|---|
| MCP translation | ❌ No MCP support. Uses its own agent communication protocols. |
| Agent role definition | ✅ Built-in multi-agent roles (Product Manager, Architect, Engineer, Project Manager) — but these are hardcoded SOPs, not user-configurable. You don't define roles; you use the predefined ones. |
| DAG orchestration |
Key numbers: 68.6k stars; Python-based; last release Apr 2024; last commit Jan 2026 (nearly dormant); the "software company" metaphor is compelling but rigid.
Verdict: Interesting multi-agent research project but not suitable as an adapter target. The fixed SOP pipeline is the opposite of the flexible DAG approach needed. If you want predefined software dev workflows, MetaGPT is great. If you want custom agent orchestration, it's not.
| Dimension | Verdict |
|---|---|
| MCP translation | ❌ No MCP support. Uses its own agent communication protocols within the platform. |
| Agent role definition | ✅ Zero-code multi-agent platform (v2.0, Jan 2026). Users define agents, workflows, and tasks through config. No coding required. |
| DAG orchestration |
Key numbers: ChatDev 2.0 rebranded as "DevAll — A Zero-Code Multi-Agent Platform for Developing Everything"; accepted at NeurIPS 2025 (published Dec 2025); web UI + backend architecture; not CLI-first.
Verdict: Not viable as an adapter target — it's a platform, not a CLI tool. However, the configurable multi-agent orchestration pattern is worth studying for the generic agent-system design. The zero-code agent definition approach (define agents + workflows via config) directly validates the three-layer architecture's direction.
| Dimension | Verdict |
|---|---|
| MCP translation | ❌ No MCP support. Uses its own preprompt + code generation system. |
| Agent role definition | ❌ Single-agent. No role specialization, no multi-agent concept. Does have "preprompts" for customizing behavior, but these are system prompts, not role definitions. |
| DAG orchestration | ❌ No orchestration capabilities. Single prompt → code output. The -i flag enables improvement mode but it's still one agent in one session. |
Status: ARCHIVED (Apr 22, 2026). Repository is read-only. The README recommends aider as an alternative: "If you are looking for an opinionated, managed service – check out gptengineer.app. If you are looking for a well maintained hackable CLI – check out aider."
Verdict: Dead project. Not an adapter target. Historically significant as one of the first "AI writes code from prompts" projects.
| Tool | MCP Support | Custom Agent Roles | DAG Orchestration | Adapter Worth Building? |
|---|---|---|---|---|
| OpenCode CLI | ✅ Native | ✅ Full | ✅ Native task()
|
(reference) |
| Claude Code CLI | ✅ .mcp.json
|
✅ Subagents, no nesting | ❌ No task()
|
✅ ~250 lines |
| Copilot CLI | ✅ MCP config | ✅ 30k char limit | ❌ Model-driven only | ✅ ~300 lines |
| Aider | ❌ None | ❌ Hardcoded modes | ❌ None | ❌ Not viable |
| Amazon Q CLI | ✅ Supported | ✅ /agent generate
|
❌ No chaining | |
| Continue CLI | ✅ Native | ✅ Hub slugs | ❌ No chaining | |
| OpenHands | ✅ Micro-agents | |||
| Goose (AAIF) | ✅ 70+ MCPs | ✅ AGENTS.md/skills | ❌ No task(), ACP possible |
✅ ~200 lines |
| Open Interpreter | ❌ None | ❌ Single-agent | ❌ None | ❌ Not viable |
| MetaGPT | ❌ None | ❌ Not viable | ||
| ChatDev | ❌ None | ✅ Configurable | ❌ Not CLI | |
| gpt-engineer | ❌ None | ❌ Single-agent | ❌ None | ❌ Archived |
The three-layer architecture (generic agent-system + MCP catalog + CLI adapters) is feasible and worth building. Five of twelve evaluated tools are viable adapter targets:
| Tool | Priority | Why |
|---|---|---|
| OpenCode | ✅ Default | Native format, full DAG support — the reference |
| Claude Code | ✅ High | MCP + subagents, most popular alternative |
| Copilot | ✅ High | MCP + agents, enterprise adoption |
| Goose | ✅ Medium | Best MCP ecosystem (70+), ACP for future DAG |
| OpenHands | Micro-agents are interesting, but platform-first |
OpenCode's in-CLI DAG orchestration is a genuine differentiator, but this is a question of runtime fidelity, not feasibility — all CLIs with headless mode can participate in DAG workflows via external orchestration. The architecture should acknowledge this distinction explicitly:
-
In-CLI orchestration → OpenCode only (via
task()) - External orchestration → Available for all CLIs (via companion orchestrator script or ACP)
-
ACP-based orchestration → Long-term strategic bet — if ACP matures, OpenCode's
task()advantage diminishes as orchestration moves outside the CLI entirely
- opencode-environment-bootstrap
- OpenCode CLI
- OpenCode config docs
- OpenCode agent docs
- OpenCode MCP docs
- Claude Code CLI (Anthropic)
- Claude Code subagents
- Copilot CLI (GitHub)
- Copilot custom instructions
- Copilot MCP servers
- Goose (AAIF)
- Goose documentation
- MetaGPT
- ChatDev
- Aider
- Open Interpreter
- Continue CLI
- Amazon Q Developer
- OpenHands
- Model Context Protocol
- Agent Client Protocol