OpenCode is an open-source, provider-agnostic coding agent (MIT license) that has rapidly overtaken Claude Code in community adoption (105k GitHub stars vs. 67k), offering developers flexibility to switch between models (Claude, OpenAI, Google, local) without vendor lock-in. This tutorial provides a beginner-friendly walkthrough of setting up OpenCode on Windows via WSL, understanding its core modes, and leveraging its extensibility through project rules, skills, and commands.
🔧 Setup & Environment
- Windows + WSL: OpenCode recommends WSL for best performance and terminal compatibility. Install WSL with
wsl-install, then install OpenCode via the provided command. Use a separate terminal window for OpenCode’s TUI to avoid keybinding conflicts (e.g., Ctrl+B conflicts with Cursor). - Provider Connection: Connect a model provider (e.g., ChatGPT Plus, GPT-5.3 codeex) via browser-based authentication. Free models are included but slow; switching providers is done via
Ctrl+P→ model selection. - Consistent Workspace: Open the repo inside WSL (e.g.,
cursor .in the WSL terminal) so that Cursor edits the same files OpenCode modifies. The bottom-left of the IDE should show “WSL” to confirm the setup.
🧠Core Concepts: Build vs. Plan Mode & agents.md
- Build Mode: Full tool access (edits, bash). Use for implementation (features, refactoring, test fixes). Keep prompts specific (e.g., “Make change X, run test Y, show diff”).
- Plan Mode: Restricted permissions; asks before risky actions. Use for design, code review, debugging strategy. Always start in Plan mode to avoid unintended changes, then switch to Build, then back to Plan for review.
agents.md: Generated viaopen-code initin the repo root. This file defines project conventions, structure, dos/don’ts, build/lint commands, and test instructions. It is a living document that evolves with the project. Commit it to version control for team-wide consistency.
🧩 Skills vs. Commands
- Skills (reusable playbooks): Knowledge modules that the agent loads for specific tasks (e.g., “how to write migrations,” “how to create a new page”). Stored in
open-code/skills/(per project) or global config. Example: a copywriting skill that enforces high-focus language. - Commands (workflow shortcuts): One-shot prompts run with
/name(e.g.,/test,/review,/web-page). They reduce typing and mistakes. Supports placeholders ($1,$2). Created per project or globally. Example:/scaffold skill <name>or/scaffold command <name>. - Key difference: Skills are knowledge for the agent to follow; Commands are repeatable prompts you execute. Add skills only when you notice repetition, not on day one.
đź’ˇ Practical Workflow Tips
- Start in Plan mode → confirm approach → switch to Build → implement → switch back to Plan for review.
- Use
/compactto summarize the session and reduce token usage (e.g., from 4% to 2%). - Voice input: On Windows, press
Windows+Hto dictate prompts. - Model thinking level: Adjust with
Ctrl+Tto control reasoning depth. - Scaffold incrementally: Build a robust
agents.mdfirst, then add commands and skills as you repeat tasks.
🎯 Final Takeaway
OpenCode’s true power lies in its dual-mode workflow (Plan first, then Build) and its extensibility through agents.md, skills, and commands. By maintaining a single, consistent environment (WSL + Cursor) and iteratively codifying recurring patterns, developers can dramatically reduce repetitive prompt engineering and achieve predictable, safe agent behavior. The provider-agnostic nature and open-source momentum ensure that OpenCode remains a future-proof investment for AI-assisted development—regardless of which model leads next.