Getting Started with OpenCode: Terminal‑First AI Coding Assistant

OpenCode Overview

OpenCode is an open‑source AI coding agent that follows a “terminal‑first, agent‑based coding” approach while remaining provider‑agnostic. It provides a workflow layer that can launch a terminal UI, run non‑interactive prompts, expose a headless HTTP server (with optional Web UI), and be controlled programmatically via the official JavaScript/TypeScript SDK @opencode-ai/sdk.

Prerequisites

Modern terminal emulator (required for the TUI experience).

Access to at least one LLM provider (API key or subscription).

Installation

Run the official install script (Linux/macOS/WSL): curl -fsSL https://opencode.ai/install | bash Package‑manager alternatives:

# Node.js global install
npm install -g opencode-ai

# Homebrew (recommended for latest release)
brew install anomalyco/tap/opencode

# Arch Linux (stable)
sudo pacman -S opencode

# Arch Linux (AUR – latest)
paru -S opencode-bin

Windows (recommended via WSL) – alternative package managers:

# Chocolatey
choco install opencode

# Scoop
scoop install opencode

Docker quick try:

docker run -it --rm ghcr.io/anomalyco/opencode

Verification

opencode --version
opencode --help

The commands should display the version number and a list of sub‑commands.

Connecting a Provider

Two practical methods:

Interactive TUI : start OpenCode and run the built‑in /connect command. Follow the UI prompts to select a provider and complete authentication (some flows open a browser).

CLI (non‑interactive) : run opencode auth login. Credentials are stored in ~/.local/share/opencode/auth.json. OpenCode can also read keys from environment variables or a .env file.

Project Initialization

From the repository root:

cd /path/to/your/repo
opencode
/init

The /init command analyses the codebase and creates an AGENTS.md file that can be committed to share project context.

Core CLI Workflows

Non‑interactive generation :

opencode run "Explain how closures work in JavaScript"

Generate a Go function with tests :

opencode run "Write a Go function ParsePort(envVar string, defaultPort int) (int, error) that reads an env var, parses an integer, validates 1‑65535, and returns defaultPort when empty. Include three table‑driven tests."

Safe refactoring with the plan agent :

opencode run --agent plan --file ./src/auth.ts \
  "Refactor this file to reduce complexity. Output: (1) a short plan, (2) a unified diff patch, (3) risk/edge‑case checklist. Do not execute commands."

Repository exploration :

opencode run --agent explore \
  "In this repo, where is API request authentication verified? List possible files and explain the flow. If unsure, describe what you checked."

Persistent headless server for repeated calls :

# Terminal 1
opencode serve --port 4096 --hostname 127.0.0.1

# Terminal 2
opencode run --attach http://localhost:4096 "Summarize the repository structure and main entry points."
opencode run --attach http://localhost:4096 "Propose three high‑impact refactoring suggestions with rationale."

Programmatic Usage (JS/TS SDK)

Install the SDK: npm install @opencode-ai/sdk Example script (e.g., scripts/opencode-sdk-demo.mjs) that starts the server, checks health, creates a session, prompts for a README snippet, and shuts down:

import { createOpencode } from "@opencode-ai/sdk";

const opencode = await createOpencode({
  hostname: "127.0.0.1",
  port: 4096,
  config: {
    // model: "provider/model" – replace with your LLM
  },
});

console.log(`Server running at: ${opencode.server.url}`);

const health = await opencode.client.global.health();
console.log("Health:", health.data.healthy, "Version:", health.data.version);

const session = await opencode.client.session.create({ body: { title: "SDK demo" } });
const result = await opencode.client.session.prompt({
  path: { id: session.data.id },
  body: { parts: [{ type: "text", text: "Generate a short README section describing this repository." }] },
});
console.log(result.data);

opencode.server.close();

Run with node scripts/opencode-sdk-demo.mjs. Expected output includes the server URL, a health‑check response, and the session’s response object.

Minimal Configuration (JSONC)

Create opencode.jsonc at the repository root:

{
  "$schema": "https://opencode.ai/config.json",
  "model": "provider/model",
  "small_model": "provider/small-model",
  "server": { "port": 4096, "hostname": "127.0.0.1" },
  "permission": { "edit": "ask", "bash": "ask" }
}

Quick Reference

Common commands:

opencode                     # launch TUI
opencode run "..."           # non‑interactive run
opencode run --file path "..." # attach a file to the prompt
opencode models --refresh    # refresh model list
opencode auth login          # configure provider credentials
opencode serve               # start headless HTTP server (OpenAPI)
opencode web                 # start server + Web UI
opencode session list        # list sessions
opencode stats               # token/cost statistics

Key TUI shortcuts (leader key defaults to ctrl+x):

/connect   # connect a provider
/init      # analyze repo, generate AGENTS.md
/share     # share a session (if enabled)
/undo      # undo last change
/redo      # redo undone change
/help      # show help / shortcuts

References

OpenCode quick‑start: https://www.glukhov.org/ai-devtools/opencode/ AI developer tools ecosystem overview:

https://www.glukhov.org/ai-devtools/