OpenCode Setup Guide

​

Overview

• 75+ LLM providers: Claude, GPT, Gemini, DeepSeek, Kimi, local models, and more
• Model experimentation: Compare reasoning quality across providers
• Cost optimization: Switch to cheaper models for routine tasks
• Beautiful TUI: Visual, intuitive terminal interface
• Multi-session: Work on multiple research projects simultaneously
• LSP support: Advanced code intelligence and navigation
• Open source: MIT license, community-driven (27K+ GitHub stars)

• Official Website
• GitHub Repository (27K stars)
• Documentation

​

Step 1: Installation

​

1.1 Prerequisites

• Node.js 18 or newer
• Terminal access
• API keys for providers you want to use

node --version

​

1.2 Install OpenCode

npm install -g opencode

opencode --version

cd ~/your-research-project
opencode

​

Step 2: Configure AI Providers

​

2.1 Multiple Provider Support

• Anthropic (Claude) - Best reasoning
• OpenAI (GPT) - Broad capability
• Google (Gemini) - Large context
• DeepSeek - Cost-effective
• Kimi K2 - Strong analysis
• Local models (via Ollama) - Privacy

​

2.2 Add Your First Provider

opencode

1. Navigate to Settings (usually s key)
2. Select Providers
3. Click Add Provider
4. Choose from list (e.g., “Anthropic”)
5. Enter API key
6. Select default model (e.g., “claude-sonnet-4.5”)
7. Save and test

​

2.3 Configure Multiple Providers

1. Google (Gemini): Free tier, massive context
   • Provider: Google AI
   • API Key: From Google AI Studio
   • Model: gemini-2.5-pro
2. Anthropic (Claude): Premium reasoning
   • Provider: Anthropic
   • API Key: From Anthropic Console
   • Model: claude-sonnet-4.5
3. DeepSeek: Budget-friendly
   • Provider: DeepSeek
   • API Key: From DeepSeek Platform
   • Model: deepseek-chat

​

Step 3: Using the TUI Interface

​

3.1 Navigation

• Chat Area: Conversation with AI
• File Explorer: Browse project files
• Provider Selector: Switch models on-the-fly
• Settings: Configure preferences

• Tab: Switch between panels
• Enter: Select/activate
• Esc: Go back
• ?: Help menu
• q: Quit

​

3.2 Model Switching

1. Ask same question to different models
2. Switch provider mid-conversation
3. Compare reasoning approaches
4. Document which models excel at what

Question to GPT-5: "Identify themes in these 10 papers"
→ Switch to Claude
Same question to Claude: "Identify themes in these 10 papers"
→ Compare quality of thematic analysis

​

Step 4: Project Setup for Research

​

4.1 Create Research Project

/Research-OpenCode/
├── .opencode/
│   └── config.json       # Project-specific settings
├── literature/            # Papers (markdown)
├── analysis/              # Data, results
├── notes/                 # Research notes
└── drafts/                # Paper sections

​

4.2 Project Configuration

{
  "project": "Literature Review AI Education",
  "defaultProvider": "google",
  "defaultModel": "gemini-2.5-pro",
  "context": {
    "alwaysInclude": ["@README.md"],
    "folders": ["literature", "analysis"]
  },
  "preferences": {
    "citationStyle": "APA 7th",
    "outputFormat": "markdown"
  }
}

​

Step 5: File Management

​

5.1 File Explorer Panel

• Browse folders in TUI
• Click files to add to context
• Multi-select for batch operations
• See file previews

​

5.2 Reference Files with @

"Summarize @/literature/smith2024.md"

"Compare @/literature/smith2024.md and @/literature/jones2024.md"

"Analyze all files in @/literature/ for common methodologies"

​

5.3 Multi-File Operations

"For each file in @/literature/:
1. Extract research question
2. Extract methodology
3. Extract key findings
4. Save to @/analysis/extraction_table.csv"

​

Step 6: Multi-Session Workflows

​

6.1 Work on Multiple Projects

# Terminal 1
cd ~/Literature-Review
opencode --session "lit-analysis"

# Terminal 2
cd ~/Data-Analysis
opencode --session "data-work"

• Context separated by project
• No crosstalk between tasks
• Resume any session anytime

​

6.2 Shareable Session Links

1. Complete analysis in OpenCode
2. Generate shareable link
3. Send to advisor
4. They can review your exact prompts and outputs

