OpenCode Setup Guide

Intermediate · 15–20 min · provider API keys or OpenCode Zen account

Hold the tool constant, change the model, and isolate what actually matters.

Overview

OpenCode is an open-source, multi-provider terminal agent. It keeps the tool constant while you vary the model or provider. This lets you run model-selection experiments.

OpenCode supports Claude, GPT, Gemini, DeepSeek, Kimi, and local models from a single interface. Send the same prompt to any provider without changing your workflow. The trade-off: you configure each provider and choose the right model for the task.

Official resources:

• OpenCode website
• GitHub repository
• OpenCode documentation

Install

Prerequisites

• Node.js 18 or newer, or a supported package manager (npm, bun, pnpm, yarn)
• A modern terminal emulator
• API keys for any provider you want to use, or an OpenCode Zen account

Check Node.js:

node --version

Installation options

npm install -g opencode-ai

brew install anomalyco/tap/opencode

curl -fsSL https://opencode.ai/install | bash

Verify the binary:

opencode --version
opencode --help

First launch

cd ~/your-research-project
opencode

The first time you run OpenCode in a project, run /init to create an AGENTS.md file that records the project structure and conventions.

Configure providers

Option A: OpenCode zen

The OpenCode team curates OpenCode Zen, a selected list of models. Inside OpenCode, run:

/connect

Select opencode, sign in at the printed URL, and paste the API key. This is the fastest way to start if you do not already have provider keys.

Option B: direct provider keys

Add your keys directly if you already use Claude, OpenAI, Google, DeepSeek, or Kimi APIs. Provider support changes; check the OpenCode provider list for the current set.

Common research providers:

• Anthropic — Claude Opus 4.8, Sonnet 5, Haiku 4.5
• OpenAI — GPT-5.5, GPT-5.4 family
• Google — Gemini 3.5 Flash, Gemini 3.1 Pro preview
• DeepSeek — V4-era models
• Kimi — K2.7 Code, K2.6
• Local — Ollama or another OpenAI-compatible local endpoint

Basic interface

OpenCode is a terminal UI with two primary modes:

• Build mode — default; can read, write, and run commands in the project
• Plan mode — read-only analysis and planning; toggle with Tab

Use Plan mode when you want the agent to think through a change before making it. Switch back to Build mode to execute.

Referencing files

Use @ to point to files or folders:

Summarize @/literature/smith2024.md

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

What methods appear most often across @/literature/?

Sharing a conversation

Use /share to generate a link to the current conversation. This is useful for reproducibility, advisor feedback, or teaching.

Project setup for research

A minimal research project might look like this:

/Research-OpenCode/
├── AGENTS.md              # Project conventions generated by /init
├── literature/            # Papers (markdown)
├── analysis/              # Data, results
├── notes/                 # Research notes
└── drafts/                # Paper sections

Run /init after navigating to the folder. Then edit AGENTS.md to include project-specific conventions, such as citation style, output format, or coding standards.

Model-comparison workflow

The core research pattern is to hold the prompt and context constant and vary the model.

1. Ask one model a question.
2. Switch provider or model inside OpenCode.
3. Ask the same question again.
4. Record differences in reasoning, depth, and factual accuracy.

Example:

[Claude Sonnet 5]
"Based on these 10 papers in @/literature/, what are the three most significant research gaps?"

[Gemini 3.5 Flash]
"Based on these 10 papers in @/literature/, what are the three most significant research gaps?"

Document which gaps each model identifies, which citations it uses, and where it hallucinates.

Cost-quality strategy

A common pattern is to use cheaper models for high-volume work and stronger models for final synthesis:

1. Screening — DeepSeek or Gemini Flash/Lite for initial filtering
2. Extraction — Kimi K2.6 or another mid-range model for structured output
3. Synthesis — Gemini 3.5 Flash or Gemini 3.1 Pro preview for large-context synthesis
4. Final argument — Claude Opus 4.8 or Sonnet 5 for theoretical framing

Track costs in each provider's dashboard. Log which model handled each task so you can optimize costs later.

Integration with Research Memex

Zotero → OpenCode

1. Export papers from Zotero.
2. Convert PDFs via the OCR guide.
3. Load the markdown into an OpenCode project.
4. Run the same analysis prompt across multiple providers.

OpenCode → Obsidian or Zettlr

1. Save markdown outputs from OpenCode.
2. Import them into Obsidian or Zettlr.
3. Link insights to literature notes and add @citekeys.

Comparison with other CLIs

Choose OpenCode when model choice is part of the method. Choose Claude Code when a single polished agent matters more. Choose Antigravity CLI when the Google terminal-agent workflow is the right fit.

Best practices

• Defaults first. Use provider defaults for temperature and sampling unless the model docs recommend otherwise.
• Version your prompts. Save successful prompts so you can rerun them across models.
• Record failure modes. The most useful comparison data often comes from model failures, not successes.
• Start small. Run a single paper through three models before scaling to a full corpus.
• Check quotas. Free tiers and rate limits change; verify them before batch work.

Troubleshooting

opencode: command not found

• Reinstall with npm install -g opencode-ai
• Check the npm global prefix: npm config get prefix
• Ensure the install directory is in PATH: echo $PATH
• Restart the terminal

Provider connection errors

• Verify the API key is correct and has credits
• Test the key with the provider's own interface first
• Check the OpenCode provider list for the exact model ID and base URL

Display issues

• Use a modern terminal emulator (WezTerm, Alacritty, Ghostty, Kitty)
• Ensure the terminal is at least 80x24
• Enable UTF-8 support

Model not responding

• Check provider status pages
• Try a different model from the same provider
• Switch to an alternative provider as a control

What's next

Read the CLI Tools Overview to compare OpenCode, Claude Code, and Antigravity CLI. Choose the right tool for your workflow.

External references

• OpenCode documentation
• OpenCode GitHub repository
• Google AI Studio
• Anthropic Console
• DeepSeek Platform