OpenCode

OpenCode is an open-source, multi-provider AI coding assistant that offers flexibility in model selection and provider configuration.

Overview

Key Features

Feature	Description
Multi-Provider	Switch between Anthropic, OpenAI, and others
Configurable	YAML-based configuration
Prompt Templates	Reusable prompt library
Project Aware	Reads project context files

Installation

# Install OpenCode
go install github.com/opencode-ai/opencode@latest

# Or download binary from releases
curl -fsSL https://opencode.ai/install.sh | sh

# Verify installation
opencode version

Configuration

Directory Structure

.opencode/
├── config.yaml      # Main configuration
├── .env             # API keys (gitignored)
├── .env.example     # API key template
└── prompts/         # Custom prompts
    ├── chapter-writer.md
    ├── researcher.md
    └── reviewer.md

config.yaml

# OpenCode Configuration for Documentation Generation

# Provider settings
providers:
  anthropic:
    enabled: true
    api_key: "${ANTHROPIC_API_KEY}"
    default_model: "claude-sonnet-4-20250514"

  openai:
    enabled: true
    api_key: "${OPENAI_API_KEY}"
    default_model: "gpt-4-turbo"

# Task-specific model assignments
task_models:
  # Complex writing tasks
  chapter_writing:
    provider: "anthropic"
    model: "claude-opus-4-20250514"

  # Research and analysis
  research:
    provider: "anthropic"
    model: "claude-sonnet-4-20250514"

  # Code generation
  code:
    provider: "anthropic"
    model: "claude-sonnet-4-20250514"

  # Quick fixes
  quick:
    provider: "anthropic"
    model: "claude-3-5-haiku-20241022"

# Project settings
project:
  context_file: "INSTRUCTIONS.md"
  include_patterns:
    - "latex/**/*.tex"
    - "agents/**/*.md"
    - "plan/**/*.md"
  exclude_patterns:
    - "node_modules/**"
    - "*.log"

Environment Variables

Create the .opencode/.env file:

# Anthropic API
ANTHROPIC_API_KEY=sk-ant-api...

# OpenAI API (optional)
OPENAI_API_KEY=sk-...

Security

Never commit .env files. Add to .gitignore:

.opencode/.env

Project Context

INSTRUCTIONS.md

# OpenCode Project Instructions

## Project Type
LaTeX documentation generation using AI agents.

## Key Directories
- `sources/` - Input documents (PDF, DOCX)
- `latex/` - Output LaTeX files
- `agents/` - Agent prompt templates

## Writing Guidelines
1. Use flowing academic prose
2. Limit bullet lists (max 2-3 per chapter)
3. Include citations using \cite{}
4. Proper language with correct formatting

## Model Selection
- Complex chapters: Use Opus
- Simple tasks: Use Sonnet
- Quick fixes: Use Haiku

Custom Prompts

prompts/chapter-writer.md

# Chapter Writer Prompt

You are a technical documentation writer.

## Task
Write LaTeX chapter: {{chapter_name}}

## Requirements
- Maximum pages: {{max_pages}}
- Language: {{language}}
- Style: Academic prose, minimal bullet lists

## Sources
{{#each sources}}
- {{this.name}}: {{this.description}}
{{/each}}

## Output
Complete LaTeX chapter file.

Using Custom Prompts

# Run with custom prompt
opencode run prompts/chapter-writer.md \
  --var chapter_name="05-security" \
  --var max_pages="8" \
  --var language="English"

Workflow Integration

Provider Selection by Task

Command Examples

# Use specific task model
opencode --task chapter_writing "Write chapter 05"

# Override model
opencode --model claude-opus-4-20250514 "Complex analysis task"

# Use different provider
opencode --provider openai "Generate code example"

Comparison: OpenCode vs Claude Code

Feature	Claude Code	OpenCode
Providers	Anthropic only	Multiple
Configuration	JSON	YAML
Prompt Library	Built-in	Custom templates
Agent Spawning	Native	Manual
Best For	Anthropic-focused	Multi-provider needs

Best Practices

1. Task-Model Mapping

Configure appropriate models for each task type:

task_models:
  # High complexity, high cost
  complex_analysis:
    model: "claude-opus-4-20250514"

  # Medium complexity, balanced
  standard_writing:
    model: "claude-sonnet-4-20250514"

  # Low complexity, fast
  formatting:
    model: "claude-3-5-haiku-20241022"

2. Context Optimization

project:
  # Include only relevant files
  include_patterns:
    - "latex/chapters/*.tex"
    - "agents/*.md"

  # Exclude build artifacts
  exclude_patterns:
    - "*.aux"
    - "*.log"
    - "*.pdf"

3. Prompt Versioning

Keep prompts under version control:

prompts/
├── v1/
│   └── chapter-writer.md
├── v2/
│   └── chapter-writer.md  # Improved version
└── current -> v2/         # Symlink to current

Troubleshooting

Provider Not Configured

Error: 'anthropic' provider is not configured

Solution:

1. Check that .opencode/config.yaml contains the enabled provider
2. Verify API key in .opencode/.env
3. Ensure environment variables are loaded

Model Not Found

Error: 'claude-opus' model not found

Solution: Use full model identifiers:

• claude-opus-4-20250514 (not claude-opus)
• claude-sonnet-4-20250514 (not claude-sonnet)

Next Steps

• Claude Code - Primary orchestration tool
• External AI Tools - Research services
• Agent Prompts - Prompt templates