OpenCode Internal Documentation

Architecture Overview

The OpenCode codebase is structured to facilitate the development and deployment of an open-source AI coding agent. The architecture is modular, with distinct components handling various aspects of the system's functionality. The primary components include the Agent Client Protocol (ACP) implementation, the command-line interface (CLI), and various utilities for authentication and integration with external services like GitHub.

Major Components

1. Agent Client Protocol (ACP)

   • Located in packages/opencode/src/acp, this component implements the Agent Client Protocol, which is responsible for initializing agents, managing sessions, and handling protocol-specific capabilities.
   • The core file agent.ts manages the lifecycle of an agent and ensures compliance with the protocol.

2. Command-Line Interface (CLI)

   • The CLI provides users with the ability to interact with the OpenCode agent through commands. It is implemented in packages/opencode/src/cli.
   • Commands are organized within the cmd directory, with each command encapsulated in its own file (e.g., auth.ts, github.ts).

3. Authentication

   • The authentication module, found in packages/opencode/src/auth, handles user authentication and authorization processes, integrating with various identity providers.

4. Integration with External Services

   • Integration with services like GitHub is facilitated through specific modules, such as github.ts in the CLI commands directory. This module handles tasks like issue explanation and resolution directly within GitHub.

Core Data Structures and Abstractions

Key Types and Interfaces

• Agent Interface: Defined in the ACP implementation, the Agent interface outlines the necessary methods and properties for any agent conforming to the protocol.
• Session Management: Sessions are managed using a structured approach, with types defined in session.ts to handle session states and transitions.
• Authentication Models: The authentication module defines types for handling user credentials and authorization tokens.

Key Subsystems

Agent Client Protocol (ACP)

The ACP subsystem is crucial for maintaining protocol compliance and managing agent interactions. It uses a clean separation of concerns, with distinct files handling different aspects of the protocol.

// Example from agent.ts
class Agent {
  constructor() {
    // Initialization logic
  }
  
  public startSession(): void {
    // Session start logic
  }
  
  public endSession(): void {
    // Session end logic
  }
}

Command-Line Interface (CLI)

The CLI subsystem is designed to provide a flexible and extensible interface for interacting with OpenCode. Each command is implemented as a separate module, allowing for easy addition and modification of commands.

// Example from auth.ts
function authenticateUser(credentials: Credentials): Promise<AuthResponse> {
  // Authentication logic
}

Authentication

The authentication subsystem ensures secure and efficient user authentication, supporting various identity providers. It abstracts the complexity of handling different authentication mechanisms.

Important Code Paths and Algorithms

Session Management

Session management is a critical aspect of the ACP implementation. The lifecycle of a session involves initialization, active state management, and termination. The session.ts file orchestrates these transitions, ensuring that each session adheres to protocol requirements.

GitHub Integration

The GitHub integration module (github.ts) allows OpenCode to interact with GitHub repositories, facilitating tasks like explaining issues or automating pull requests. This integration leverages GitHub's API to perform actions based on user commands.

Extension Points

Adding New Commands

To extend the CLI with new functionality, developers can create new command modules within the cmd directory. Each module should export a function that defines the command's behavior and integrates with the existing CLI infrastructure.

Integrating New Identity Providers

The authentication subsystem is designed to support multiple identity providers. To add a new provider, developers can implement the necessary authentication logic within the auth module and ensure it conforms to the existing interface.

Expanding Protocol Capabilities

The ACP implementation allows for the addition of new capabilities by extending the Agent interface and updating the agent.ts file to handle these new capabilities.

By understanding the architecture, core data structures, key subsystems, important code paths, and extension points, developers can effectively modify, debug, or extend the OpenCode codebase.