OpenCode cheat sheet

A scannable OpenCode reference: 31 short snippets across 13 topics, each linking back to the lesson it came from.

At a glance

Quick snippets

What OpenCode is

An agent in the terminal

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-5",
  "permission": {
    "edit": "ask",
    "bash": "ask"
  },
  "mcp": {
    "context7": { "type": "remote", "url": "https://mcp.context7.com/mcp" }
  }
}

Full lesson: What OpenCode is →

Install and first session

Install and authenticate

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

# or with a package manager
npm install -g opencode-ai
brew install sst/tap/opencode

# verify the binary is on your PATH
opencode --version

Install and authenticate

# pick a provider and paste the API key when prompted
opencode auth login
opencode auth list

Your first session

cd ~/projects/my-app
git status                 # a clean tree is a safe place to experiment
opencode                   # opens the terminal interface

# inside the session
/init                      # scan the project and write an AGENTS.md

Full lesson: Install and first session →

Workflow tips and limits

A workflow that holds up

# AGENTS.md

## Commands
- Test: npm test -- --runInBand
- Lint: npm run lint
- Build: npm run build

## Rules
- Never edit files under generated/ - they are rebuilt.
- Use the project logger, not console.log.
- Add or update a test with every behaviour change.

Full lesson: Workflow tips and limits →

Choosing and configuring model providers

Authenticating a provider

# interactive provider picker; stores credentials outside the repo
opencode auth login

# see what is configured, without printing the keys
opencode auth list

# remove one
opencode auth logout

The configuration file

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-5",
  "small_model": "anthropic/claude-haiku-4-5",
  "autoupdate": true,
  "share": "manual"
}

Different models for different jobs

# override for a single non-interactive run
opencode run --model openrouter/deepseek/deepseek-chat "summarise the diff"

# switch inside the TUI
/models

Full lesson: Choosing and configuring model providers →

Running local models with Ollama and LM Studio

Wiring a local endpoint

# Ollama: pull something and start the server
ollama pull qwen2.5-coder:7b
ollama serve            # listens on http://localhost:11434

# LM Studio: load a model in the GUI, start the local server
# it listens on http://127.0.0.1:1234 by default

Cost, privacy and speed

# keep the model resident so the first call is not a load
OLLAMA_KEEP_ALIVE=30m ollama serve

# a quick throughput check before you commit a workflow to it
curl -s http://localhost:11434/api/generate -d '{
  "model": "qwen2.5-coder:7b",
  "prompt": "print hello",
  "stream": false
}' | head -c 200

Full lesson: Running local models with Ollama and LM Studio →

Plan mode versus build mode

Two agents, two postures

# in the TUI
<Tab>            # toggle between the build and plan agents

# or pick explicitly
/agent/build
/agent/plan

A plan-first workflow

> [plan] Add rate limiting to the public API.

Expected shape of the answer:
1. The files it will touch and why
2. Where the counter lives and how it resets
3. What happens when Redis is unavailable
4. Which existing tests need updating
5. What it will NOT change

Then stop. Do not edit anything.

Tuning the agents

opencode run --agent plan "list the files that would need to change to add pagination"

Full lesson: Plan mode versus build mode →

Project context and instruction files

Initializing and where files live

# from the project root, inside a session
/init
# OpenCode inspects the repository and writes an AGENTS.md you then edit

# global guidance, applied to every project
~/.config/opencode/AGENTS.md

# project guidance, committed with the repository
./AGENTS.md

Nested context files

packages/core/AGENTS.md

# Core package rules

- Pure TypeScript only. No Node built-ins beyond node:assert in tests.
- Public API is whatever src/index.ts exports; everything else is internal.
- Adding an export is a breaking-change review, not a refactor.
- Money is integer minor units with an explicit currency. Never a float.

Pulling in existing documentation

{
  "$schema": "https://opencode.ai/config.json",
  "instructions": [
    "CONTRIBUTING.md",
    "docs/architecture.md",
    "docs/api/*.md"
  ]
}

Full lesson: Project context and instruction files →

Sessions, snapshots and undo

Sessions are local and resumable

# inside the TUI
/new             # start a fresh session
/sessions        # list and switch between sessions
/export          # dump the current conversation to markdown
/share           # create a link (only if sharing is enabled)

