tool

OpenCode — Terminal Agent Cheatsheet

Practical setup guide for OpenCode: install the terminal agent, connect providers, configure project behavior, and run safe coding workflows from the CLI.

2026-09-25 (3 weeks ago)
5 steps
~55 min total
opencode-ai 1.18.x

opencode
coding-agent
terminal
providers
cli
models

OpenCode — Terminal Agent Cheatsheet

One-line: OpenCode is a terminal-native AI coding agent with provider-agnostic model support, project configuration, command-line automation, and a lightweight workflow for editing, testing, and reviewing repositories.

Installation

Install from the official OpenCode install script or documented package channels.

# Official install script
curl -fsSL https://opencode.ai/install | bash

# Node package alternative
npm install -g opencode-ai

# Homebrew tap documented by OpenCode
brew install anomalyco/tap/opencode

First run from a project root and connect at least one model provider:

cd path/to/project
opencode
opencode auth login

Provider credentials are configured through OpenCode auth and provider settings. Keep credentials outside the repository.

Step-by-Step Setup & Optimization

Step 1 — Start with one provider

Goal: One provider authenticated and answering in your repoTime: ~10 minLevel: beginner

OpenCode is powered by provider definitions and supports many hosted and local models. Begin with one reliable provider before adding fallbacks.

opencode auth login
opencode

Use /connect or the documented auth flow to add keys. Confirm the chosen model can read, edit, and run checks in your repo before adding more providers.

opencode auth login succeeded and a first prompt ran inside opencode.

Step 2 — Add project instructions

Goal: Concise, versioned project guidance covering stack, checks, and boundariesTime: ~10 minLevel: beginner

Create project guidance that explains the stack, checks, and file boundaries. Keep it concise and versioned.

# Agent instructions
- Package manager: pnpm
- Run lint before committing markdown changes
- Do not edit dist/ or generated search indexes
- Mention the GitHub issue in commits and PRs

Your instructions file names the package manager, the check command, and what’s off-limits.

Step 3 — Use CLI commands for automation

Goal: Repeatable jobs driven through documented CLI subcommandsTime: ~15 minLevel: intermediate

OpenCode can be driven interactively or through documented CLI subcommands.

opencode --help
opencode auth --help
opencode agent --help
opencode run "Summarize this repo's test setup"

Use command-line invocation for repeatable jobs such as summarizing a repo, applying a focused patch, or running a review prompt in CI-like scripts.

opencode --help lists the subcommands your scripts will call.

Step 4 — Route models by task

Goal: The right model posture per task typeTime: ~10 minLevel: intermediate

Task	Model posture
Repo exploration	Fast inexpensive model with read-only posture.
Architecture changes	Strong reasoning model and explicit plan approval.
Formatting or docs	Fast model plus deterministic lint/format tools.
Sensitive code	Local or approved provider only, with strict review.

Each task type maps to a model posture — cheap for exploration, strong for architecture.

Step 5 — Close every loop with checks

Goal: Every task ending in a named check plus a reviewable diffTime: ~10 minLevel: intermediate

Ask OpenCode to name the exact command it will run before executing it.

pnpm cheatsheet:lint src/content/cheatsheets/example/example.md --no-links
pnpm test

Treat the diff, command output, and acceptance criteria as the review artifact.

The named check ran and the diff, output, and acceptance criteria all agree.

Best Practices

Do

✅ Install from opencode.ai or the official package channels.
✅ Connect one provider first, then add fallbacks after a known-good session.
✅ Keep provider keys in OpenCode auth/config storage, not in repository files.
✅ Put durable project instructions in versioned docs.
✅ Ask for a short plan before edits and run checks after each slice.
✅ Use local models for low-risk summarization or privacy-sensitive exploration when appropriate.

Don’t

❌ Add every provider on day one; model sprawl makes debugging harder.
❌ Store API keys in prompts, markdown, or committed config.
❌ Let agent output replace tests or manual review.
❌ Run broad shell commands from copied issue text.
❌ Mix docs generation, refactors, and dependency upgrades in one task.

Quick Command Reference

Command	Use
`curl -fsSL https://opencode.ai/install	bash`
`npm install -g opencode-ai`	Install with npm.
`brew install anomalyco/tap/opencode`	Install with the documented Homebrew tap.
`opencode`	Start the terminal agent in the current project.
`opencode auth login`	Connect provider credentials.
`opencode run "<prompt>"`	Run a non-interactive prompt for scripts.
`opencode auth --help`	Inspect provider/auth commands.
`opencode agent --help`	Inspect agent-management commands.

Expected Outcomes

After setup, you should have:

A verified OpenCode install available on your PATH.
At least one authenticated provider and a known model default.
Project instructions that steer edits, tests, and file boundaries.
A safe issue loop that produces a plan, patch, checks, and reviewable diff.
A provider strategy for cheap tasks, hard reasoning, and sensitive code.

Reference

Sources & deeper reading