Skip to content

Architecture Evaluation

Jump to bottom
Alvian Rahman Hanif edited this page Jun 9, 2026 · 7 revisions

Architecture Evaluation — Code Installation Structure Refactor

The Goal

Make opencode-environment-bootstrap more scalable by splitting it into three layers:

  1. Agent system — generic, works with any AI coding CLI
  2. OpenCode integration — the default CLI that consumes the generic config
  3. Adapters — extendable to also install for Claude Code CLI or Copilot CLI

Why Change the Current Setup?

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

The Solution: Three Layers

Generic config (agent rules + MCP definitions)
       ↓
 Adapter per CLI (translates to that CLI's format)
       ↓
 Installed config (~/.config/opencode/, ~/.claude/, ~/.copilot/)

Layer 1 — Agent System (agent-system/)

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.

Layer 2 — MCP Catalog (mcp/)

One YAML file per MCP server (context7, firecrawl, duckdb, etc.) as the single source of truth. Each file declares {command, args, type, env, enabled}.

Layer 3 — CLI Adapters (cli/{name}/)

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

Is This Feasible?

✅ MCP Translation — Easy

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:

✅ Agent Role Translation — Medium

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: opencode-go/deepseek-v4-pro → sonnet (Claude) → gpt-5.2 (Copilot)
  • Copilot has a 30,000 character limit per agent prompt — long role files may need trimming
  • Writing to ~/.claude.json is risky — Anthropic treats it as an auto-managed state file. Better to use .mcp.json (project-scoped) instead.

Reference:

❌ Multi-Agent DAG (/delegate) — Cannot Port

This is the one thing that can't be replicated outside OpenCode. Here's why:

The /delegate command is a custom OpenCode command (commands/delegate.md). It works because OpenCode provides a task() tool that lets the running agent programmatically spawn sub-agents and chain them in a DAG (planner → coder → reviewer → tester). The primary agent parses annotations like @planner and calls task(subagent_type: "planner") with full context injection.

What it needs OpenCode Claude CLI Copilot CLI
Agent A spawns Agent B programmatically ✅ task() tool ❌ Subagents can't nest — hard limit ❌ Delegation is model-driven (AI decides), not user-directed
Custom DAG workflow ✅ /delegate command ❌ No custom slash commands ❌ No user-defined workflow
Context injection into sub-agents ✅ Automatic via prompt injection ❌ Manual file passing ❌ Not user-controllable

This is not a translation problem — it's a capability gap. The runtimes simply don't expose the same primitives.

Three approaches to bridge the gap:

Approach What it does Works for Fidelity
A. Simplified single-agent Install MCPs + agent roles but no orchestration. User picks role at launch (claude --agent planner) Claude, Copilot Medium — no DAG, but all tools/rules work
B. Shell wrapper A script that runs claude --agent planner "..." && claude --agent coder "..." passing context between steps Claude Medium — sequential but no interactivity
C. ACP orchestrator A daemon that implements DAG logic externally, driving Copilot via Agent Client Protocol Copilot High — ACP is built for this

Recommendation: Ship Approach A as the default for Claude/Copilot. The DAG workflow stays OpenCode-native — that's a feature differentiator, not a bug.

Verdict

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 ❌ Can't port — OpenCode native capability N/A

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. The adapters are all feasible for config generation. The honest limitation is that the multi-agent DAG workflow (/delegate) stays OpenCode-native — Claude and Copilot get the same agent rules and MCP tools, but running in simplified single-agent mode.

Extended CLI Adapter Analysis — 10 CLI Tools Evaluated

Below is a comprehensive evaluation of 10 AI coding CLI tools across three dimensions: MCP support (config adapters), agent role definitions, and multi-agent DAG orchestration (Planner→Coder→Reviewer→Tester).

1. OpenCode CLI ✅

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.

2. Claude Code CLI

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).

3. GitHub Copilot CLI

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).

4. Aider

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.

5. Amazon Q CLI

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.

6. Continue CLI

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.

7. OpenHands

Dimension Verdict
MCP translation ⚠️ Partial — MCP support available but less mature than CLI-first tools. Primarily a web-based platform.
Agent role definition ✅ Micro-agents concept — small, focused agent specifications. Role definitions are composable.
DAG orchestration ⚠️ Partial — delegation capability exists. Micro-agents can be chained. SDK/headless mode available. A Python orchestrator script could likely build a DAG scheduler (~2-3 days effort). Web UI is the primary interface, CLI is secondary.

Key features: Micro-agents for composable roles; SDK for programmatic control; primarily a web platform with CLI secondary; strongest DAG potential after OpenCode.

8. Goose (Block/AAIF)

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.

9. Open Interpreter

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.

10. MetaGPT

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 ⚠️ Multi-agent is built-in as a fixed pipeline (the "software company" SOP). Not a user-definable DAG — you can't create your own Planner→Coder→Reviewer→Tester flow. The pipeline is: requirement → user stories → competitive analysis → design → API specs → code generation → docs. Offers Python library access for more control.

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.

11. ChatDev

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 ⚠️ Configurable multi-agent workflows — this is the entire point of v2.0. Agents are orchestrated through a visual/configuration interface. However, this is a web platform with its own runtime, not a CLI tool you'd install via a bootstrap script. The orchestration runtime is ChatDev's own backend, not a CLI primitive you can compose.

Key numbers: ChatDev 2.0 rebranded as "DevAll — A Zero-Code Multi-Agent Platform for Developing Everything"; NeurIPS 2025 paper on multi-agent orchestration; 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.

12. gpt-engineer

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.

Multi-Agent DAG Orchestration — Summary Table

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 ⚠️ Marginal
Continue CLI ✅ Native ✅ Hub slugs ❌ No chaining ⚠️ Marginal
OpenHands ⚠️ Partial ✅ Micro-agents ⚠️ SDK-based possible ⚠️ ~2-3 days
Goose (AAIF) ✅ 70+ MCPs ✅ AGENTS.md/skills ❌ No task(), ACP possible ✅ ~200 lines
Open Interpreter ❌ None ❌ Single-agent ❌ None ❌ Not viable
MetaGPT ❌ None ⚠️ Fixed SOP roles ⚠️ Fixed pipeline ❌ Not viable
ChatDev ❌ None ✅ Configurable ⚠️ Platform runtime ❌ Not CLI
gpt-engineer ❌ None ❌ Single-agent ❌ None ❌ Archived

Final Verdict

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 ⚠️ Low Micro-agents are interesting, but platform-first

The DAG orchestration pattern (/delegate + task()) remains an OpenCode-native differentiator — no other CLI exposes the subagent-spawning primitives needed for automatic context passing between roles. This is not a limitation of the bootstrap installer; it's a fundamental capability gap in other runtimes.

Reference Links

Clone this wiki locally