# from the shell
opencode run -c "now add a test for the case we just discussed"   # continue the latest
opencode run --session <id> "and update the changelog"

Snapshots and undo

# in the TUI
/undo            # revert the last change set
/redo            # put it back if you changed your mind

# the underlying safety net is still git
git status --short
git stash push -m "before agent experiment"

Running sessions in parallel

# two terminals, one repository, two independent tasks
# terminal A
opencode run "add pagination to the orders endpoint"

# terminal B - a different area of the tree
opencode run "upgrade the test runner and fix the fallout in tests/"

# a headless server one client can attach to
opencode serve --port 4096

Full lesson: Sessions, snapshots and undo →

Code intelligence with language servers

Automatic detection

# check which servers are running in a session
/lsp

# the same information appears in the log output
opencode run --print-logs "add a required field to the Order type and fix the fallout"

When the server misleads

# reproduce what the agent sees, outside the agent
npx tsc --noEmit
npx tsc --noEmit -p packages/core/tsconfig.json

# if the compile is clean but the agent insists otherwise, the server
# is reading a different project - that is a config problem, not a code one

Full lesson: Code intelligence with language servers →

MCP servers and custom tools

Every tool has a context price

# how much context is in play right now
/context

# a rough comparison: connect one server, measure, connect another, measure
opencode run "how many tools do you currently have available?"

Scoping and troubleshooting

{
  "mcp": {
    "postgres": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-postgres"],
      "environment": { "DATABASE_URL": "{env:DATABASE_READONLY_URL}" }
    }
  },
  "permission": {
    "bash": { "*": "ask", "git status*": "allow" }
  }
}

Full lesson: MCP servers and custom tools →

Skills, plugins and custom commands

Custom commands

---
description: Add a database migration with a matching down migration
agent: build
---

Create a migration for: $ARGUMENTS

Requirements:
- Generate it with the project's migration tool, never by hand.
- The down migration must be exact, not a no-op.
- Update the schema snapshot afterwards.
- Run the migration test suite and show the output.

Custom commands

.opencode/command/migrate.md     ->  /migrate add a unique index on users.email
~/.config/opencode/command/     ->  available in every project

# the body supports the same injections as the prompt
$ARGUMENTS   # everything typed after the command
!git diff    # output of a shell command, inlined
@src/db.ts   # contents of a file, inlined

Plugins and sharing a setup

// .opencode/plugin/audit-edits.js
export const AuditEdits = async ({ project, client, $, directory }) => ({
  "tool.execute.after": async (input, output) => {
    if (input.tool !== "edit" && input.tool !== "write") return;
    await client.app.log({
      body: { service: "audit", level: "info", message: "edited " + input.args.filePath },
    });
  },
});

Full lesson: Skills, plugins and custom commands →

Permissions, privacy and secret handling

What stays local and what does not

{
  "$schema": "https://opencode.ai/config.json",
  "share": "manual"
}

Keeping secrets out of the conversation

# AGENTS.md

## Never
- Never read or print .env, *.pem, secrets/* or anything matching *_key.
- Never commit a value that looks like a credential.
- If a task needs a secret, reference the environment variable name only.

Full lesson: Permissions, privacy and secret handling →

Headless mode, the SDK and CI

Non-interactive runs

# one task, then exit
opencode run "summarise the changes in the working tree"

# continue the previous session with a follow-up
opencode run -c "now write the changelog entry"

# constrain the run
opencode run --agent plan --model anthropic/claude-haiku-4-5 \
  "list the files that import the deprecated client"

# keep the server running so several clients can attach
opencode serve --port 4096

The HTTP API and SDKs

opencode serve --port 4096
# then, from anywhere on the same host
curl -s http://localhost:4096/session | head -c 400

A review job

# run the same job locally before trusting it in CI
docker run --rm -v "$PWD:/work" -w /work \
  -e ANTHROPIC_API_KEY node:22 \
  sh -c "npm install -g opencode-ai && opencode run --agent plan 'summarise the diff'"

Full lesson: Headless mode, the SDK and CI →

FAQ

Related cheat sheets

AI Basics AI Agents Math for AI Machine Learning scikit-learn TensorFlow

Last refreshed 2026-09-27.