OpenCode From Zero to Pro: A Grounded Setup Guide for Professional AI-Assisted Coding

A hype-free guide for turning a plain OpenCode install into a professional coding environment. Based on practitioner research from Data Leads Future, DEV.to, and Medium, plus real-world testing. Last updated: 2026-07-29.

If you've looked into AI coding agents recently, you've seen the noise. Everyone has an opinion. Everyone has a plugin stack. Everyone is selling something.

This guide isn't that. It's what we found after reading everything, testing the claims, and stripping away what doesn't matter. It starts from a completely vanilla OpenCode install — no plugins, no MCP servers, no skills — and builds up to a professional setup that works for real projects.

What Is OpenCode?

OpenCode is an open-source AI coding agent built by the team at SST (Anomaly Innovations). It's MIT-licensed, written in Go, and supports over 75 LLM providers. In under a year it crossed 160,000 GitHub stars with no marketing team and no subscription requirement — just developers telling other developers.

Architecturally, it runs as a persistent client-server model. A background server handles AI communication and session state in a local SQLite database. The frontend — terminal TUI, desktop app, or IDE extension — connects to it. This means sessions survive SSH drops and terminal closures. Reconnect, and the server is still running mid-task.

Two built-in modes: Build (full tool access — reads, writes, runs commands) and Plan (read-only analysis that produces execution plans). Available for VS Code, Cursor, Zed, and as a standalone Desktop app.

1. Installation

One-Command Install

OpenCode relies on bun as a runtime dependency. The install is a single command:

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

If your environment blocks the automatic install, install bun first:

npm install -g bun

Then retry, or install manually from opencode.ai.

What You Get

• opencode CLI — terminal TUI built with Bubble Tea, completely keyboard-driven
• OpenCode Desktop — standalone graphical app (recommended for daily use)
• VS Code / Cursor / Zed extensions — available through each editor's extension marketplace

Desktop vs TUI: The desktop app supports Workspaces (git worktrees for parallel development branches), which the TUI doesn't. Install both — some plugins check for the OpenCode command during initialization.

Verify

opencode --version

Current version: 1.15+.

2. Provider Configuration (Critical)

This is the single most common setup mistake, and it quietly breaks things in ways that are hard to diagnose.

The Wrong Way

You open OpenCode, your model isn't in the default list, so you click "Custom provider" and fill in:

• Model ID
• Base URL
• API key

Why this breaks things: OpenCode now has no metadata about your model. It doesn't know the context window size, the pricing, or the capabilities. Features like automatic context compression, token budgeting, and smart model selection stop working because they rely on that metadata.

The Right Way

1. Open OpenCode Desktop → Settings → Providers
2. Scroll to the bottom of the provider list
3. Click "Show more providers"
4. Find your actual provider (OpenRouter, Together, Fireworks, Anthropic, etc.)
5. Enter that provider's API key

Once configured this way, all models from that provider appear with full metadata — context size, pricing, everything.

Finding Your Provider ID

OpenCode stores provider configuration at:

~/.local/share/opencode/auth.json

Open that file to find your provider ID and API key. You'll need the provider ID if you later configure custom agents.

Free Models (No API Key Needed)

OpenCode currently offers several free models:

• Big Pickle — a stealth model available free
• DeepSeek V4 Flash — efficiency-optimized MoE (284B total, 13B activated), strong coding performance
• Nemotron 3 Super — NVIDIA's hybrid MoE (120B, 12B activated)

These are limited-time offers. Check opencode.ai for current availability.

Recommended Paid Providers

3. AGENTS.md — Your Long-Term Memory

This is the single most impactful thing you can do for your OpenCode setup. It's called "Rules" in the UI, but it's really the project's long-term memory.

What AGENTS.md Does

1. Locks in project facts. Without AGENTS.md, every new session makes the LLM scan the entire project from scratch. AGENTS.md tells it directly: "This project uses X stack, Y conventions, Z dependency manager."

2. Narrows probability distributions. LLMs generate probabilistically. When a method parameter can be Optional[int] or int | None, the LLM picks one at random. AGENTS.md saying "always use int | None" shifts the probability to 100%. No more random variation.

3. Prevents dependency mistakes. If you use uv with --prerelease=allow, write that in AGENTS.md. The LLM will not fall back to pip install.

