BMAD-METHOD/discovery-docs/opencode-architecture-deep-dive.md

# opencode Core Architecture Deep Dive

This document provides a comprehensive overview of the foundational elements of the `opencode` architecture, based on a detailed examination of its codebase.

## Core Philosophies and Goals:

The core philosophies behind `opencode` revolve around empowering developers with an **AI coding agent built for the terminal**, emphasizing **extensibility, configurability, and a structured approach to AI interaction**.

### What `opencode` Set Out to Do:

1.  **AI-Powered Developer Augmentation:** Provide an intelligent assistant that helps developers with coding tasks directly within their terminal environment.
2.  **Extensibility and Customization:** Be highly adaptable, allowing users to extend its capabilities and tailor its behavior to specific project needs and preferences.
3.  **Structured and Reliable AI Interaction:** Make AI interactions predictable and manageable through clear definitions of agents, tools, and sessions, along with robust error handling and validation.
4.  **Transparency and Observability:** Provide insights into the AI's decision-making process and tool execution.

### How `opencode` Accomplished Its Goals:

1.  **Agent-Centric Architecture:**
    - **Configurable Agents:** Defines agents with distinct roles, permissions, and toolsets (`Agent.Info` schema), allowing for specialized AI behaviors.
    - **Agent Generation:** The `Agent.generate` function, guided by a meta-prompt (`generate.txt`), enables the AI to create new agent configurations based on user descriptions.

2.  **Tool-Driven Capabilities:**
    - **Comprehensive Toolset:** Provides a rich set of built-in tools for common developer tasks (e.g., `bash`, `edit`, `read`, `write`, `glob`, `grep`, `webfetch`).
    - **Extensible Tool Registry:** The `ToolRegistry` allows for dynamic registration of new tools through plugins (`EXTRA` tools) and HTTP callbacks (`HTTP` tools).
    - **Structured Tool Definition:** Tools adhere to the `Tool.Info` interface, ensuring clear descriptions, `zod`-validated parameters, and a standardized `execute` method.

3.  **Session-Based Context Management:**
    - **Persistent Sessions:** Manages persistent sessions (`Session.Info`) that maintain conversation history, tool outputs, and project context.
    - **Message Structure:** Messages are highly structured (`MessageV2.Info` and `MessageV2.Part`s), supporting various content types (text, reasoning, tool calls, file changes, snapshots).
    - **Context Pruning:** The `prune` function helps manage token limits by compacting old tool outputs.

4.  **API-First Design:**
    - **Hono-based Server:** A robust HTTP API exposes all core functionalities, making `opencode` programmable and allowing for diverse frontend integrations.

5.  **Dynamic Prompt Orchestration:**
    - **Context Assembly:** Dynamically constructs system prompts by combining provider-specific headers, model-specific instructions, environmental context, and custom rule files.
    - **Workflow Automation:** The `command` function enables command-driven workflows, processing templates, handling file/agent references, and invoking subagents.

6.  **Developer-Friendly Interfaces:**
    - **Terminal User Interface (TUI):** A Go-based TUI provides a terminal-native experience.
    - **Web Application:** A React/TypeScript web app (`packages/app/`) offers a modern, interactive interface.

---

## 1. Agents (`packages/opencode/src/agent/agent.ts`)

- **Definition:** Agents are configured via a `zod` schema (`Agent.Info`), specifying `name`, `description`, `mode` (`subagent`, `primary`, `all`), `permissions` (for `edit`, `bash`, `webfetch`), `model` (provider and ID), `prompt`, and `tools` (enabled/disabled).
- **Configuration:** Agent configurations are loaded from `Config.get()` and managed via `Instance.state`. Built-in agents (`general`, `build`, `plan`) are provided, and users can define/override configurations.
- **Generation:** The `Agent.generate` function uses a meta-prompt (`generate.txt`) to create new agent configurations based on descriptions.
- **Invocation:** Agent invocation is primarily driven by the AI model's decision-making based on the system prompt and available tools. The `mode` property influences orchestration.
- **Purpose:** Agents are specialized AI assistants configured for specific tasks and workflows, allowing for focused tools with custom prompts, models, and tool access.
- **Configuration Details:** Configured in `opencode.json` or through Markdown files. Options include `description`, `temperature`, `disable` status, `prompt` (custom system prompt), `model` (to override the default), and `tools` (to control tool availability).
- **Permissions:** Granular permissions for actions like `edit`, `bash`, and `webfetch` can be set to `allow`, `ask`, or `deny`, either globally or per agent, with granular control for bash commands.
- **Mode:** Agents have a `mode` (primary, subagent, or all) and can accept `additional` provider-specific model options.

