# 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