Creating AGENTS.md

In OpenCode, run the /init command. The AI analyzes your project and generates a baseline. Then edit it manually.

What a Good AGENTS.md Contains

# Project Overview

Eva is a personal AI assistant platform. Monorepo with:
- Python backend (FastAPI) in /backend
- React + TypeScript frontend in /frontend
- MCP server plugins in /mcp-servers

# Technology Stack

- Python 3.14+ with async/await throughout
- React 19 + Tailwind CSS 4 for UI
- Bun as the JavaScript runtime

# Commands

- `uv sync --prerelease=allow` — sync Python dependencies
- `bun install` — install frontend dependencies
- `pytest` — run Python tests

# Coding Conventions

- Type hints: always use `str | None`, never `Optional[str]`
- Imports: standard library first, then third-party, then local
- Async: use `async def` for all I/O-bound functions

Where It Lives

<project-root>/AGENTS.md

OpenCode reads it automatically. Refresh it after significant architecture changes by running /init again.

4. Plan vs Build: Using the Two Built-in Agents

Vanilla OpenCode comes with exactly two agents. Using them correctly is the difference between frustration and flow.

Build Agent (Default)

• Full tool access: reads, writes, executes
• Use when: You have a clear, unambiguous task
• Don't use when: The task is complex or ambiguous — it will start coding based on its own interpretation without verifying with you

Plan Agent

• Read-only mode. Cannot edit any files.
• Asks clarifying questions about requirements
• Produces an execution plan

The Professional Workflow

Every new requirement → Start with Plan agent → Get execution plan →
Save plan as .md file → Start fresh session → Load plan with Build agent

Why This Matters

Beginners go straight to Build. Then they wonder why the agent makes architectural mistakes, works on the wrong thing, or gets confused halfway through.

Plan then Build is the foundational discipline. It's the same principle as writing a spec before writing code.

5. Planning Workflow Mode (v1.15+)

Starting from v1.15, the Plan agent has an experimental planning workflow mode that automates this flow without any plugins.

Enable It

export OPENCODE_EXPERIMENTAL_PLAN_MODE=true

Add it to your shell profile (~/.bashrc or ~/.zshrc).

The 5 Phases

Where Plan Files Are Saved

• With a git repo: <project>/.opencode/plans/<timestamp>-<slug>.md
• Without a git repo: ~/.local/share/opencode/plans/<timestamp>-<slug>.md

Pro Tip

Configure the explore sub-agents with a cheaper model (DeepSeek-V4-Flash) to save tokens on codebase analysis. Let the Plan agent itself use your primary model.

6. Workspaces — Parallel Development

The Desktop app has a hidden superpower: Workspaces, built on git worktrees.

What It Solves

In traditional AI coding, you wait while the agent works. With workspaces, you can run multiple agents in parallel on different features — each in their own git branch and directory.

How to Enable

1. Open your project in OpenCode Desktop
2. Right-click the project icon in the top-left corner of the window
3. Select "Enable Workspace" from the context menu