• Reproducibility
• Feedback from supervisors
• Teaching others your workflow

​

Step 7: Model Comparison Workflows

​

7.1 The Research Question Test

Provider: OpenAI
"Based on these 10 papers in @/literature/, what are the
three most significant research gaps?"

Provider: Anthropic
[Same question]

Provider: Google
[Same question]

• Which model identified the deepest gaps?
• Which had the most creative insights?
• Which was most thorough?

​

7.2 Cost-Quality Optimization

1. DeepSeek (cheap): Initial screening, data extraction
2. Gemini (free + powerful): Comprehensive synthesis
3. Claude (premium): Final theoretical arguments

• DeepSeek: $0.14 per 1M tokens
• Gemini: FREE (1K req/day)
• Claude: $3 per 1M tokens

​

Step 8: LSP Features for Research

​

8.1 Code Intelligence for Data Analysis

• LSP provides autocomplete
• Function signatures
• Documentation lookup
• Error detection

"Review my R script @/analysis/meta_analysis.R:
- Check statistical methodology
- Suggest improvements
- Verify effect size calculations"

​

8.2 Navigate Large Codebases

• Jump to definitions
• Find all references
• Understand dependencies
• Refactor safely

​

Step 9: Integration with Research Memex

​

9.1 Zotero → OpenCode Pipeline

1. Export papers from Zotero
2. Convert via OCR Guide
3. Load into OpenCode
4. Choose model based on task:
   • Gemini: Massive corpus analysis
   • Claude: Deep theoretical work
   • DeepSeek: High-volume screening

​

9.2 OpenCode → Obsidian

1. Complete analysis in OpenCode
2. Save markdown outputs
3. Import to Obsidian
4. Link with literature notes

​

9.3 OpenCode → Zettlr

1. Generate synthesis with best-fit model
2. Export to Zettlr
3. Add @citekeys
4. Export to Word/PDF

​

Step 10: Best Practices

​

10.1 Model Selection Strategy

​

10.2 Session Management

• Session: “screening” → Use DeepSeek
• Session: “synthesis” → Use Gemini
• Session: “writing” → Use Claude

• Clear separation of work
• Easy to resume
• Context doesn’t bleed between phases

​

10.3 Cost Tracking

• Check provider dashboards regularly
• Log which models you use for each task
• Calculate cost per paper analyzed
• Optimize based on results

​

Step 11: Advanced Features

​

11.1 Custom Provider Configuration

• Together AI
• Perplexity
• Groq (ultra-fast)
• Replicate (specialized models)
• Ollama (local privacy)

{
  "providers": {
    "custom": {
      "baseURL": "https://api.example.com/v1",
      "apiKey": "$CUSTOM_API_KEY",
      "models": ["custom-research-model"]
    }
  }
}

​

11.2 Batch Processing

"For each paper in @/literature/ (47 total):
1. Run /summarize command
2. Save output to @/summaries/[filename]_summary.md
3. Track progress with todo list
4. Report when complete"

​

11.3 Workflow Automation

