Welcome to opencode

Your guide to understanding the codebase

Learning Path

17 units • 5 levels

Orchestration & APIs

  • Pipelines, workflows, public interfaces • 3 units

Database & Storage Layer

  • Data Model
  • Project Structure & Configuration

Infrastructure

  • CLI & Command System
  • Tooling • 7

Core Logic & Data

  • Business rules, schemas, models • 3 units

Agent System & Tool Integration

  • Architecture • 11

Multi-Provider LLM Integration

  • Integration • 10

Session & Workspace Management

  • Workflow • 5

Interaction & Integration

  • UI components, external connectors • 2 units

API Gateway & SDK

  • API • 3

Multi-Platform Applications

  • Architecture • 4

Cross-Cutting Concerns

  • Auth, logging, config, testing • 2 units

Deployment & Infrastructure

  • Deployment
  • Security & Billing
    • Security • 7

Edge Cases & Resilience

  • Error handling, fault tolerance • 4

Additional Data Model Patterns

  • Data Model • 11

Additional Error Handling Patterns

  • Error Handling • 9

Additional Patterns

  • Patterns • 6

Additional Testing Patterns

  • Testing • 1

Test Your Knowledge

Test your deep understanding of the codebase

Question Tiers

  • Why
    • Purpose & Problem • 8
  • Architecture
    • Design & Patterns • 10
  • Code
    • Implementation • 8

Hands-On Assignment

90-120 minutes

Your Challenge

Create a custom agent tool that integrates with the existing tool system to analyze code quality metrics across a workspace. The tool should leverage the agent system's tool integration patterns to scan files, calculate metrics (like cyclomatic complexity, file size distribution, or comment density), and return structured results that agents can use to provide recommendations. This will help you understand how agents discover and execute tools, how tools interact with the workspace, and how results flow back through the LLM provider chain.

Starting Points

  1. .opencode/agent/docs.md:1-35
    • Understand the agent system architecture and how tools are registered and executed
    • explore
  2. github/index.ts:1-165
    • Study this GitHub Action integration to see how external tools interact with the opencode system and process workspace data
    • reference
  3. .opencode/agent/docs.md:15-30
    • Pay attention to how tools are defined, their input/output schemas, and execution context
    • explore
  4. github/action.yml:1-75
    • See how configuration and inputs are structured for external integrations
    • reference

Success Criteria

  • Tool is discoverable by the agent system and appears in the available tools list
  • Tool can be invoked with parameters (e.g., target directory, specific metrics to calculate)
  • Tool successfully analyzes at least 3 different code quality metrics across workspace files
  • Tool returns structured JSON output that includes per-file metrics and workspace-level summaries
  • An agent can successfully use your tool to answer questions like 'What files in this workspace need refactoring?'
  • Tool handles edge cases gracefully (empty directories, non-code files, permission errors)

Hints

  • Hint 1: Understanding the tool registration pattern
  • Hint 2: Workspace and file access
  • Hint 3: Structuring your tool output
  • Hint 4: Integration points
  • Hint 5: Testing your tool

Prerequisites

  • TypeScript/JavaScript basics
  • JSON schema design
  • File system operations
  • Understanding of code metrics concepts

opencode - Learning Path