(It's intentionally hidden to avoid clutter. Not in the main menu.)

Real-World Use

Workspace 1: "Fix auth token refresh bug" → agent is working
Workspace 2: "Add new API endpoint" → agent is working
Workspace 3: "Write tests for payment module" → agent is working
You: Review PRs as they come in

7. Session Discipline

This is the least technical and most important practice.

The Problem: Context Rot

LLMs have two well-documented biases:

• Primacy bias: They pay more attention to the beginning of context
• Recency bias: They pay more attention to the end

The middle of a long session? Noise. Even with OpenCode's context compression, quality degrades over time.

The Rule

After each major milestone, start a new session.

Not after every prompt. After:

• Planning is complete (start new session for coding)
• A feature is implemented (start new session for next feature)
• Code review is done (start new session for fixes)

How It Looks

Session 1: Plan agent — clarify requirements, produce plan file → CLOSE
Session 2: Build agent — load plan, implement feature A → CLOSE
Session 3: Build agent — implement feature B → CLOSE
Session 4: Review agent — review all changes → CLOSE

Each session is focused, has a single purpose, and fits in the model's effective context window.

8. Custom Commands and Agents

OpenCode lets you define custom slash commands and agents using plain Markdown files. No plugin architecture, no compilation.

Custom Commands

Create a file at .opencode/commands/<name>.md:

---
name: goal
description: Start a new coding task with autonomous execution
agent: goal-orch
---

Run /goal to start a new development task.

The user said: $ARGUMENTS

First, clarify the requirements. Then break them down into
atomic requirements and execute them one by one.

The $ARGUMENTS placeholder is replaced with whatever the user types after the command.

Custom Agents

Place agent definitions at:

• Global: ~/.config/opencode/agents/<name>.md
• Project: <project>/.opencode/agents/<name>.md

---
description: Code reviewer — reviews changes for bugs and architectural issues
mode: subagent
model: anthropic/claude-sonnet-4-6
tools:
  write: false
  edit: false
  bash: false
---

You are a code reviewer. Review the implementation against the requirements
in the plan file. Check for:
1. Does the implementation match the requirements?
2. Are there any edge cases not handled?
3. Are there performance issues?
4. Is the code consistent with AGENTS.md conventions?

Sub-agents communicate with primary agents via the task tool. The first call creates a sub-session, subsequent calls with the same task_id resume it.

9. The Full Daily Workflow

Here's what a professional session looks like from start to finish:

Morning: Sync & Plan

1. git pull to sync with team
2. Pick highest-priority task
3. OpenCode → Plan agent → describe the task
4. Let Plan explore the codebase, ask clarifying questions
5. Review the plan, approve it
6. Plan writes a .md plan file

Execution: Build

1. Start a fresh session
2. Switch to Build agent
3. Load the plan file: "Execute the plan in .opencode/plans/2026-07-29-task.md"
4. Agent implements, runs tests, reports completion
5. Review changes
6. Run full test suite

Review: Close the Loop

1. Run Code Review sub-agent on changes
2. Fix any issues
3. Create PR / commit
4. Close the workspace (auto-cleans branch and directory)

Discipline Checklist

• Started with Plan agent?
• Saved plan as .md file?
• Started fresh session for coding?
• AGENTS.md updated with any new architecture decisions?
• Tests pass?
• Workspace cleaned up?

10. Cost Expectations

OpenCode is BYOK (Bring Your Own Key). There's no subscription lock-in.

OpenCode Go is an optional $10/month subscription that gives you one API key and access to a curated set of tested models. Worth it if you don't want to manage API keys.

Bottom line: Even with Claude Opus 4.7 at heavy use, you're looking at $30–80/month. Compare that to Claude Code Max at $100–200/month for the same model quality.

11. What Comes Next

The setup above handles most professional work. When you hit its limits, here's the progression path:

Stage 2: OpenSpec (Spec-Driven Development)

Add formal spec-driven development on top of vanilla. Every feature goes through:

explore → propose → apply → verify → archive

Proposals include: proposal.md, design.md, tasks.md, .openspec.yaml. Installed via npm install -g openspec.

Stage 3: Reflection

Add a reflection agent between "propose" and "apply" phases that uses a different LLM than your main agent. Different models have different blind spots — this catches requirements-level bugs before any code is written.

Stage 4: Loop Engineering

Build a /goal command that creates an automated coding loop:

• Orchestrator agent breaks task into atomic requirements
• Worker agents implement each with tests
• DAG-based parallel execution
• Only reports back when everything passes

When to Consider Claude Code / Conductor

If you need the 29-hook governance system for enterprise compliance, Agent Teams with inter-agent communication, or macOS-native Conductor for parallel worktree orchestration — Claude Code Max at $100–200/month is the alternative. But the skills and discipline you build with OpenCode transfer directly.

Quickstart Checklist

• Installed OpenCode CLI + Desktop
• Configured provider via "Show more providers" (not Custom provider)
• Ran /init to create AGENTS.md, then edited it manually
• Enabled Planning Workflow Mode: OPENCODE_EXPERIMENTAL_PLAN_MODE=true
• Tested Plan agent → saved plan → fresh session → Build agent flow
• Created at least one custom agent in ~/.config/opencode/agents/
• Found auth.json at ~/.local/share/opencode/auth.json
• Tried Workspaces (right-click project icon)
• Established session discipline (fresh session per milestone)

This guide is based on practitioner research from Data Leads Future, DEV.to, and Medium, combined with hands-on testing with the OpenCode platform. It will be updated as the tool evolves.