# OpenCode: First Session with the Coding Agent

> Install the OpenCode CLI, connect a cloud or local Ollama model, open a project, give the agent a task, and compare it to Claude Code and Cursor.

- Canonical: https://guides-ai.com/guides/opencode-first-steps/
- Plate 14.07 · Topic: Other coding agents (https://guides-ai.com/topics/agents/)
- Published: 19 Oct 2026 · 3 min read
- Source site: guides-ai — https://guides-ai.com/

OpenCode is an open-source coding agent that lives in your terminal: it reads your repo, edits files, and runs commands, driven by whatever model you point it at. Unlike Claude Code it is provider-agnostic, so the same agent runs on a cloud API or a local model. Everything below follows the [official docs](https://opencode.ai/docs).

## 1. Install the CLI

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

That script puts `opencode` on your PATH; a package manager works too, via `npm install -g opencode-ai`. Confirm with `opencode --help`.

## 2. Start it in your project

```bash
cd /path/to/project
opencode
```

Running `opencode` opens the terminal UI rooted at your repo; run `/init` once so the agent scans the code and writes an `AGENTS.md` context file you commit to Git.

## 3. Connect a provider or local model

```text
/connect
```

`/connect` walks you through signing in and pasting an API key (stored in `~/.local/share/opencode/auth.json`); `/models` then lists the 75+ providers OpenCode supports via models.dev. To run fully local against [Ollama](/guides/run-local-llm-ollama-macos-linux/), add it as a custom provider in `opencode.json`:

```json
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Ollama (local)",
      "options": { "baseURL": "http://localhost:11434/v1" },
      "models": { "llama2": { "name": "Llama 2" } }
    }
  }
}
```

Point `baseURL` at your Ollama server and list each pulled model; if tool calls misbehave, raise Ollama's `num_ctx` to 16k-32k.

## 4. Give the agent a task

With a model selected, type a request in plain language, such as "add a /health endpoint and a test for it". OpenCode proposes file edits and shell commands and waits for your approval before acting, the same review-first loop as terminal agents like [Aider](/guides/aider-first-steps/).

## 5. How it compares to Claude Code and Cursor

Claude Code is a terminal agent tied to Anthropic's models; Cursor is a GUI editor with an agent built in. OpenCode keeps the terminal workflow but stays open-source and model-agnostic, so you can swap a frontier API for a local model in place. For the editor-versus-terminal trade-off, see [Claude Code vs Cursor](/guides/claude-code-vs-cursor/).

## If it fails

- **`opencode: command not found`** The install location is not on your PATH. Reopen the shell, or put npm's global bin folder on your PATH.
- **No models listed or an authentication error** You have not connected a provider. Run `/connect` for an API key, or for Ollama confirm `ollama serve` is running and the model pulled.
- **The agent ignores tools or loops with a local model** Small models drop tool calls. Pick a tool-capable model and raise `num_ctx` (start at 16k).

---

Next: [Aider first steps](/guides/aider-first-steps/) · [Codex CLI first steps](/guides/codex-cli-first-steps/) · [Claude Code vs Cursor](/guides/claude-code-vs-cursor/).