The Ultimate Beginner Guide to OpenCode
A complete masterclass on the open-source, model-agnostic AI coding platform — from first install to custom agents, MCP servers, and local models.
What is OpenCode?
OpenCode is an open-source, terminal-first AI coding agenttrusted by over 6.5M developers — with 140,000+ GitHub stars, 850 contributors, and 11,000+ commits. Unlike the competition, it doesn't lock you into a single model or provider.
VS Code with AI built in. Good — but paying for a separate subscription when VS Code now adds similar features natively is hard to justify.
Fast and great at large codebases with parallel agents. But you're locked into Anthropic — the $20 plan can push you to $100/month quickly with heavy use.
Reads and understands your project structure before writing — slower but more accurate for debugging. No model flexibility.
A layer on top of all tools. Open-source, terminal-first, also available as desktop app and IDE extension. Use Claude, GPT, Gemini, or local models — all in the same workflow. Even configure different models for different agents.
You're not choosing a tool — you're choosing how you want to work. Use a heavyweight model like GPT-5 for complex implementation and a faster, cheaper model like Claude Haiku for planning — all configured per agent.
Prerequisite Reality Check
OpenCode amplifies your knowledge — it doesn't replace it.If you know what to build, it builds faster. If you don't, it becomes trial and error. Even with AI, errors happen — you need to read logs, fix imports, and adjust logic.
Installation
Install via npm (recommended):
Also available via PNPM, Bun, Yarn, Chocolatey, Scoop, or Docker.
Verify and launch:
First launch — two modes:
- Plan Mode (Tab): AI explains what it's going to do — no file changes. Always start here for multi-file work.
- Build Mode (default): AI executes and modifies your code directly.
On first launch, the right panel shows Context: tokens used, percentage utilization, and cost so far. LSP (Language Server Protocol) runs automatically — OpenCode spins up the right language server (e.g., TypeScript LSP for .ts files) so the AI understands your types, dependencies, and structure, not just text.
Core Commands
These are the commands you'll use every session. Watch the video to see each one demonstrated live.
/initScans your folder and asks a few clarifying questions (project type, stack), then generates agent.md and boilerplate. Always run this on new projects.
@filenameThe most important command. Reference a specific file so the AI reads it before responding. e.g., "Refactor the function in @src/App.jsx to increment by +5." Way more efficient than describing file locations.
/undoReverts the last file change. Requires Git initialized in the repo (run git init first). Modified files are shown in the right panel.
/redoRe-applies an undone change.
/connectBring your own API key. Choose a provider (OpenAI, Anthropic, OpenRouter, GitHub Copilot) and paste your key. Automatically switches to the connected model.
/modelsView and switch models. Free models (Big Pickle, Minimax M2.5, Nemotron 3 Super) need no setup. Switch to Gemini, Anthropic, or local Ollama models anytime.
/sessionsSwitch between saved sessions. Rename a session (/rename), create a new one (/new), or share it publicly (/share — creates a link copied to clipboard). /unshare disables the link.
/themesChange the TUI theme — One Dark, Tokyo Night, Vercel, and more.
/compactSummarizes the entire conversation history into a dense paragraph. The AI still remembers project goals but thousands of tokens are freed. Use when the AI feels forgetful or after 20+ debugging messages.
/exit /q /quitQuit the TUI.
opencode.jsonc file to your project. Define commands like /review-recent or /document, specify which model to use, and set Build or Plan agent mode.Interfaces: TUI, Desktop, Web & IDE
Terminal UI (TUI)
- Default interface — launch with
opencode - Tab/Shift+Tab to navigate option lists
- Right panel shows context, tokens, modified files
- Switch agents with Tab key or @ mention
Desktop App
- Download .exe / .dmg / .deb from opencode.ai/download
- Supports all commands (/model, /compact, etc.)
- Multi-project support from the left panel
- Settings for theme, fonts, shortcut keys, and providers
Web App
Username: opencode. Set custom with OPENCODE_SERVER_USERNAME. Ideal for remote access over a network.
IDE Extension
- Search "OpenCode" in VS Code marketplace (by SST)
- Use directly from the integrated terminal
- ACP protocol: connects to Zed, JetBrains, Avante.nvim, CodeCompanion.nvim
- Run via
opencode acp— JSON-RPC over stdio
Environment Tiers: Free, Go & Zen
Big Pickle, Minimax M2.5, Nemotron 3 Super
No API key or account needed. Up to 1M tokens (input/output/cached) free for all three. Usage controlled by system load or IP caps — not a hard public limit. If rate-limited, try Go or Zen. Not recommended for production or sensitive data — prompts may be collected to improve models.
Flat-rate subscription for high-volume usage. Access to selected open-source models: GLM-5, Kimi K2.5, Qwen 3.5 Plus. Cheaper models (Qwen 3.5+) allow more requests per 5-hour window; higher-cost models (GLM-5.1) allow fewer. Open models like Gemma and Qwen are now on par with proprietary models for many coding tasks.
Access to GPT-5.2 Codex, Claude Haiku 4.5, and other premium models. Billed per 1M tokens — check the pricing charts in the video. Create account at opencode.ai/auth (Gmail or GitHub), enable billing, generate an API key, then type /connect and select OpenCode Zen.
Models: 75+ Providers, Full Control
Models are identified as provider_id/model_id — e.g., openai/gpt-5 or anthropic/claude-3-5-sonnet. OpenCode follows a strict priority order when selecting the active model:
Custom model config in opencode.jsonc:
- Add a provider block (e.g., openai, anthropic) with specific model IDs
- Configure thinking modes: minimal, low, medium, high — disable ones you don't need
- Create a custom
debug-modemodel with high reasoning effort + low text verbosity - Set temperature per agent: 0.0–0.2 for deterministic code analysis, 0.6–1.0 for brainstorming
Agents & Sub-Agents
Instead of one generic AI, you get focused assistants per job. Switch between primary agents with Tab, or call any agent with @agent-name.
Built-in Primary Agents:
Build (default)
Full tool access — edits files, runs commands, does complete development work.
Plan
Restricted agent. Explains what it will do, asks permission before file edits or bash commands. Use for analysis without risk of unintended changes.
Built-in Sub-Agents (call with @):
@General
Powerful, multi-purpose. Handles complex multi-step tasks and can make file changes.
@Explore
Fast, read-only. Searches your codebase and answers questions without modifying anything.
Custom agents in opencode.jsonc:
- Set
mode: primary(shows in Tab cycle) ormode: subagent(@ mention only) — omitting mode makes it both - Assign a different model per agent (e.g.,
qwen3.6-plusfor a low-cost document agent) - Set temperature per agent (0.1 for precise code generation, 0.8 for planning)
- Control permissions:
write: true/false,edit: true/false - Add descriptions and system prompts inline or from a referenced file
- Disable an agent with
disabled: true
Skills & Workflow Automations
Skills are reusable instructions defined once, used anytime. Instead of repeating the same prompts, create a skill — OpenCode discovers and loads it when the agent needs it. Skills are loaded only when needed, so having 50 skills adds near-zero overhead to every prompt.
How skills are stored
- Project-level:
.opencode/skills/skill-name/SKILL.md - Global (shared across all projects):
~/.opencode/skills/ - Each folder = one skill. The SKILL.md file contains the instructions.
How OpenCode finds them
- Scans from current directory upward to the git root
- Also checks global locations automatically
- Agents see what skills exist, pull full instructions only when needed
Example: React best-practice skills
- react-cleaner: Standardizes React component structure and hook usage patterns
- react-styler: Manages CSS-in-JS and Tailwind class consistency
- Configure frontend-coach agent to always apply these skills automatically
- Configure junior-developer agent to ask for confirmation before applying them
Other skill ideas: company security standards (block secret keys in commits), GitHub commit conventions (meaningful descriptions + tags), project-specific linting rules.
MCP Servers: Connect to External Tools
MCP (Model Context Protocol) lets you connect external tools to OpenCode — local or remote. Once added, they become available to your agents automatically. Important: every active MCP increases context size (more tokens, more cost). Only enable what you actually need.
Example: Analyze Git repo → save summary to Notion
Step 1 — Add Git MCP (local, reads commits and repo context):
"type": "local",
"command": ["npx", "-y", "@modelcontextprotocol/server-git"],
"enabled": true
}
Step 2 — Add Notion MCP (sends output to a real Notion page):
"type": "local",
"command": ["npx", "-y", "@modelcontextprotocol/server-notion"],
"enabled": true,
"environment": { "NOTION_API_KEY": "your-key" }
}
Then prompt: "Analyze the latest commits and save the summary to Notion." OpenCode reads the git log and writes to your Notion page directly. You can also use remote MCP servers instead of local npx commands for hosted setups.
Local Models: Ollama & OpenRouter
Option A — Ollama (local GPU/CPU models)
First response after cold start is slow (~1 min). After that, responses speed up. gemma4:e2b runs on 12–16 GB RAM with no GPU. For production quality, use Gemma 4 26B or cloud Ollama models (minimax m2.7 cloud — responses in 3–4s).
Option B — OpenRouter (free cloud models)
Many free models available — but they tend to be slower and often quantized. OpenCode Zen provider generally gives better performance-per-cost than calling OpenRouter directly.
Context & Cost Optimization
Use /compact regularly
When AI feels forgetful or after 20+ messages on the same issue. Frees thousands of tokens while keeping project goals intact.
Tiered model usage
Use a capable model (qwen-plus) for reasoning and logic, switch to a cheaper one (qwen-turbo) for simple edits. Turbo models are a fraction of the cost per token.
Only enable needed MCPs
Every active MCP adds extra instructions to every prompt — tokens are spent even when you're not using it.
Reference files with @filename
Don't describe file locations. Just @src/App.jsx — OpenCode pulls only the relevant parts, not the entire codebase.
Prefer opencode/ prefix
OpenCode Zen usually gives better performance for cost compared to calling OpenAI or Anthropic APIs directly.
Compact in opencode.jsonc
Add a custom compact instruction: "Focus on code changes and API shapes. Drop conversational back-and-forth." Keeps summaries tight.
Other Integrations
GitHub Integration
Mention /opencode or /oc in a GitHub issue or PR comment. OpenCode runs inside a GitHub Actions runner — triage issues, explain bugs, implement features, open pull requests. Set up with opencode github install.
Supports: issue comments, PR review comments, scheduled runs, manual workflow dispatches. Configure model, agent, prompt, sharing behavior, and token access in the workflow YAML.
LSP (Language Server Protocol)
OpenCode auto-starts the right language server when a matching file is opened (TypeScript, Python, Go, Java, Rust, PHP, and more). The AI understands your actual types, dependencies, and structure — not just text. Customize in the lsp config section: disable globally, disable specific servers, pass init options, or add custom servers for file types not in the built-in list.
ACP (Agent Client Protocol)
Runs OpenCode as an agent backend inside ACP-compatible editors via opencode acp (JSON-RPC over stdio). Supported in Zed, JetBrains IDEs, Avante.nvim, and CodeCompanion.nvim — use OpenCode without leaving your editor.
What the Video Covers
Setup & Installation
- npm / PNPM / Bun / Docker install
- Windows (Git Bash + PowerShell)
- Version verification and first launch
- Plan Mode vs Build Mode
Interfaces
- TUI navigation and context panel
- Desktop app (.exe / .dmg)
- Web app with password protection
- IDE extension (VS Code / SST)
Models & Tiers
- Free / Go / Zen account comparison
- 75+ provider support
- Custom model config in opencode.jsonc
- Temperature and thinking modes
Agents & Skills
- Build, Plan, General, Explore agents
- Custom primary and sub-agents
- react-cleaner and react-styler skills
- Auto-discovery and on-demand loading
MCP & Integrations
- Git MCP for repo context
- Notion MCP for output
- GitHub Actions integration
- LSP and ACP support
Local Models & Cost
- Ollama local + cloud models
- OpenRouter free tier
- /compact for context management
- Tiered model cost strategy
Ready to build with full model freedom?
Hit play on the video to see every command, agent, skill, and MCP integration in action — real terminal output, real apps, real workflows from start to finish.
Watch the Full TutorialRecommended Blogs
Read Our Blogs
Best Screen Recorder Tools: What to Look For in 2026
What makes a screen recorder good in 2026: recording quality, AI transcription, editing, and privacy — plus a checklist before you choose one.
How to Get Your First 10 Paying Users: A Step-by-Step Playbook for B2B and B2C SaaS Founders
Why the first ten matter more than the next ten thousand - and exactly how to find them.