# 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 [中文版本](/readme-zh.md) ## 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**](/en/chapter_01_ai_programming_assistant_background/1.1_from_auto-completion_to_agentic_coding.md) * [**1.2 AI Programming Assistant Product Landscape**](/en/chapter_01_ai_programming_assistant_background/1.2_ai_programming_assistant_product_landscape.md) * [**1.3 OpenCode's Positioning and Design Philosophy**](/en/chapter_01_ai_programming_assistant_background/1.3_opencode_positioning_and_design_philosophy.md) *** ### 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**](/en/chapter_02_project_structure_and_development_environment/2.1_obtaining_source_code_and_environment_setup.md) * [**2.2 Monorepo Structure Analysis**](/en/chapter_02_project_structure_and_development_environment/2.2_monorepo_structure_analysis.md) * [**2.3 Core Package `packages/opencode/src/` Module Map**](/en/chapter_02_project_structure_and_development_environment/2.3_core_package_module_map.md) *** ### Chapter 3: Overall Architecture Design > Understanding OpenCode's architectural layers and data flow from a global perspective. * [**3.1 Client-Server Architecture**](/en/chapter_03_overall_architecture_design/3.1_client-server_architecture.md) * [**3.2 Core Data Flow: From User Input to AI Response**](/en/chapter_03_overall_architecture_design/3.2_core_data_flow.md) * [**3.3 Multi-Project and Multi-Worktree Support**](/en/chapter_03_overall_architecture_design/3.3_multi-project_and_multi-worktree_support.md) * [**3.4 Layered Configuration System Design**](/en/chapter_03_overall_architecture_design/3.4_layered_configuration_system_design.md) *** ## 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**](/en/chapter_04_session_system/4.1_session_data_model.md) * [**4.2 Message Model**](/en/chapter_04_session_system/4.2_message_model.md) * [**4.3 SessionPrompt: The Session Entry Point**](/en/chapter_04_session_system/4.3_sessionprompt_entry_point.md) * [**4.4 SessionProcessor: The Core of the Agentic Loop**](/en/chapter_04_session_system/4.4_sessionprocessor_core_loop.md) * [**4.5 Compaction: Context Window Management**](/en/chapter_04_session_system/4.5_compaction_context_window_management.md) * [**4.6 Session State Management**](/en/chapter_04_session_system/4.6_session_state_management.md) *** ### Chapter 5: Tool System > Tools are the only way Agents interact with the external world. * [**5.1 Tool Abstraction Layer Design**](/en/chapter_05_tool_system/5.1_tool_abstraction_layer_design.md) * [**5.2 ToolRegistry: Registration and Discovery**](/en/chapter_05_tool_system/5.2_toolregistry_registration_and_discovery.md) * [**5.3 Built-in Tools Source Code Analysis**](/en/chapter_05_tool_system/5.3_built-in_tools_source_code_analysis.md) * [**5.4 Permission Checks in Tool Invocations**](/en/chapter_05_tool_system/5.4_permission_checks_in_tool_invocations.md) *** ### Chapter 6: Agent System > An Agent is the abstraction that gives an LLM its "personality" and "capability boundaries." * [**6.1 Agent Data Model**](/en/chapter_06_agent_system/6.1_agent_data_model.md) * [**6.2 Built-in Agent: build**](/en/chapter_06_agent_system/6.2_built-in_agent_build.md) * [**6.3 Agent Auxiliary Functions**](/en/chapter_06_agent_system/6.3_agent_auxiliary_functions.md) * [**6.4 System Prompt Architecture**](/en/chapter_06_agent_system/6.4_system_prompt_architecture.md) * [**6.5 Custom Agent Configuration**](/en/chapter_06_agent_system/6.5_custom_agent_configuration.md) *** ### Chapter 7: Provider (Multi-Model Adaptation Layer) > Understanding how OpenCode uniformly interfaces with 20+ LLM Providers. * [**7.1 Vercel AI SDK Integration**](/en/chapter_07_provider_multi_model_adaptation_layer/7.1_vercel_ai_sdk_integration.md) * [**7.2 Provider Registration and Resolution**](/en/chapter_07_provider_multi_model_adaptation_layer/7.2_provider_registration_and_resolution.md) * [**7.3 Model Metadata System**](/en/chapter_07_provider_multi_model_adaptation_layer/7.3_model_metadata_system.md) * [**7.4 ProviderTransform: Differentiated Model Adaptation**](/en/chapter_07_provider_multi_model_adaptation_layer/7.4_providertransform_differentiated_adaptation.md) * [**7.5 LLM Module: Streaming Call Implementation**](/en/chapter_07_provider_multi_model_adaptation_layer/7.5_llm_module_streaming_call_implementation.md) *** ### Chapter 8: MCP (Model Context Protocol) > MCP is the core protocol for OpenCode to connect with external tool ecosystems. * [**8.1 MCP Protocol Introduction**](/en/chapter_08_mcp/8.1_mcp_protocol_introduction.md) * [**8.2 MCP Client Implementation**](/en/chapter_08_mcp/8.2_mcp_client_implementation.md) * [**8.3 MCP OAuth Authentication**](/en/chapter_08_mcp/8.3_mcp_oauth_authentication.md) * [**8.4 MCP Configuration**](/en/chapter_08_mcp/8.4_mcp_configuration.md) *** ## 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**](/en/chapter_09_permission_control_system/9.1_permission_model_design.md) * [**9.2 Permission Evaluation Engine**](/en/chapter_09_permission_control_system/9.2_permission_evaluation_engine.md) * [**9.3 Permission Configuration Hierarchy**](/en/chapter_09_permission_control_system/9.3_permission_configuration_hierarchy.md) * [**9.4 Permission Request Interaction Flow**](/en/chapter_09_permission_control_system/9.4_permission_request_interaction_flow.md) * [**9.5 Permission Strategies for Each Tool**](/en/chapter_09_permission_control_system/9.5_permission_strategies_for_each_tool.md) *** ### Chapter 10: Snapshot and File System > Understanding how OpenCode safely manages file changes and rollbacks. * [**10.1 Git Snapshot System**](/en/chapter_10_snapshot_and_file_system/10.1_git_snapshot_system.md) * [**10.2 File System Tools**](/en/chapter_10_snapshot_and_file_system/10.2_file_system_tools.md) * [**10.3 Patch System**](/en/chapter_10_snapshot_and_file_system/10.3_patch_system.md) * [**10.4 Worktree Management**](/en/chapter_10_snapshot_and_file_system/10.4_worktree_management.md) *** ### Chapter 11: Event Bus and Scheduler > Understanding the core mechanism for decoupled inter-module communication. * [**11.1 Event Bus**](/en/chapter_11_event_bus_and_scheduler/11.1_event_bus.md) * [**11.2 Key Event List**](/en/chapter_11_event_bus_and_scheduler/11.2_key_event_list.md) * [**11.3 Scheduler: Timed Task Scheduling**](/en/chapter_11_event_bus_and_scheduler/11.3_scheduler_timed_task_scheduling.md) *** ### Chapter 12: Command Line Interface and TUI > Understanding OpenCode's frontend implementation from a user interaction perspective. * [**12.1 CLI Startup Flow**](/en/chapter_12_cli_and_tui/12.1_cli_startup_flow.md) * [**12.2 TUI Implementation**](/en/chapter_12_cli_and_tui/12.2_tui_implementation.md) * [**12.3 Web UI**](/en/chapter_12_cli_and_tui/12.3_web_ui.md) * [**12.4 Non-Interactive Mode**](/en/chapter_12_cli_and_tui/12.4_non-interactive_mode.md) *** ## Part IV: Ecosystem ### Chapter 13: Plugin System > Understanding the core of OpenCode's extensibility — the Plugin architecture. * [**13.1 Plugin Interface Definition**](/en/chapter_13_plugin_system/13.1_plugin_interface_definition.md) * [**13.2 Plugin Lifecycle Hooks**](/en/chapter_13_plugin_system/13.2_plugin_lifecycle_hooks.md) * [**13.3 Plugin Loading Mechanism**](/en/chapter_13_plugin_system/13.3_plugin_loading_mechanism.md) * [**13.4 OpenCode SDK**](/en/chapter_13_plugin_system/13.4_opencode_sdk.md) *** ### Chapter 14: Skill System > Skills are modular extension units for Agent capabilities. * [**14.1 Skill Definition and Structure**](/en/chapter_14_skill_system/14.1_skill_definition_and_structure.md) * [**14.2 Skill Loading Flow**](/en/chapter_14_skill_system/14.2_skill_loading_flow.md) * [**14.3 Command System**](/en/chapter_14_skill_system/14.3_command_system.md) *** ### 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**](/en/chapter_15_oh-my-opencode_deep_dive/15.1_project_overview_and_architecture.md) * [**15.2 Plugin Entry Point and Initialization**](/en/chapter_15_oh-my-opencode_deep_dive/15.2_plugin_entry_point_and_initialization.md) * [**15.3 Multi-Agent System**](/en/chapter_15_oh-my-opencode_deep_dive/15.3_multi-agent_system.md) * [**15.4 Custom Tool System**](/en/chapter_15_oh-my-opencode_deep_dive/15.4_custom_tool_system.md) * [**15.5 Hook System (53 Hooks Explained)**](/en/chapter_15_oh-my-opencode_deep_dive/15.5_hook_system.md) * [**15.6 Feature Modules**](/en/chapter_15_oh-my-opencode_deep_dive/15.6_feature_modules.md) * [**15.7 Plugin Interface Implementation**](/en/chapter_15_oh-my-opencode_deep_dive/15.7_plugin_interface_implementation.md) * [**15.8 Embedded MCP Services**](/en/chapter_15_oh-my-opencode_deep_dive/15.8_embedded_mcp_services.md) *** ### Chapter 16: IDE Extensions and ACP > Understanding how OpenCode integrates with various IDEs. * [**16.1 VSCode Extension**](/en/chapter_16_ide_extensions_and_acp/16.1_vscode_extension_implementation.md) * [**16.2 Zed Extension**](/en/chapter_16_ide_extensions_and_acp/16.2_zed_extension_implementation.md) * [**16.3 ACP (Agent Client Protocol)**](/en/chapter_16_ide_extensions_and_acp/16.3_acp_protocol_deep_analysis.md) *** ## 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**](/en/chapter_17_hands-on_labs/17.1_lab1_llm_cli_chat_tool.md) * [**17.2 Lab 2: Adding Tool Use Capability to the CLI Tool**](/en/chapter_17_hands-on_labs/17.2_lab2_tool_use_capability.md) * [**17.3 Lab 3: Building an MCP Server**](/en/chapter_17_hands-on_labs/17.3_lab3_building_mcp_server.md) * [**17.4 Lab 4: Writing an OpenCode Plugin**](/en/chapter_17_hands-on_labs/17.4_lab4_writing_opencode_plugin.md) * [**17.5 Lab 5: Building a Simplified Multi-Agent Orchestration System**](/en/chapter_17_hands-on_labs/17.5_lab5_simplified_multi-agent_orchestration_system.md) *** ### 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**](/en/chapter_18_design_philosophy_and_best_practices/18.1_review_of_opencode_key_design_decisions.md) * [**18.2 Design Insights from oh-my-opencode**](/en/chapter_18_design_philosophy_and_best_practices/18.2_design_insights_from_oh-my-opencode.md) * [**18.3 Best Practices for Building AI Programming Assistants**](/en/chapter_18_design_philosophy_and_best_practices/18.3_best_practices_for_building_ai_programming_assistants.md) * [**18.4 Future Outlook**](/en/chapter_18_design_philosophy_and_best_practices/18.4_future_outlook.md) *** ## 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/` | --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://www.opencodebook.xyz/readme.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.