## 2. Tools (`packages/opencode/src/tool/registry.ts` and `packages/opencode/src/tool/tool.ts`)

- **Registry:** `ToolRegistry` is the central point for managing tools.
- **Types:** Includes `BUILTIN` tools (e.g., `BashTool`, `EditTool`, `WebFetchTool`), `EXTRA` tools (runtime-registered via plugins), and `HTTP` tools (registered via HTTP callbacks for external services).
- **Definition:** Tools are defined using `Tool.define`, adhering to the `Tool.Info` interface, which specifies `id`, `description`, `parameters` (with `zod` schemas for validation), and an `execute` method.
- **Context:** The `Tool.Context` interface provides session, message, agent, and abort signal information to tools.
- **Permissions:** The `ToolRegistry.enabled()` function determines tool availability based on agent permissions.

## 3. Server API (`packages/opencode/src/server/server.ts`)

- **Framework:** Hono-based HTTP API.
- **Key Endpoints:**
  - `/experimental/tool/register`: Dynamic registration of HTTP callback tools.
  - `/experimental/tool/ids`, `/experimental/tool`: List available tools.
  - `/session/*`: Comprehensive session management (create, retrieve, update, delete, share, summarize, messages, prompts, commands, shell execution, revert, permissions).
  - `/config`, `/config/providers`: Configuration and AI provider/model lists.
  - `/file/*`: File system operations.
  - `/find/*`: Search functionalities.
  - `/agent`: List all agents.
  - `/tui/*`: TUI control endpoints.
  - `/auth/:id`: Authentication.

## 4. Session Management (`packages/opencode/src/session/index.ts`)

- **Structure:** Sessions are defined by `Session.Info` schema, including `id`, `projectID`, `directory`, `parentID`, `share` info, `title`, `version`, `time` (created, updated, compacting), and `revert` state.
- **Lifecycle:** Functions for `create`, `get`, `list`, `children`, `update`, `remove`, `share`, `unshare`, and `initialize`.
- **Message Handling:** Manages `MessageV2.Info` and `MessageV2.Part`s within sessions, including `updateMessage`, `removeMessage`, `updatePart`.
- **Pruning:** `prune` function compacts old tool outputs to manage token limits.
- **Usage:** `getUsage` tracks cost and token usage.

## 5. Message Structure (`packages/opencode/src/session/message-v2.ts`)

- **Errors:** Defines custom error types.
- **`ToolState`:** Tracks the `pending`, `running`, `completed`, or `error` state of tool executions.
- **`Part` Types:** A rich set of content types for messages: `SnapshotPart`, `PatchPart`, `TextPart`, `ReasoningPart`, `ToolPart`, `FilePart` (with `FileSource` or `SymbolSource`), `AgentPart`, `StepStartPart`, `StepFinishPart`.
- **`User` and `Assistant` Messages:** Distinct schemas for user and assistant messages, with assistant messages including detailed contextual information, cost, and token usage.
- **Events:** `MessageV2.Event` for real-time updates.
- **`MessageV2.WithParts`:** Combines message info with its parts.

## 6. Prompt Orchestration (`packages/opencode/src/session/prompt.ts`)

- **Core Function:** `prompt(input: PromptInput)` orchestrates AI interaction.
- **User Input:** Creates user messages, handling file references and converting them to AI-readable parts.
- **Concurrency:** Uses session locking and queuing.
- **Context Assembly:** Resolves agent, model, and constructs system prompts (`SystemPrompt.header`, `SystemPrompt.provider`, `SystemPrompt.environment`, `SystemPrompt.custom`).
- **Tool Integration:** Resolves and wraps tools, handling execution, state updates, and plugin triggers.
- **AI Interaction:** Uses `streamText` to interact with AI models.
- **Response Processing:** `createProcessor` handles streaming AI output, updating messages, tool states, and tracking steps/patches.
- **Direct Execution:** `shell` function for direct shell command execution.
- **Command Workflows:** `command` function executes predefined commands, processes templates, handles file/agent references, and can invoke subagents via `TaskTool`.
- **Dynamic Prompt Injection:** `insertReminders` injects synthetic prompts based on agent mode.
- **Session Title Generation:** `ensureTitle` generates session titles using a smaller AI model.

## 7. System Prompts (`packages/opencode/src/session/system.ts`)

