# OpenCode Setup Guide

URL: https://research-memex.org/docs/implementation/agentic-ai-tools/opencode-setup-guide
Description: Set up OpenCode, a multi-provider terminal agent for comparing models and running repeatable research workflows.



<GuideMeta>
  Intermediate · 15–20 min · provider API keys or OpenCode Zen account
</GuideMeta>

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

## Overview [#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.

<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.
</Info>

Official resources:

* [OpenCode website](https://opencode.ai/)
* [GitHub repository](https://github.com/anomalyco/opencode)
* [OpenCode documentation](https://opencode.ai/docs)

## Install [#install]

### Prerequisites [#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:

```bash
node --version
```

### Installation options [#installation-options]

<CodeGroup>
  ```bash npm
  npm install -g opencode-ai
  ```

  ```bash Homebrew (tap)
  brew install anomalyco/tap/opencode
  ```

  ```bash Install script
  curl -fsSL https://opencode.ai/install | bash
  ```
</CodeGroup>

Verify the binary:

```bash
opencode --version
opencode --help
```

### First launch [#first-launch]

```bash
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 [#configure-providers]

### Option A: OpenCode zen [#option-a-opencode-zen]

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

```text
/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 [#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

<Warning>
  Model names and availability change quickly. Verify the model ID against the provider's current list before pinning a model in a research workflow. See the [AI Model Reference Guide](/docs/implementation/core-references/ai-model-reference-guide) for broader model-selection guidance.
</Warning>

## Basic interface [#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 [#referencing-files]

Use `@` to point to files or folders:

```text
Summarize @/literature/smith2024.md
```

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

```text
What methods appear most often across @/literature/?
```

### Sharing a conversation [#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 [#project-setup-for-research]

A minimal research project might look like this:

```text
/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 [#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:

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

```text
[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 [#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 [#integration-with-research-memex]

### Zotero → OpenCode [#zotero--opencode]

1. Export papers from [Zotero](/docs/implementation/foundational-setup/zotero-setup-guide).
2. Convert PDFs via the [OCR guide](/docs/implementation/ai-environment-setup/ocr-pdf-conversion-guide).
3. Load the markdown into an OpenCode project.
4. Run the same analysis prompt across multiple providers.

### OpenCode → Obsidian or Zettlr [#opencode--obsidian-or-zettlr]

1. Save markdown outputs from OpenCode.
2. Import them into [Obsidian](/docs/implementation/foundational-setup/obsidian-setup-guide) or [Zettlr](/docs/implementation/foundational-setup/zettlr-setup-guide).
3. Link insights to literature notes and add @citekeys.

## Comparison with other CLIs [#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 [#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 [#troubleshooting]

### `opencode: command not found` [#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 [#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 [#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 [#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 [#whats-next]

Read the [CLI Tools Overview](/docs/implementation/ai-environment-setup/cli-setup-guide) to compare OpenCode, Claude Code, and Antigravity CLI. Choose the right tool for your workflow.

### External references [#external-references]

* [OpenCode documentation](https://opencode.ai/docs)
* [OpenCode GitHub repository](https://github.com/anomalyco/opencode)
* [Google AI Studio](https://aistudio.google.com/)
* [Anthropic Console](https://console.anthropic.com/)
* [DeepSeek Platform](https://platform.deepseek.com/)