# Deep Dive into OpenCode — Table of Contents and Outline > **Model**: claude-opus-4-6 (anthropic/claude-opus-4-6) **Tools**: OpenCode **Generated**: 2025-02-17 **GitHub**: *** ## Language [中文版本](https://www.opencodebook.xyz/readme-zh) ## Book Structure Overview As of OpenCode version 1.2.5. This book is divided into **five parts and eighteen chapters**, systematically covering OpenCode's architecture design and implementation principles — from foundational concepts to source code analysis, from core mechanisms to ecosystem extensions, and from theory to practice. | Part | Chapter Range | Core Topics | Est. Word Count | | -------------------------- | -------------- | ------------------------------------------------- | --------------- | | Part I: Foundations | Chapters 1–3 | Background, Setup, Overall Architecture | \~15,000 words | | Part II: Core Architecture | Chapters 4–8 | Session, Tool, Agent, Provider, MCP | \~30,000 words | | Part III: Key Mechanisms | Chapters 9–12 | Permissions, Snapshot, Event Bus, TUI | \~20,000 words | | Part IV: Ecosystem | Chapters 13–16 | Plugin System, oh-my-opencode, IDE Extensions | \~20,000 words | | Part V: Practice | Chapters 17–18 | Hands-on Labs, Design Philosophy & Future Outlook | \~15,000 words | *** ## Part I: Foundations ### Chapter 1: The Era of AI Programming Assistants > Guiding readers to understand the technical background and industry context behind OpenCode's creation. * [**1.1 From Auto-Completion to Agentic Coding**](https://www.opencodebook.xyz/en/chapter_01_ai_programming_assistant_background/1.1_from_auto-completion_to_agentic_coding) * [**1.2 AI Programming Assistant Product Landscape**](https://www.opencodebook.xyz/en/chapter_01_ai_programming_assistant_background/1.2_ai_programming_assistant_product_landscape) * [**1.3 OpenCode's Positioning and Design Philosophy**](https://www.opencodebook.xyz/en/chapter_01_ai_programming_assistant_background/1.3_opencode_positioning_and_design_philosophy) *** ### Chapter 2: Project Structure and Development Environment > Setting up the development environment and building a macro-level understanding of the project structure. * [**2.1 Obtaining Source Code and Environment Setup**](https://www.opencodebook.xyz/en/chapter_02_project_structure_and_development_environment/2.1_obtaining_source_code_and_environment_setup) * [**2.2 Monorepo Structure Analysis**](https://www.opencodebook.xyz/en/chapter_02_project_structure_and_development_environment/2.2_monorepo_structure_analysis) * [**2.3 Core Package `packages/opencode/src/` Module Map**](https://www.opencodebook.xyz/en/chapter_02_project_structure_and_development_environment/2.3_core_package_module_map) *** ### Chapter 3: Overall Architecture Design > Understanding OpenCode's architectural layers and data flow from a global perspective. * [**3.1 Client-Server Architecture**](https://www.opencodebook.xyz/en/chapter_03_overall_architecture_design/3.1_client-server_architecture) * [**3.2 Core Data Flow: From User Input to AI Response**](https://www.opencodebook.xyz/en/chapter_03_overall_architecture_design/3.2_core_data_flow) * [**3.3 Multi-Project and Multi-Worktree Support**](https://www.opencodebook.xyz/en/chapter_03_overall_architecture_design/3.3_multi-project_and_multi-worktree_support) * [**3.4 Layered Configuration System Design**](https://www.opencodebook.xyz/en/chapter_03_overall_architecture_design/3.4_layered_configuration_system_design) *** ## Part II: Core Architecture ### Chapter 4: Session System > The session is OpenCode's core abstraction — understanding it means understanding the entire conversation management mechanism. * [**4.1 Session Data Model**](https://www.opencodebook.xyz/en/chapter_04_session_system/4.1_session_data_model) * [**4.2 Message Model**](https://www.opencodebook.xyz/en/chapter_04_session_system/4.2_message_model) * [**4.3 SessionPrompt: The Session Entry Point**](https://www.opencodebook.xyz/en/chapter_04_session_system/4.3_sessionprompt_entry_point) * [**4.4 SessionProcessor: The Core of the Agentic Loop**](https://www.opencodebook.xyz/en/chapter_04_session_system/4.4_sessionprocessor_core_loop) * [**4.5 Compaction: Context Window Management**](https://www.opencodebook.xyz/en/chapter_04_session_system/4.5_compaction_context_window_management) * [**4.6 Session State Management**](https://www.opencodebook.xyz/en/chapter_04_session_system/4.6_session_state_management) *** ### Chapter 5: Tool System > Tools are the only way Agents interact with the external world. * [**5.1 Tool Abstraction Layer Design**](https://www.opencodebook.xyz/en/chapter_05_tool_system/5.1_tool_abstraction_layer_design) * [**5.2 ToolRegistry: Registration and Discovery**](https://www.opencodebook.xyz/en/chapter_05_tool_system/5.2_toolregistry_registration_and_discovery) * [**5.3 Built-in Tools Source Code Analysis**](https://www.opencodebook.xyz/en/chapter_05_tool_system/5.3_built-in_tools_source_code_analysis) * [**5.4 Permission Checks in Tool Invocations**](https://www.opencodebook.xyz/en/chapter_05_tool_system/5.4_permission_checks_in_tool_invocations) *** ### Chapter 6: Agent System > An Agent is the abstraction that gives an LLM its "personality" and "capability boundaries." * [**6.1 Agent Data Model**](https://www.opencodebook.xyz/en/chapter_06_agent_system/6.1_agent_data_model) * [**6.2 Built-in Agent: build**](https://www.opencodebook.xyz/en/chapter_06_agent_system/6.2_built-in_agent_build) * [**6.3 Agent Auxiliary Functions**](https://www.opencodebook.xyz/en/chapter_06_agent_system/6.3_agent_auxiliary_functions) * [**6.4 System Prompt Architecture**](https://www.opencodebook.xyz/en/chapter_06_agent_system/6.4_system_prompt_architecture) * [**6.5 Custom Agent Configuration**](https://www.opencodebook.xyz/en/chapter_06_agent_system/6.5_custom_agent_configuration) *** ### Chapter 7: Provider (Multi-Model Adaptation Layer) > Understanding how OpenCode uniformly interfaces with 20+ LLM Providers. * [**7.1 Vercel AI SDK Integration**](https://www.opencodebook.xyz/en/chapter_07_provider_multi_model_adaptation_layer/7.1_vercel_ai_sdk_integration) * [**7.2 Provider Registration and Resolution**](https://www.opencodebook.xyz/en/chapter_07_provider_multi_model_adaptation_layer/7.2_provider_registration_and_resolution) * [**7.3 Model Metadata System**](https://www.opencodebook.xyz/en/chapter_07_provider_multi_model_adaptation_layer/7.3_model_metadata_system) * [**7.4 ProviderTransform: Differentiated Model Adaptation**](https://www.opencodebook.xyz/en/chapter_07_provider_multi_model_adaptation_layer/7.4_providertransform_differentiated_adaptation) * [**7.5 LLM Module: Streaming Call Implementation**](https://www.opencodebook.xyz/en/chapter_07_provider_multi_model_adaptation_layer/7.5_llm_module_streaming_call_implementation) *** ### Chapter 8: MCP (Model Context Protocol) > MCP is the core protocol for OpenCode to connect with external tool ecosystems. * [**8.1 MCP Protocol Introduction**](https://www.opencodebook.xyz/en/chapter_08_mcp/8.1_mcp_protocol_introduction) * [**8.2 MCP Client Implementation**](https://www.opencodebook.xyz/en/chapter_08_mcp/8.2_mcp_client_implementation) * [**8.3 MCP OAuth Authentication**](https://www.opencodebook.xyz/en/chapter_08_mcp/8.3_mcp_oauth_authentication) * [**8.4 MCP Configuration**](https://www.opencodebook.xyz/en/chapter_08_mcp/8.4_mcp_configuration) *** ## Part III: Key Mechanisms ### Chapter 9: Permission Control System > Security is the lifeline of AI Agents — deeply understanding how OpenCode controls Agent behavior boundaries. * [**9.1 Permission Model Design**](https://www.opencodebook.xyz/en/chapter_09_permission_control_system/9.1_permission_model_design) * [**9.2 Permission Evaluation Engine**](https://www.opencodebook.xyz/en/chapter_09_permission_control_system/9.2_permission_evaluation_engine) * [**9.3 Permission Configuration Hierarchy**](https://www.opencodebook.xyz/en/chapter_09_permission_control_system/9.3_permission_configuration_hierarchy) * [**9.4 Permission Request Interaction Flow**](https://www.opencodebook.xyz/en/chapter_09_permission_control_system/9.4_permission_request_interaction_flow) * [**9.5 Permission Strategies for Each Tool**](https://www.opencodebook.xyz/en/chapter_09_permission_control_system/9.5_permission_strategies_for_each_tool) *** ### Chapter 10: Snapshot and File System > Understanding how OpenCode safely manages file changes and rollbacks. * [**10.1 Git Snapshot System**](https://www.opencodebook.xyz/en/chapter_10_snapshot_and_file_system/10.1_git_snapshot_system) * [**10.2 File System Tools**](https://www.opencodebook.xyz/en/chapter_10_snapshot_and_file_system/10.2_file_system_tools) * [**10.3 Patch System**](https://www.opencodebook.xyz/en/chapter_10_snapshot_and_file_system/10.3_patch_system) * [**10.4 Worktree Management**](https://www.opencodebook.xyz/en/chapter_10_snapshot_and_file_system/10.4_worktree_management) *** ### Chapter 11: Event Bus and Scheduler > Understanding the core mechanism for decoupled inter-module communication. * [**11.1 Event Bus**](https://www.opencodebook.xyz/en/chapter_11_event_bus_and_scheduler/11.1_event_bus) * [**11.2 Key Event List**](https://www.opencodebook.xyz/en/chapter_11_event_bus_and_scheduler/11.2_key_event_list) * [**11.3 Scheduler: Timed Task Scheduling**](https://www.opencodebook.xyz/en/chapter_11_event_bus_and_scheduler/11.3_scheduler_timed_task_scheduling) *** ### Chapter 12: Command Line Interface and TUI > Understanding OpenCode's frontend implementation from a user interaction perspective. * [**12.1 CLI Startup Flow**](https://www.opencodebook.xyz/en/chapter_12_cli_and_tui/12.1_cli_startup_flow) * [**12.2 TUI Implementation**](https://www.opencodebook.xyz/en/chapter_12_cli_and_tui/12.2_tui_implementation) * [**12.3 Web UI**](https://www.opencodebook.xyz/en/chapter_12_cli_and_tui/12.3_web_ui) * [**12.4 Non-Interactive Mode**](https://www.opencodebook.xyz/en/chapter_12_cli_and_tui/12.4_non-interactive_mode) *** ## Part IV: Ecosystem ### Chapter 13: Plugin System > Understanding the core of OpenCode's extensibility — the Plugin architecture. * [**13.1 Plugin Interface Definition**](https://www.opencodebook.xyz/en/chapter_13_plugin_system/13.1_plugin_interface_definition) * [**13.2 Plugin Lifecycle Hooks**](https://www.opencodebook.xyz/en/chapter_13_plugin_system/13.2_plugin_lifecycle_hooks) * [**13.3 Plugin Loading Mechanism**](https://www.opencodebook.xyz/en/chapter_13_plugin_system/13.3_plugin_loading_mechanism) * [**13.4 OpenCode SDK**](https://www.opencodebook.xyz/en/chapter_13_plugin_system/13.4_opencode_sdk) *** ### Chapter 14: Skill System > Skills are modular extension units for Agent capabilities. * [**14.1 Skill Definition and Structure**](https://www.opencodebook.xyz/en/chapter_14_skill_system/14.1_skill_definition_and_structure) * [**14.2 Skill Loading Flow**](https://www.opencodebook.xyz/en/chapter_14_skill_system/14.2_skill_loading_flow) * [**14.3 Command System**](https://www.opencodebook.xyz/en/chapter_14_skill_system/14.3_command_system) *** ### Chapter 15: oh-my-opencode Deep Dive > As the most complex third-party Plugin in the OpenCode ecosystem, oh-my-opencode demonstrates the full power of the Plugin system. * [**15.1 Project Overview and Architecture**](https://www.opencodebook.xyz/en/chapter_15_oh-my-opencode_deep_dive/15.1_project_overview_and_architecture) * [**15.2 Plugin Entry Point and Initialization**](https://www.opencodebook.xyz/en/chapter_15_oh-my-opencode_deep_dive/15.2_plugin_entry_point_and_initialization) * [**15.3 Multi-Agent System**](https://www.opencodebook.xyz/en/chapter_15_oh-my-opencode_deep_dive/15.3_multi-agent_system) * [**15.4 Custom Tool System**](https://www.opencodebook.xyz/en/chapter_15_oh-my-opencode_deep_dive/15.4_custom_tool_system) * [**15.5 Hook System (53 Hooks Explained)**](https://www.opencodebook.xyz/en/chapter_15_oh-my-opencode_deep_dive/15.5_hook_system) * [**15.6 Feature Modules**](https://www.opencodebook.xyz/en/chapter_15_oh-my-opencode_deep_dive/15.6_feature_modules) * [**15.7 Plugin Interface Implementation**](https://www.opencodebook.xyz/en/chapter_15_oh-my-opencode_deep_dive/15.7_plugin_interface_implementation) * [**15.8 Embedded MCP Services**](https://www.opencodebook.xyz/en/chapter_15_oh-my-opencode_deep_dive/15.8_embedded_mcp_services) *** ### Chapter 16: IDE Extensions and ACP > Understanding how OpenCode integrates with various IDEs. * [**16.1 VSCode Extension**](https://www.opencodebook.xyz/en/chapter_16_ide_extensions_and_acp/16.1_vscode_extension_implementation) * [**16.2 Zed Extension**](https://www.opencodebook.xyz/en/chapter_16_ide_extensions_and_acp/16.2_zed_extension_implementation) * [**16.3 ACP (Agent Client Protocol)**](https://www.opencodebook.xyz/en/chapter_16_ide_extensions_and_acp/16.3_acp_protocol_deep_analysis) *** ## Part V: Practice ### Chapter 17: Hands-on Labs > Through five progressive experiments, build key components of an AI programming assistant from scratch. * [**17.1 Lab 1: Implementing a Simple LLM CLI Chat Tool**](https://www.opencodebook.xyz/en/chapter_17_hands-on_labs/17.1_lab1_llm_cli_chat_tool) * [**17.2 Lab 2: Adding Tool Use Capability to the CLI Tool**](https://www.opencodebook.xyz/en/chapter_17_hands-on_labs/17.2_lab2_tool_use_capability) * [**17.3 Lab 3: Building an MCP Server**](https://www.opencodebook.xyz/en/chapter_17_hands-on_labs/17.3_lab3_building_mcp_server) * [**17.4 Lab 4: Writing an OpenCode Plugin**](https://www.opencodebook.xyz/en/chapter_17_hands-on_labs/17.4_lab4_writing_opencode_plugin) * [**17.5 Lab 5: Building a Simplified Multi-Agent Orchestration System**](https://www.opencodebook.xyz/en/chapter_17_hands-on_labs/17.5_lab5_simplified_multi-agent_orchestration_system) *** ### Chapter 18: Design Philosophy, Best Practices, and Future Outlook > Summarizing the entire book, distilling design wisdom, and looking ahead to future directions. * [**18.1 Review of OpenCode's Key Design Decisions**](https://www.opencodebook.xyz/en/chapter_18_design_philosophy_and_best_practices/18.1_review_of_opencode_key_design_decisions) * [**18.2 Design Insights from oh-my-opencode**](https://www.opencodebook.xyz/en/chapter_18_design_philosophy_and_best_practices/18.2_design_insights_from_oh-my-opencode) * [**18.3 Best Practices for Building AI Programming Assistants**](https://www.opencodebook.xyz/en/chapter_18_design_philosophy_and_best_practices/18.3_best_practices_for_building_ai_programming_assistants) * [**18.4 Future Outlook**](https://www.opencodebook.xyz/en/chapter_18_design_philosophy_and_best_practices/18.4_future_outlook) *** ## Appendices ### Appendix A: OpenCode Configuration Reference Manual * Complete list and description of `opencode.json` configuration options ### Appendix B: oh-my-opencode Configuration Reference Manual * Complete list and description of `oh-my-opencode.json` configuration options ### Appendix C: Built-in Tool API Reference * Parameters, return values, and permission requirements for each built-in tool ### Appendix D: MCP Protocol Quick Reference * Core concepts, transport methods, message formats ### Appendix E: Glossary * Definitions of terms: LLM, Token, Context Window, Function Calling, Agent, MCP, ACP, LSP, AST, SSE, Monorepo, TUI, etc. ### Appendix F: Recommended Reading and Resources * Official documentation links * Related papers and articles * Recommended open-source projects *** ## Source Code File Index > Quick reference table for key source code files covered in this book | Chapter | Key Files | | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Chapter 4: Session | `session/index.ts`, `session/processor.ts`, `session/llm.ts`, `session/compaction.ts`, `session/system.ts`, `session/instruction.ts`, `session/prompt.ts`, `session/message-v2.ts`, `session/retry.ts`, `session/revert.ts`, `session/status.ts`, `session/summary.ts`, `session/todo.ts` | | Chapter 5: Tool | `tool/tool.ts`, `tool/registry.ts`, `tool/truncation.ts`, `tool/bash.ts`, `tool/edit.ts`, `tool/read.ts`, `tool/write.ts`, `tool/glob.ts`, `tool/grep.ts`, `tool/task.ts`, `tool/lsp.ts`, `tool/webfetch.ts`, `tool/websearch.ts`, `tool/todo.ts`, `tool/skill.ts`, `tool/plan.ts`, `tool/batch.ts`, `tool/question.ts`, `tool/apply_patch.ts`, `tool/multiedit.ts`, `tool/codesearch.ts` | | Chapter 6: Agent | `agent/agent.ts`, `agent/prompt/*.txt`, `session/prompt/*.txt` | | Chapter 7: Provider | `provider/provider.ts`, `provider/transform.ts`, `provider/models.ts`, `provider/auth.ts`, `provider/error.ts`, `provider/sdk/copilot/` | | Chapter 8: MCP | `mcp/index.ts`, `mcp/auth.ts`, `mcp/oauth-provider.ts`, `mcp/oauth-callback.ts` | | Chapter 9: Permission | `permission/next.ts`, `permission/index.ts`, `permission/arity.ts` | | Chapter 10: Snapshot | `snapshot/index.ts`, `file/index.ts`, `file/ignore.ts`, `file/ripgrep.ts`, `file/watcher.ts`, `patch/index.ts`, `worktree/index.ts` | | Chapter 11: Bus | `bus/index.ts`, `bus/bus-event.ts`, `bus/global.ts`, `scheduler/index.ts` | | Chapter 12: CLI/TUI | `cli/bootstrap.ts`, `cli/cmd/*.ts`, `cli/cmd/tui/app.tsx`, `cli/cmd/tui/component/`, `cli/cmd/tui/routes/` | | Chapter 13: Plugin | `plugin/index.ts`, `plugin/codex.ts`, `plugin/copilot.ts` | | Chapter 14: Skill | `skill/index.ts`, `skill/skill.ts`, `skill/discovery.ts`, `command/index.ts` | | Chapter 15: oh-my-opencode | `oh-my-opencode/src/index.ts`, `agents/*.ts`, `tools/*`, `hooks/*`, `features/*`, `plugin/*`, `mcp/*`, `config/*` | | Chapter 16: IDE/ACP | `acp/agent.ts`, `acp/session.ts`, `acp/types.ts`, `sdks/vscode/`, `extensions/zed/` |