Welcome to opencode

Your guide to understanding the codebase

Learning Path

5 levels
17 learning units

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

Agent System & Tool Integration

Architecture

  • Multi-Provider LLM Integration • Integration • 10
  • Session & Workspace Management • Workflow • 5
  • Interaction & Integration • UI components, external connectors • 2

API Gateway & SDK

Multi-Platform Applications

Architecture • 4

Cross-Cutting Concerns

  • Auth, logging, config, testing • 2

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

Patterns • 6

Additional Testing Patterns

Testing • 1

Test Your Knowledge

Start Quiz

Progress 0/26 answered

Question Tiers - ordered for deep understanding

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

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

  • .opencode/agent/docs.md:1-35
    Understand the agent system architecture and how tools are registered and executed
    explore
  • 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
  • .opencode/agent/docs.md:15-30
    Pay attention to how tools are defined, their input/output schemas, and execution context
    explore
  • 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 patternconceptual
  • Hint 2: Workspace and file accesscode location
  • Hint 3: Structuring your tool outputimplementation
  • Hint 4: Integration pointsimplementation
  • Hint 5: Testing your tooltesting

Prerequisites

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

opencode - Learning Path