Claude Code VS OpenCode: Architecture, Design & The Road Ahead — Table of Contents

Model: claude-opus-4-6 (anthropic/claude-opus-4-6)
Token Usage: ~45,000 input + ~8,000 output (TOC generation)
Tools: OpenCode + Oh-My-OpenCode
Generated: 2026-04-01
Subjects: OpenCode, Oh-My-OpenCode, Claude Code

Language

中文版本

Book Structure Overview

This book — Claude Code VS OpenCode — provides an in-depth multi-dimensional analysis comparing three AI coding agent systems — OpenCode (open-source foundation), Oh-My-OpenCode (multi-agent orchestration layer), and Claude Code (Anthropic's commercial agent) — from shared architectural patterns to distinctive innovations, culminating in best practices for agent design.

Part I: The Landscape

Chapter 1: The Evolution of Coding Agents

Tracing the three eras of AI coding — from autocomplete to chat copilot to autonomous agent — and why scaffolding matters more than the model.

• 1.1 From Code Completion to Autonomous Agents
• 1.2 Market Landscape & Technical Divide
• 1.3 "Scaffolding Matters More Than the Model"
• 1.4 The Three Systems Under Study

Chapter 2: The Three Systems at a Glance

A high-level overview of OpenCode, Oh-My-OpenCode, and Claude Code — tech stacks, core positioning, and a quick comparison matrix.

• 2.1 OpenCode: The Open-Source Foundation
• 2.2 Oh-My-OpenCode: The Orchestration Revolution
• 2.3 Claude Code: The Commercial Benchmark
• 2.4 Quick Comparison Matrix

Part II: Shared Architecture (Commonalities)

Chapter 3: The Core Loop — The ReAct Paradigm

The foundational execution model shared by all three systems: think, act, observe, repeat.

• 3.1 The Think-Act-Observe Cycle
• 3.2 Streaming Architecture
• 3.3 Stop Conditions & Loop Control

Chapter 4: Tool System Design

Tools are the only way agents interact with the external world — how they're defined, registered, secured, and executed.

• 4.1 Tool Definition Paradigm
• 4.2 Shared Tool Inventory
• 4.3 Tool Permissions & Safety
• 4.4 Tool Output Handling

Chapter 5: Session & Context Management

How conversations are persisted, messages structured, context compacted, and sessions recovered across interruptions.

• 5.1 Session Persistence
• 5.2 Message Structure
• 5.3 Context Compaction
• 5.4 Session Recovery & Continuation

Chapter 6: LLM Provider Abstraction

From 20+ provider SDKs to a single streaming interface — how each system abstracts model access.

• 6.1 Multi-Model Support Architecture
• 6.2 Model Capability Detection
• 6.3 Authentication & Key Management

Chapter 7: MCP — The USB-C of AI

Model Context Protocol: why it changes everything, how each system implements it, and MCP vs A2A.

• 7.1 Why MCP Changes Everything
• 7.2 MCP Implementation Across Three Systems
• 7.3 MCP vs A2A: Complementary, Not Competing

Chapter 8: Configuration & Customization

Multi-level config precedence, project memory systems, and instruction assembly pipelines.

• 8.1 Multi-Level Config Precedence
• 8.2 Project Memory System
• 8.3 Instruction System

Part III: Distinctive Features

Chapter 9: OpenCode's Unique Contributions

Multi-interface architecture, ACP protocol, namespace organization, SDK programmability, and plan mode.

• 9.1 Multi-Interface Architecture
• 9.2 ACP: Agent Client Protocol
• 9.3 Namespace Organization Pattern
• 9.4 SDK & Programmability
• 9.5 Plan Mode

Chapter 10: Oh-My-OpenCode's Innovations

Three-layer orchestration, semantic categories, Ultrawork mode, Ralph Loop, wisdom accumulation, 41-hook system, skill-embedded MCPs, and Tmux visual multi-agent.

• 10.1 Three-Layer Orchestration Architecture
• 10.2 Semantic Category System
• 10.3 Ultrawork Mode
• 10.4 Ralph Loop & Todo Continuation
• 10.5 Wisdom Accumulation System
• 10.6 The 41-Hook Five-Tier System
• 10.7 Skill-Embedded MCPs
• 10.8 Tmux Visual Multi-Agent

Chapter 11: Claude Code's Commercial Design

ML permission classifier, cost control, enterprise readiness, custom Ink renderer, multi-strategy compaction, Bridge/Coordinator modes, and 100+ slash commands.

• 11.1 Security Architecture
• 11.2 Cost Control
• 11.3 Enterprise Readiness
• 11.4 Custom Ink Implementation
• 11.5 Multi-Strategy Context Compaction
• 11.6 Bridge Mode & Coordinator Mode
• 11.7 The 100+ Slash Command System

Part IV: Deep Dive — How Oh-My-OpenCode is Built on OpenCode

Chapter 12: Anatomy of a 130K-LOC Plugin

A source-code-level deep dive into how Oh-My-OpenCode leverages OpenCode's plugin system to build an entire multi-agent orchestration layer — without forking a single line of the host.

• 12.1 Plugin Entry Point & Bootstrap Sequence

  • src/index.ts: The 8-hook handshake with OpenCode's plugin system
  • 6-phase initialization: provider → plugin-components → agents → tools → MCPs → commands
  • Lifecycle: how OMO boots before the first user message arrives

• 12.2 The 8 OpenCode Hook Handlers

  • config: Injecting agents, tools, MCPs, commands into OpenCode's registry
  • tool: Registering 26 custom tools via OpenCode SDK
  • chat.message: First-message variant gate, session setup, keyword detection
  • chat.params: Anthropic effort level adjustment
  • event: Session lifecycle event handling
  • tool.execute.before / tool.execute.after: Pre/post tool interception
  • experimental.chat.messages.transform: Context injection and thinking block validation

• 12.3 Tool Injection Architecture

  • How OMO's 26 tools are registered via plugin/tool-registry.ts
  • Tool wrapping pattern: OpenCode SDK tool → OMO tool with extra context
  • The delegate-task tool: spawning subagents through OpenCode's session system
  • Background task tools: concurrency management atop OpenCode's infrastructure

• 12.4 Agent System Implementation

  • builtin-agents.ts: Factory functions for 11 agents with model resolution and fallback chains
  • Dynamic prompt building: dynamic-agent-prompt-builder.ts — tool tables, delegation guides, hard blocks
  • How agents map to OpenCode's native agent concept vs. OMO's orchestration layer
  • System prompt assembly: modular sections (identity, interview, plan generation, behavioral constraints)

• 12.5 Hook System: 41 Hooks on 5 OpenCode Hook Points

  • How 41 OMO hooks are multiplexed onto OpenCode's 5 plugin hook points
  • Hook execution order and priority
  • The tool.execute.before pipeline: file guard → label truncator → rules injector
  • The experimental.chat.messages.transform pipeline: context injection → thinking validation → todo preservation
  • Hook enable/disable via configuration

• 12.6 Configuration Layering

  • How OMO's 3-level config (project → user → defaults) coexists with OpenCode's 7-level config
  • 22 Zod v4 schema files: agents, categories, hooks, MCPs, skills, commands, experimental
  • JSONC support: why comments in config files matter for DX
  • Config validation and partial fallback strategy

• 12.7 Claude Code Compatibility Layer

  • Loading Claude Code plugins from .opencode/plugins/
  • Loading Claude Code commands from .opencode/command/
  • Loading Claude Code agents from .opencode/agents/
  • Loading Claude Code MCPs from .mcp.json with ${VAR} env expansion
  • Why OMO maintains Claude Code compatibility: the migration path argument

• 12.8 Background Agent Spawner & Session Management

  • How OMO creates new OpenCode sessions for background agents
  • Concurrency management: 5 concurrent per model/provider
  • Parent session notification mechanism
  • Session continuation via session_id — preserving full context across turns
  • The boulder state: tracking Sisyphus continuation across interruptions

Part V: Deep Comparative Analysis

Chapter 13: Architectural Philosophy Comparison

Open vs closed, simple vs complex, control vs autonomy, general vs specialized.

• 13.1 Open vs Closed
• 13.2 Simplicity vs Complexity
• 13.3 Control vs Autonomy
• 13.4 General vs Specialized

Chapter 14: Tool System Deep Comparison

Tool count vs coverage, unique tools, LSP integration depth, and tool composition patterns.

• 14.1 Tool Count & Coverage
• 14.2 Unique Tools
• 14.3 LSP Integration Depth
• 14.4 Tool Composition Patterns

Chapter 15: Agent Orchestration Comparison

Single-agent vs multi-agent, specialization, background tasks, wisdom transfer vs context isolation.

• 15.1 Orchestration Pattern Taxonomy
• 15.2 Single-Agent vs Multi-Agent
• 15.3 Agent Specialization
• 15.4 Background Tasks & Parallel Execution
• 15.5 Wisdom Transfer vs Context Isolation

Chapter 16: Extensibility Comparison

Plugin systems, skill systems, command systems, hook systems, and manifest-driven discovery.

• 16.1 Plugin System
• 16.2 Skill System
• 16.3 Command System
• 16.4 Hook System
• 16.5 Manifest-Driven Discovery

Chapter 17: Security Model Comparison

Permission paradigms, sandboxing, supply chain security, and credential isolation.

• 17.1 Permission Paradigms
• 17.2 Sandboxing
• 17.3 Supply Chain Security
• 17.4 Credential Isolation

Part VI: Agent Design Best Practices

Chapter 18: Architecture of the Ideal Coding Agent

The consensus architecture for 2026, the five defining tensions, and lessons from the three systems.

• 18.1 Consensus Architecture: 2026 Best Practices
• 18.2 The Five Defining Tensions
• 18.3 Lessons from the Three Systems

Chapter 19: The Art of Tool Design

ACI design principles, minimal tool sets, cognitive cost of tool output, and tool composition vs bloat.

• 19.1 ACI (Agent-Computer Interface) Principles
• 19.2 Minimal Tool Set Principle
• 19.3 Cognitive Cost of Tool Output
• 19.4 Tool Composition vs Tool Bloat

Chapter 20: Context Engineering

The shift from prompt engineering to context engineering — four memory strategies and overflow recovery.

• 20.1 From Prompt Engineering to Context Engineering
• 20.2 Four Memory Strategies
• 20.3 Automatic Context Injection
• 20.4 Context Window Overflow Recovery

Chapter 21: The Art of Multi-Agent Orchestration

Five orchestration patterns, when to use multi-agent, specialization design, wisdom accumulation, and parallel execution challenges.

• 21.1 Five Orchestration Patterns
• 21.2 When to Use Multi-Agent
• 21.3 Designing Agent Specialization
• 21.4 Wisdom Accumulation vs Context Isolation
• 21.5 Challenges of Parallel Execution

Chapter 22: Designing for Extensibility

Three content types, MCP as universal substrate, lifecycle hooks, and the simplicity spectrum.

• 22.1 Three Content Types
• 22.2 MCP as Universal Extensibility Substrate
• 22.3 Lifecycle Hooks
• 22.4 The Simplicity Spectrum

Chapter 23: Balancing Safety & Autonomy

Threat models, sandboxing, capability declaration, and lessons from Claude Code's 84% permission reduction.

• 23.1 Threat Model
• 23.2 Sandboxing is Key
• 23.3 Capability Declaration Pattern
• 23.4 Lessons from Claude Code

Part VII: Future & Practice

Chapter 24: What's Next for Coding Agents

From code generation to software engineering, vibe coding, convergence trends, and unsolved challenges.

• 24.1 From "Code Generation" to "Software Engineering"
• 24.2 "Vibe Coding" & The Evolving Developer Role
• 24.3 Convergence Trends
• 24.4 Unsolved Challenges

Chapter 25: Building Your Own Coding Agent

The starting decision tree, minimum viable agent, pitfalls to avoid, and what to measure.

• 25.1 The Starting Decision Tree
• 25.2 Minimum Viable Agent
• 25.3 Pitfalls to Avoid
• 25.4 What to Measure

Chapter 26: Designing "Oh-My-Claude-Code" — A Multi-Agent Plugin for Claude Code

A thought experiment and architectural blueprint: if we were to build an OMO-equivalent orchestration layer for Claude Code, what would it look like? What's possible, what's missing, and what would need to change?

• 26.1 Claude Code's Extension Surface: What's Available Today

  • Hooks (session_start, pre_compact, post_compact, post_sampling, file_changed)
  • Plugins (.claude/plugins/) with commands, tools, skills, hooks
  • Custom agents (.claude/agents/) with markdown definitions
  • MCP servers (.claude/mcp.json) for external tools
  • CLAUDE.md / memory system for persistent context
  • What's exposed vs. what's locked down

• 26.2 Gap Analysis: OpenCode Plugin API vs Claude Code Extension API

  • OpenCode's 8 hook points (config, tool, chat.message, chat.params, event, tool.execute.before/after, experimental.chat.messages.transform) — full lifecycle control
  • Claude Code's hook points — more limited, focused on safety
  • What OMO features are possible on Claude Code today vs. what requires API changes
  • The "message transform" gap: why context injection is harder on Claude Code

• 26.3 Architecture Blueprint: Oh-My-Claude-Code

  • Multi-agent orchestration via custom agents + AgentTool
  • Background task delegation via TaskCreate/TaskGet/TaskOutput
  • Skill system leveraging Claude Code's native skills + MCP
  • Configuration via CLAUDE.md + .claude/settings.json
  • The "Sisyphus prompt" approach: encoding orchestration logic in system prompts
  • Wisdom accumulation via memory system + structured notes

• 26.4 What's Achievable Today: A Practical Implementation Plan

  • Phase 1: Custom agents with specialized prompts (Oracle, Explore, Librarian equivalents)
  • Phase 2: Hook-based continuation (post_sampling → todo enforcement)
  • Phase 3: MCP-based tool augmentation (AST-grep, session management, LSP extensions)
  • Phase 4: Plugin-based orchestration layer
  • Estimated effort and token cost implications

• 26.5 What's Missing: An Open Letter to Claude Code's Extensibility

  • The chat.message hook: intercepting and transforming messages before LLM
  • The tool.execute.before/after hooks: pre/post tool interception
  • Plugin-level tool registration: adding tools beyond MCP
  • Agent-level model selection: choosing different models for different agents
  • Background agent spawning with session continuity
  • The case for a richer plugin SDK

• 26.6 Convergence Forecast: Will OpenCode and Claude Code Plugin APIs Merge?

  • MCP as the common denominator
  • The trend toward richer hook systems
  • Open-source innovation driving commercial feature adoption
  • A unified agent extensibility standard: is it possible?

Appendices

Appendix A: Complete Tool Inventory of All Three Systems

• Full tool list with parameters, permissions, and descriptions for OpenCode, OMO, and Claude Code

Appendix B: Complete Configuration Reference

• Configuration schemas and options for all three systems

Appendix C: Key Source Code Path Mapping

• Quick reference table mapping concepts to source files across all three codebases

Appendix D: MCP Server Ecosystem Overview

• Transport types, community servers, official registry

Appendix E: Recommended Reading & References

• Anthropic: Building Effective Agents (Dec 2024)
• Anthropic: Effective Context Engineering (Sept 2025)
• Anthropic: Claude Code Sandboxing (Oct 2025)
• Anthropic: Multi-Agent Research System (June 2025)
• MCP Official Documentation
• Zylos: AI Coding Agents 2025–2026
• Zylos: Plugin and Extension Architecture
• GuruSup: Agent Orchestration Patterns
• SWE-bench & SWE-bench Pro benchmarks

Appendix F: Glossary of Terms

• LLM, Token, Context Window, Function Calling, ReAct, Agent, MCP, ACP, A2A, LSP, AST, SSE, Monorepo, TUI, Poka-yoke, ACI, JSONL, Zod, etc.

Source Code File Index

Quick reference for key source files covered in this book