- **Dynamic Construction:** Combines provider-specific headers, model-specific instructions, environmental context, and custom rule files (`AGENTS.md`, `CLAUDE.md`, `CONTEXT.md`, `config.instructions`).
- **Purpose:** Provides general instructions and context to AI models.
- **Rules Details:**
  - **Purpose:** `AGENTS.md` (similar to `CLAUDE.md` or Cursor's rules) provides custom instructions to the `opencode` AI agent, guiding its behavior by including these instructions in the LLM's context.
  - **Location and Precedence:** Rules can be project-specific (project root) or global (`~/.config/opencode/AGENTS.md`). `opencode` combines both sets, with project-specific rules taking precedence.
  - **Custom Instruction Files:** Additional instruction files can be specified in `opencode.json`, allowing for reuse and referencing external files for modular guidelines. The agent can also be instructed to reference external files for modular rule sets, either through `opencode.json` or by explicit instructions in `AGENTS.md` that prompt lazy loading of relevant files.

## 8. Project Instance (`packages/opencode/src/project/instance.ts`)

- **Context Management:** `Instance.state` and `Instance.provide` manage project-specific context, ensuring operations are performed within the correct project directory and worktree.

## 9. Configuration (`packages/opencode/src/config/config.ts`)

- **Loading and Validation:** Handles loading, validating, and applying configurations for agents, tools, and other `opencode` settings.
- **Configuration Management Details:**
  - **File Format:** `opencode` configuration is managed via JSON or JSONC files (supporting comments).
  - **File Locations and Precedence:**
    - **Global:** `~/.config/opencode/opencode.json`
    - **Per Project:** `opencode.json` in the project root.
    - **Environment Variable:** Can be specified via the `OPENCODE_CONFIG` environment variable (takes highest precedence).
  - **Key Configurable Aspects:**
    - Defining AI models and providers.
    - Setting UI themes.
    - Configuring specialized agents with custom prompts and tool permissions.
    - Creating custom commands.
    - Customizing keybinds.
    - Enabling/disabling autoupdate.
    - Configuring code formatters.
    - Managing granular permissions for AI agent actions (e.g., file editing, bash commands).
    - Specifying additional instructions for models.
  - **Advanced Configuration Features:**
    - Supports variable substitution for environment variables and file contents, which is particularly useful for managing sensitive data like API keys or incorporating large instruction sets.

## 10. Event Bus (`packages/opencode/src/bus/index.ts`)

- **Communication:** Provides a central mechanism for publishing and subscribing to events across different `opencode` components, enabling real-time updates and inter-component communication.

## 11. User Interfaces

- **Web Application (`packages/app/`):** React/TypeScript/Vite-based web UI.
- **Terminal User Interface (`packages/tui/`):** Go-based TUI.
- **Web Landing Page (`packages/web/`):** Astro-based web application.

## 12. Commands (from `https://opencode.ai/docs/commands/`)

- **Purpose:** Automate repetitive tasks, executed in the TUI by typing `/` followed by the command name.
- **Definition:** Can be defined in `opencode.jsonc` or as Markdown files in the `.opencode/command/` directory.
- **Structure:** Involves a template (the prompt sent to the LLM), an optional description, and optional specifications for the agent and model to be used.
- **Placeholders:** Supports `$ARGUMENTS` (for passing arguments), `!command` (to inject shell command output), and `@filename` (to include file content).
- **Execution:** Commands run in the project's root directory, and their output becomes part of the prompt.

## 13. Keybinds (from `https://opencode.ai/docs/keybinds/`)

- **Customization:** Fully customizable through the `opencode.json` configuration file.
- **Leader Key:** Utilizes a "leader key" (defaulting to `ctrl+x`) that must be pressed before most other keybind shortcuts to prevent conflicts in the terminal.
- **Disabling:** Specific keybinds can be disabled by setting their value to "none".

## 14. Formatters (from `https://opencode.ai/docs/formatters/`)

- **Purpose:** Automatically format files after they are written or edited, ensuring code adheres to project styles.
- **Configuration:** Defined within the `formatter` section of the `opencode.json` configuration file.
- **Properties:** Includes `disabled`, `command` (the command to execute for formatting), `environment` (environment variables), and `extensions` (file extensions it handles).
- **Custom Formatters:** Can be defined by specifying their `command` and `extensions`, using `$FILE` as a placeholder for the file path.

## 15. Themes (from `https://opencode.ai/docs/themes/`)

- **Customization:** Offers extensive customization options, allowing users to select from built-in themes, adapt to their terminal's theme, or define custom themes using a flexible JSON-based system.
- **Types:** Built-in themes, "system" theme (adapts to terminal background).
- **Custom Theme Format:** Flexible JSON format, allowing for hex colors, ANSI colors, color references, dark/light variants, and the "none" value to inherit terminal defaults.
- **Location and Precedence:** Custom themes can be defined at the user-wide or project-specific level, with a hierarchy determining precedence.