OpenCode Crash Course: Open Source AI Coding Agent
OpenCode is an open-source AI coding agent with exponential GitHub growth. Learn to install it (terminal, desktop, VS Code), configure LLM providers (including local Ollama models), set default models, create agent skills, install plugins like Oh My OpenCode, integrate MCP servers, and access it via terminal or web browser.
What is OpenCode
OpenCode: Open Source AI Coding Agent
OpenCode is an open-source AI coding agent from GitHub experiencing exponential growth. Unlike closed-source alternatives, it allows developers to contribute globally, use free built-in models, connect any LLM provider, and even fork it for enterprise use with custom AI gateways.
Why Learn One AI Coding Agent
Learning one AI coding agent framework makes it easier to switch between others because they all solve the same core problem: helping developers work faster, easier, and more efficiently. The underlying principles transfer across tools.
Installation Methods
Four Ways to Install OpenCode
OpenCode can be installed via terminal (npm/pip commands), desktop app (beta for macOS, Windows, Linux), VS Code extension, or GitHub/GitLab integrations for direct workflow integration.
Core Interface & Commands
Built-in Commands
OpenCode provides built-in commands like init (creates agent.md), undo, redo, share, and help. Users can also create custom commands with specific LLM assignments—small models for minor tasks, large models for complex ones.
Agent Modes & Variants
OpenCode has two main modes: Build (writes code) and Plan (plans without writing). Models support variants (no reasoning, minimal, low, high) matching different complexity levels. Use Tab to switch modes; Ctrl+T cycles through variants.
Context Window Monitoring
The terminal interface displays real-time context window consumption as a percentage (e.g., 14%), helping users understand token usage for each interaction.
LLM Providers & Configuration
Connecting Multiple LLM Providers
OpenCode includes free built-in models (GLM 4.7, Grok, Minimax) but also connects to external providers: OpenAI, Anthropic, Google, Hugging Face, GitHub Models, and local Ollama instances. Use slash commands or the models menu to add providers.
Setting Up Local Ollama Models
Download Ollama locally, pull models (e.g., Qwen 3 VL 2B for small tasks, GPT OSS 20B for large tasks), then create an open code.json file in the project with localhost:11434 configuration pointing to your chosen model.
Setting Default Model
Edit open code.json to add a 'model' field specifying your preferred default model. This ensures the same model loads each time you open OpenCode, rather than defaulting to the most recently used one.
Model Selection for Agent Tasks
Choose models with tools enabled for agents to perform function calling and thinking. Larger models like GPT 4.5 or Claude Opus work better for complex reasoning; smaller models (Qwen 3 VL 2B) suffice for simple tasks.
Agent Skills
What Are Agent Skills
Agent skills are reusable behavior definitions stored in skill.md files within project, global, or home directories. Skills are loaded on-demand via a native skill tool; good naming and descriptions are critical so agents recognize when to invoke them.
Creating a Skill
Create a folder (e.g., skills/meeting_notes/) with a skill.md file containing required fields: name and description, plus optional fields like license and metadata. Include instructions on when to use the skill and what it does.
Using Skills with File Context
Instead of pasting content directly, use the 'add file' command to reference a file (e.g., meeting_notes.txt). OpenCode will load the file, match it to relevant skills (like 'meeting notes summarization'), and execute the skill automatically.
Example: Meeting Notes Skill
A meeting notes skill summarizes notes and extracts action items. When a user pastes meeting notes or asks for a summary, the agent recognizes the matching skill description and invokes it to process the content.
Plugins & Extensions
What Are Plugins
Plugins extend OpenCode's capabilities and features. Community-created plugins add new agents, tools, and workflows. They can be installed, configured, and removed to customize the agent experience.
Oh My OpenCode Plugin
Oh My OpenCode is a popular plugin (19.1K+ stars) that adds curated agents: Meet (main agent using Claude Opus 4.5), Oracle (design/debugging with Gemini 3.3 Pro), Frontend Engineer (UI/UX with Gemini 3.3 Pro), Librarian (docs/codebase with Claude Sonnet 4.5), and others. It includes async teamwork so agents don't wait for each other.
Installing & Removing Plugins
Install plugins via command (e.g., npx oh-my-opencode) or by providing a prompt. Configuration is stored in ~/.config/opencode/. Remove plugins by deleting the plugin config file or specific entries from open code.json.
Tools & MCP Integration
Built-in Tools
OpenCode includes 16 built-in tools for web search, file operations, and more. These are automatically available and help agents gather information and perform tasks without additional configuration.
Model Context Protocol (MCP) Servers
MCP servers (introduced by Anthropic) integrate external tools, databases, APIs, and third-party services. OpenCode supports remote MCP servers via configuration. Add MCP entries to open code.json with the server URL to enable new capabilities.
Adding MCP Servers
Edit open code.json to add an 'mcp' section with remote server URLs. For example, add an Agno documentation MCP server so the agent can fetch Agno-specific context when answering questions about that framework.
Custom Tools
Beyond built-in tools and MCP servers, custom tools can be created. Documentation shows how to define custom tools for specialized tasks specific to your workflow.
Web & Terminal Access
Web Interface
Run 'opencode web' to launch OpenCode in your browser at localhost. The web interface provides the same AI coding experience as the terminal without needing command-line access.
Web Security
By default, the web interface is unsecured. Add authentication by setting a username (defaults to 'opencode') and password using environment variables or command flags to restrict access.
Multiple Sessions
OpenCode supports multiple concurrent sessions. Open multiple terminals or browser tabs to run different agents (e.g., one in build mode, one in plan mode) simultaneously.
Configuration Best Practices
Configuration Hierarchy
OpenCode reads configurations from multiple levels: project-level (open code.json in project root), global (~/.config/opencode/), and remote configs. Project-level settings override global settings.
Customizing Model Parameters
Beyond selecting a default model, the open code.json file allows customization of temperature, context window, reasoning budget, and other LLM parameters to fine-tune agent behavior.
Agent.md File
The agent.md file (created via 'init' command) documents your codebase structure, build instructions, test commands, style guidelines, and other context. Agents reference this to understand your project and make better decisions.
Notable quotes
If you know one AI coding agent or tool, it will be easier to switch between others because they are trying to help us solve things faster, easier, efficiently. — Sudasan Quirala
With opensource, developers will not be tied to one platform. You can contribute globally. That's the good part. — Sudasan Quirala
Good LLM and the right LLM are needed for your agent to work properly. — Sudasan Quirala
Action items
- Install OpenCode using your preferred method: terminal (npm), desktop app, VS Code extension, or GitHub/GitLab integration.
- Download and configure a local Ollama instance with at least one model (e.g., Qwen 3 VL 2B), then create an open code.json file to connect it.
- Set a default model in open code.json so you don't have to select it every time you open OpenCode.
- Create at least one custom skill (e.g., meeting notes summarization) with a clear name and description, then test it by referencing a file.
- Install and configure the Oh My OpenCode plugin to experience curated agents and async teamwork.
- Add an MCP server (e.g., Agno documentation) to open code.json and test how the agent invokes it for relevant queries.
- Explore the web interface by running 'opencode web' and compare it to the terminal experience.
- Review the agent.md file in your project and update it with accurate codebase context so agents make better decisions.
- Experiment with different model variants (no reasoning, minimal, low, high) using Ctrl+T to understand performance trade-offs.
- Read the official OpenCode documentation for advanced features like custom tools, authentication, and enterprise deployments.