Agentic AI Tools

OpenCode Setup Guide

Set up OpenCode, a multi-provider terminal agent for comparing models and running repeatable research workflows.

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

Reference page for: OpenCode installation, provider setup, and model-comparison workflows. Other pages link here when the research task requires varying the model while keeping the CLI constant.

Overview

OpenCode is an open-source, multi-provider terminal agent. Its main research value is keeping the tool constant while you vary the model or provider, which makes it useful for model-selection experiments.

Unlike a single-provider agent, OpenCode lets you send the same prompt to Claude, GPT, Gemini, DeepSeek, Kimi, or local models without changing your workflow. The trade-off is that you are responsible for configuring each provider and for choosing the right model for the task.

Info

Why OpenCode for research? Model independence is a methodological lever. When you hold the interface, context, and prompt constant and change only the model, the differences you observe are more likely to be model differences than interface differences.

Official resources:

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

OpenCode Zen is a curated model list managed by the OpenCode team. 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

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

Common research providers:

Anthropic — Claude Opus 4.8, Sonnet 4.6, 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

Warning

Model names and availability change quickly. Before pinning a model in a research workflow, verify the model ID against the provider's current list. See the AI Model Reference Guide for the broader landscape.

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/?

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.

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

Example:

[Claude Sonnet 4.6]
"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:

Screening — DeepSeek or Gemini Flash/Lite for initial filtering
Extraction — Kimi K2.6 or a mid-range model with good structured output
Synthesis — Gemini 3.5 Flash or Gemini 3.1 Pro preview for large-context synthesis
Final argument — Claude Opus 4.8 or Sonnet 4.6 for theoretical framing

Track costs in each provider's dashboard. Logging which model handled each task makes it easier to optimize later.

Integration with Research Memex

Zotero → OpenCode

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

OpenCode → Obsidian or Zettlr

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

Comparison with other CLIs

Feature	OpenCode	Claude Code	Antigravity CLI
Provider scope	Many providers	Anthropic	Google Antigravity/Gemini paths
Cost shape	Per-provider API usage	Subscription or API, depending on plan	Google account or enterprise path
Interface	Terminal UI	Standard CLI	Standard CLI
Open source	Yes (MIT)	No	Product-managed CLI
Best for	Model experimentation	Deep project work	Google terminal-agent continuity

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 is often where a model fails, not where it succeeds.
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

OpenCode's natural companion is the CLI Tools Overview, which compares OpenCode against Claude Code and Antigravity CLI so you can choose deliberately.