# analyze-batch.sh
#!/bin/bash
for file in literature/*.md; do
  opencode --provider deepseek \
    --prompt "/summarize @/$file" \
    --output "summaries/$(basename $file)"
done

​

Step 12: Troubleshooting

​

Installation Issues

• Reinstall: npm install -g opencode
• Check npm global path: npm config get prefix
• Restart terminal

• Clear npm cache: npm cache clean --force
• Try with sudo: sudo npm install -g opencode

​

Provider Connection Errors

• Verify API key is correct
• Check provider has credits
• Test with provider’s web interface first
• Ensure no firewall blocking

​

TUI Display Issues

• Use modern terminal (iTerm2, Windows Terminal, Alacritty)
• Avoid old terminals (cmd.exe)
• Check terminal size (minimum 80x24)
• Enable UTF-8 support

​

Model Not Responding

• Check internet connection
• Verify provider API status
• Try different model from same provider
• Switch to alternative provider

​

Step 13: OpenCode vs Other CLIs

​

Comparison Matrix

​

When to Use OpenCode

• ✅ You want to experiment with multiple models
• ✅ Need to optimize costs (use cheap models for routine tasks)
• ✅ Prefer visual TUI over plain text
• ✅ Want open-source flexibility
• ✅ Need to compare model reasoning quality

• Premium reasoning quality is paramount
• Budget allows for subscription
• Want enterprise support

• Need massive 1M context window
• Want completely free solution
• Comfortable with Google ecosystem

• Teaching/learning different tools
• Optimizing workflow (right tool for right task)
• Cost-quality tradeoff matters

​

Step 14: Research Workflows with OpenCode

​

14.1 Model Comparison for Synthesis

"What theoretical frameworks dominate the organizational
scaling literature?"

# Switch to DeepSeek (cheap)
[Ask question]
→ Note: Fast, decent, misses some nuances

# Switch to Gemini 2.5 Pro (free)
[Ask question]
→ Note: Comprehensive, good coverage, solid reasoning

# Switch to Claude Sonnet (premium)
[Ask question]
→ Note: Deepest insights, best theoretical connections

​

14.2 Cost-Optimized Literature Processing

Provider: DeepSeek
"Screen all 200 abstracts in @/screening/abstracts.txt
against inclusion criteria. Save to screening_results.csv"

Provider: Kimi K2
"Extract data from 50 included papers using /extract command.
Compile to master extraction table."

Provider: Google Gemini
"Analyze all 50 extracted papers. Identify themes, frameworks, gaps."

Provider: Anthropic Claude
"Develop novel theoretical framework integrating findings.
Propose testable propositions."

​

14.3 Privacy-Sensitive Research

brew install ollama  # macOS
# or download from ollama.com

ollama pull llama3.3:70b

Provider: Ollama
Model: llama3.3:70b
Base URL: http://localhost:11434

• 100% offline processing
• No data sent to cloud
• Perfect for sensitive research (medical, proprietary, etc.)
• Unlimited free usage

​

Step 15: Advanced Features

​

15.1 Multi-Session Workflows

opencode --session "lit-review" --provider google

opencode --session "data-analysis" --provider claude

opencode --session "theory" --provider claude

​

15.2 Session Sharing

In OpenCode → Settings → Export Session
→ Generates shareable link or JSON
→ Colleagues can import and see exact workflow

• Share with advisor for feedback
• Document methodology for papers
• Teach workflow to lab members
• Reproduce analysis later

​

15.3 LSP-Powered Code Analysis

"Review my Python script @/analysis/regression.py:
- Check statistical correctness
- Suggest improvements
- Explain complex sections
- Add documentation"

​

Step 16: Integration Strategies

​

16.1 The Three-CLI Strategy

• Load 50 papers (1M context)
• Comprehensive first-pass synthesis
• FREE tier lasts all day

• Compare synthesis across models
• Test DeepSeek vs Claude vs GPT
• Optimize for cost-quality

• Final theoretical refinement
• Premium reasoning for arguments
• Prepare for publication

​

16.2 From GUI to CLI

1. Develop workflow in Cherry Studio (visual, easy)
2. Extract prompts that work well
3. Automate in OpenCode (scriptable, faster)
4. Use Cherry Studio for exploration, OpenCode for production

​

Step 17: Learning Resources

​

17.1 Official Documentation

• OpenCode Docs
• GitHub Repo
• CLI Reference

​

17.2 Community

• GitHub Discussions: Ask questions, share workflows
• Issues: Report bugs, request features
• Contributors: 188+ active contributors
• Monthly users: 200,000+ developers

​

17.3 Tutorials & Guides

• Hacker News Discussion
• DEV Community
• Comparison Articles

​

Checklist

• Installed OpenCode via npm
• Configured at least 2 AI providers (e.g., Google + Claude)
• Launched the TUI interface
• Created a research project folder
• Configured project settings (.opencode/config.json)
• Tested file references with @ syntax
• Compared same task across 2 different models
• Created a multi-session workflow
• Understood cost optimization strategies
• Chosen which models to use for different research tasks

​

Resources

​

Provider Setup Guides

• API Keys Setup - Get provider keys
• Google AI Studio - Free Gemini access
• Anthropic Console - Claude keys
• DeepSeek Platform - Budget option

​

Other CLI Tools

• Claude Code - Premium single-provider
• Gemini CLI - Free Google power
• CLI Comparison - Which tool for what?

​

Research Memex Workflow

• Cherry Studio - GUI alternative
• Session 4: Agentic Workflows - Concepts
• SLR Workflow - Complete example
• Failure Museum - Quality control