Appendix D: OpenCode Quick Reference¶

This appendix serves as a quick-reference manual for OpenCode, a Rust-native, multi-provider CLI AI assistant. OpenCode is an emerging alternative to Aider that offers a lightweight, fast, and provider-agnostic experience.

When to use OpenCode: - You prefer a Rust-native tool with minimal dependencies - You want fast startup time and low memory footprint - You're looking for a lightweight alternative to Aider - You want to experiment with bleeding-edge features

1. Installation & Setup¶

1.1 Install OpenCode¶

OpenCode is distributed as a single binary with no Python dependencies:

# Using Cargo (Rust package manager)
cargo install opencode

# Or via Homebrew (macOS/Linux)
brew install opencode

# Or download the pre-built binary from GitHub releases
# https://github.com/opencode-ai/opencode/releases

# Verify installation
opencode --version

1.2 Environment Configuration¶

OpenCode reads configuration from a file or environment variables:

# Create your .env file
cp .env.example .env

# Add your API keys
# OPENAI_API_KEY=sk-...      # For OpenAI models
# ANTHROPIC_API_KEY=sk-...    # For Claude models
# DEEPSEEK_API_KEY=sk-...     # For DeepSeek models

1.3 Configuration File¶

Create .opencode.json in your repository root:

{
  "model": "qwen-2.5-coder",
  "providers": {
    "deepseek": {
      "api_key": "${DEEPSEEK_API_KEY}",
      "base_url": "https://api.deepseek.com/v1"
    },
    "qwen": {
      "api_key": "${QWEN_API_KEY}",
      "base_url": "https://dashscope.aliyuncs.com/compatible-mode/v1"
    }
  },
  "context": {
    "files": [
      "AGENTS.md",
      "AI_CONTEXT.md",
      "README.md"
    ]
  },
  "git": {
    "auto_commit": true,
    "commit_prompt": true
  },
  "validation": {
    "command": "make validate",
    "auto_fix": true
  }
}

2. Core Commands¶

OpenCode is designed for simplicity and speed:

Command	Description	Example
`opencode <file>`	Start a session with a file	`opencode docs/03-iac-using-ai.md`
`opencode -m <model> <file>`	Use a specific model	`opencode -m deepseek-chat docs/03-iac-using-ai.md`
`opencode -c <context-file>`	Add context file	`opencode -c AGENTS.md docs/03-iac-using-ai.md`
`opencode -p <prompt>`	Execute a one-shot prompt	`opencode -p "Review this chapter" docs/03-iac-using-ai.md`
`opencode --local`	Use local model (Ollama/LlamaFile)	`opencode --local docs/03-iac-using-ai.md`

Interactive Commands (within OpenCode session)¶

Command	Description
`/help`	Show all commands
`/model <name>`	Switch model
`/add <file>`	Add file to context
`/commit`	Commit changes
`/undo`	Revert last change
`/diff`	Show changes
`/run <command>`	Run shell command
`/exit`	Exit session

3. The 3-Tier Strategy in OpenCode¶

Tier Selection Guide¶

Tier	Model	Command	Use Case
Tier 1: Architect	`deepseek-chat`	`opencode -m deepseek-chat`	Complex reasoning, structural reviews
Tier 2: Editor	`qwen-2.5-coder`	`opencode -m qwen-2.5-coder`	Default: editing, validation fixes (80% of tasks)
Tier 3: Sovereign	`ollama/qwen2.5-coder`	`opencode --local`	NV1/Government, sensitive data

How to Switch Tiers¶

# Start with Tier 2 Editor (default)
opencode docs/03-iac-using-ai.md

# Switch to Tier 1 Architect within the session
/model deepseek-chat

# Start directly with local Sovereign model
opencode --local docs/03-iac-using-ai.md

# One-shot with specific model
opencode -m deepseek-chat -p "Review this chapter" docs/03-iac-using-ai.md

4. Common Workflows¶

4.1 Improving a Chapter (Tier 2 Editor)¶

# Using the Makefile (if you've added OpenCode support)
make improve-chapter-open CHAPTER=03

# Or manually
opencode -m qwen-2.5-coder \
  -c AGENTS.md \
  -c AI_CONTEXT.md \
  docs/03-iac-using-ai.md

4.2 Deep Review (Tier 1 Architect)¶

# Using the Makefile
make review-chapter-open CHAPTER=03

# Or manually
opencode -m deepseek-chat \
  -p "Perform a deep review of this chapter. Provide specific, actionable suggestions. Do NOT apply changes." \
  docs/03-iac-using-ai.md

4.3 Sovereign Mode (Tier 3 Local)¶

# Using the Makefile
make sovereign-improve-open CHAPTER=03

# Or manually
opencode --local \
  -c AGENTS.md \
  -c AI_CONTEXT.md \
  docs/03-iac-using-ai.md

4.4 Fixing Validation Issues¶

opencode -m qwen-2.5-coder \
  -p "Fix all validation issues reported by 'make validate'. Make minimal, surgical changes." \
  docs/*.md

5. OpenCode vs. Aider¶

Aspect	Aider	OpenCode
Language	Python	Rust
Performance	Good	Very fast (Rust-native)
Startup Time	~1-2 seconds	~100-200ms
Memory Usage	~200-400MB	~50-100MB
Model Support	100+ via LiteLLM	Growing, multi-provider
Edit Format	10+ strategies	Evolving
Community	42K+ stars	Emerging
Maturity	Very mature (35 months)	Newer, rapidly evolving

Recommendation: Use OpenCode if you need a lightweight, fast tool and are comfortable with Rust-based binaries. Stick with Aider if you need maximum model compatibility and battle-tested stability.

6. Cost Optimization Tips¶

OpenCode supports the same token-saving practices as Aider:

Practice	How-To
Read-only files	Use `-c` for context files instead of adding them
Targeted editing	Specify exact files, not entire directories
Use Tier 2 by default	Default to `qwen-2.5-coder` for 80% of tasks
Local Tier 3	Use `--local` for sensitive work ($0.00)

Pre-Flight Cost Check¶

# Estimate tokens before running
opencode --estimate-cost docs/03-iac-using-ai.md

7. Troubleshooting¶

Issue	Solution
"Command not found"	Ensure OpenCode is installed and in PATH
"API key missing"	Set environment variables or add to `.opencode.json`
"Model not found"	Check provider configuration in `.opencode.json`
Git conflict	Commit or stash changes before session
Local model not found	Pull model: `ollama pull qwen2.5-coder`

8. Integration with Makefile¶

Add these targets to your Makefile to support OpenCode:

# ==================== OpenCode Workflows ====================
improve-chapter-open:
    @echo "🔄 Improving chapter with OpenCode..."
    @opencode -m qwen-2.5-coder \
        -c AGENTS.md \
        -c AI_CONTEXT.md \
        -p "Improve this chapter following AGENTS.md rules." \
        docs/$(CHAPTER).md

review-chapter-open:
    @echo "🔍 Reviewing chapter with OpenCode (Architect)..."
    @opencode -m deepseek-chat \
        -c AGENTS.md \
        -c AI_CONTEXT.md \
        -p "Review this chapter for technical accuracy, clarity, and completeness." \
        docs/$(CHAPTER).md

sovereign-improve-open:
    @echo "🔒 Improving with Sovereign model..."
    @opencode --local \
        -c AGENTS.md \
        -c AI_CONTEXT.md \
        -p "Improve this chapter. Ensure all data stays local." \
        docs/$(CHAPTER).md