# OpenCode AI: The Complete Guide to the Open-Source Terminal Coding Agent Revolutionizing Development in 2026
## Transform Your Development Workflow with the Most Powerful Free AI Coding Assistant
The landscape of AI-powered development tools has exploded in 2026, but one solution stands apart from the crowd: **OpenCode**. This open-source, terminal-first AI coding agent has captured the attention of over 650,000 developers monthly and earned more than 70,000 GitHub stars—all within its first year of existence. If you're tired of expensive subscriptions, vendor lock-in, and privacy concerns with proprietary AI tools, OpenCode offers a refreshing alternative that puts you back in control.
In this comprehensive guide, we'll explore everything you need to know about OpenCode: what it is, how it works, its standout features, real-world applications, and how it compares to alternatives like Cursor, GitHub Copilot, and Aider. Whether you're a solo developer, part of an enterprise team, or building AI-powered applications, this guide will show you how to leverage OpenCode to write better code faster.
---
## Table of Contents
1. [What is OpenCode?](#what-is-opencode)
2. [Why OpenCode Matters in 2026](#why-opencode-matters)
3. [Core Architecture and Technical Features](#core-architecture)
4. [Getting Started: Installation and Setup](#getting-started)
5. [Advanced Features Deep Dive](#advanced-features)
6. [Real-World Use Cases and Applications](#real-world-use-cases)
7. [OpenCode vs. Alternatives: Head-to-Head Comparison](#comparison)
8. [Privacy, Security, and Local Models](#privacy-security)
9. [Integration with Development Workflows](#integration)
10. [Best Practices and Pro Tips](#best-practices)
11. [Future Roadmap and Community](#roadmap)
12. [Conclusion: Is OpenCode Right for You?](#conclusion)
---
**OpenCode** is an open-source AI coding agent designed specifically for terminal-first development workflows. Unlike traditional AI assistants that operate in the browser or require you to switch contexts between your editor and a chat interface, OpenCode brings intelligent code assistance directly into your command line—where many developers spend the majority of their time.
### The Core Value Proposition
At its essence, OpenCode serves as an intelligent coding partner that:
- **Writes, debugs, refactors, and plans code** through natural language instructions
- **Operates autonomously** within defined boundaries, making decisions and iterating on solutions
- **Maintains full context** of your codebase through Language Server Protocol (LSP) integration
- **Supports 75+ LLM providers** including Claude, GPT-4, Gemini, and local models via Ollama
- **Prioritizes privacy** by storing zero code or context data on external servers
- **Remains completely free and open-source**, with no vendor lock-in
Think of OpenCode as having an expert developer sitting beside you in the terminal, capable of understanding your entire project, making informed changes across multiple files, running tests, catching errors, and fixing them—all without you needing to leave the command line.
### Who Built OpenCode?
OpenCode is developed by the team behind SST (Serverless Stack), built by developers who are passionate about terminal-based workflows and tools like Neovim. The project emerged from a simple observation: while AI coding assistants were proliferating, most forced developers into graphical interfaces or locked them into specific ecosystems. OpenCode was designed to be the antithesis of this approach—open, flexible, and terminal-native.
### Key Statistics (January 2026)
- **70,000+ GitHub Stars**: Exceptional community adoption
- **500+ Contributors**: Active open-source development
- **650,000+ Monthly Active Developers**: Rapidly growing user base
- **75+ Supported LLM Providers**: Unmatched flexibility
- **40+ Built-in LSP Servers**: Comprehensive language support
---
## Why OpenCode Matters in 2026
### The Problems OpenCode Solves
#### 1. **Subscription Fatigue and Cost Control**
In 2026, AI coding tools have become expensive. GitHub Copilot charges $10-19/month, Cursor ranges from $20-200/month, and Claude Code subscriptions can exceed $200/month for heavy users. For developers working on multiple projects or teams managing budgets, these costs accumulate rapidly.
**OpenCode's solution**: The core tool is completely free. You only pay for the underlying LLM API usage (OpenAI, Anthropic, etc.), or you can run local models via Ollama at zero cost. This gives you full transparency and control over expenses.
#### 2. **Privacy and Data Security**
Proprietary AI tools typically require uploading your code to external servers for processing. For enterprises handling sensitive intellectual property, regulated industries (healthcare, finance), or developers working on proprietary codebases, this creates unacceptable risk.
**OpenCode's solution**: All processing happens locally. Your code never leaves your machine unless you explicitly choose to use cloud LLM providers. When combined with local models through Docker Model Runner or Ollama, you achieve complete air-gapped privacy.
#### 3. **Vendor Lock-In**
Most AI coding assistants tie you to specific ecosystems: GitHub Copilot works best with VS Code, Cursor is its own IDE, Claude Code operates within Anthropic's environment. Switching tools means learning new interfaces and losing customizations.
**OpenCode's solution**: Provider-agnostic architecture means you can switch between Claude, GPT-4, Gemini, DeepSeek, or local models without changing your workflow. The open-source nature ensures you're never locked into a single vendor's roadmap or pricing decisions.
#### 4. **Context Switching and Workflow Disruption**
Traditional AI assistants force you to leave your terminal, copy code into a chat interface, wait for responses, then manually apply changes back to your files. This constant context switching destroys flow state.
**OpenCode's solution**: Terminal-native interface keeps you in your development environment. OpenCode reads files, makes changes, runs commands, receives feedback from LSP servers, and iterates—all while you maintain focus.
---
## Core Architecture and Technical Features
### Client-Server Architecture
OpenCode employs a sophisticated client-server architecture that separates the user interface from the backend logic:
- **Server (Backend)**: Handles LLM communication, tool execution, session management, and file operations
- **TUI Client (Frontend)**: Provides the terminal user interface with real-time updates
- **Desktop App (Beta)**: Cross-platform application for Windows, macOS, and Linux
This architecture enables powerful capabilities:
- **Remote operation**: Run OpenCode on your development server while controlling it from your laptop
- **Multiple clients**: Attach different interfaces (TUI, desktop, mobile in the future) to the same backend session
- **Session persistence**: Continue conversations across disconnections and device switches
### Language Server Protocol (LSP) Integration
One of OpenCode's most powerful differentiators is its automatic LSP integration:
**How It Works**:
1. When you open a project, OpenCode scans file extensions (`.py`, `.ts`, `.go`, `.rs`, etc.)
2. It automatically identifies required language servers and starts them in the background
3. LSP servers provide OpenCode with:
- **Diagnostics**: Real-time error detection and linting
- **Semantic understanding**: Function signatures, type information, dependencies
- **Code intelligence**: Auto-completion data, symbol definitions, references
**Supported Languages** (40+ built-in LSP servers):
| Language | LSP Server | Auto-Install |
|----------|------------|--------------|
| TypeScript/JavaScript | typescript-language-server | ✅ |
| Python | Pyright | ✅ |
| Go | gopls | ✅ |
| Rust | rust-analyzer | ✅ |
| C/C++ | clangd | ✅ |
| Java | jdtls | ✅ |
| PHP | intelephense | ✅ |
| Ruby | ruby-lsp | ✅ |
| Swift | sourcekit-lsp | ✅ |
| Terraform | terraform-ls | ✅ |
**The Impact**: Unlike tools that rely solely on static code analysis or embeddings, OpenCode receives live feedback from your language servers. When it makes a change that breaks the build, the LSP server immediately reports the error, and OpenCode iterates to fix it—just like a human developer would.
### Model Context Protocol (MCP) Support
OpenCode is one of the first coding agents to deeply integrate Anthropic's Model Context Protocol (MCP), an open standard for connecting LLMs to external tools and data sources.
**MCP Capabilities**:
- **STDIO Servers**: Run local processes that expose tools via standard input/output
- **HTTP/SSE Servers**: Connect to remote services over HTTP with authentication
- **Tool Discovery**: Automatically detect available tools from MCP servers
- **Permission System**: Control which tools OpenCode can access
**Real-World Example**: Connect OpenCode to a database MCP server to:
- Query your database schema
- Generate migration scripts based on actual table structures
- Create seed data that matches your production types
### Agentic Behavior and Autonomy
OpenCode operates as a true autonomous agent, not just a chatbot:
**Traditional Flow (Cursor, Copilot)**:
1. You: "Fix this error"
2. AI: Suggests a fix
3. You: Review, accept, run tests
4. Tests fail
5. You: "Tests are failing"
6. Repeat...
**OpenCode Flow**:
1. You: "Fix this error"
2. OpenCode: Makes change → LSP reports new error → Searches for problematic file → Reads it → Attempts fix → Runs `go test` → Sees failure → Iterates fix → Tests pass → Reports completion
This autonomous iteration dramatically accelerates development by eliminating the manual back-and-forth prompting loop.
### Built-In Tools
OpenCode comes with a comprehensive toolkit:
| Tool | Function | Use Case |
|------|----------|----------|
| `write` | Create or overwrite files | Generating new code |
| `read` | Read file contents | Understanding codebase |
| `grep` | Search with regex | Finding patterns across files |
| `list` | List directory contents | Exploring project structure |
| `ask` | Request user input | Clarifying requirements |
| `bash` | Execute shell commands | Running tests, building, deploying |
These tools are exposed to the LLM, allowing it to operate like a developer with terminal access.
---
## Getting Started: Installation and Setup
### Installation Methods
**Method 1: Quick Install Script (Recommended)**
```bash
curl -fsSL https://opencode.ai/install | bash
```
This downloads the latest binary and sets up your PATH automatically.
**Method 2: Node.js/npm**
```bash
npm install -g opencode-ai
```
**Method 3: Homebrew (macOS/Linux)**
```bash
brew install sst/tap/opencode
```
**Method 4: Arch Linux (Paru)**
```bash
paru -S opencode-bin
```
### Initial Configuration
#### Step 1: Authenticate with an LLM Provider
```bash
opencode auth login
```
This launches an interactive wizard where you select your provider (Anthropic, OpenAI, Google, etc.) and enter your API key. Keys are stored locally in `~/.local/share/opencode/auth.json`.
**Supported Providers** (75+):
- **Anthropic**: Claude 3.5 Sonnet, Claude 3 Opus, Claude 3 Haiku
- **OpenAI**: GPT-4o, GPT-4 Turbo, O1, O3-mini
- **Google**: Gemini 1.5 Pro, Gemini 2.0 Flash
- **DeepSeek**: DeepSeek V3, DeepSeek Coder
- **AWS Bedrock**: Access models through AWS
- **Azure OpenAI**: Enterprise Azure deployments
- **Local Models**: Ollama, llama.cpp, LM Studio
#### Step 2: Navigate to Your Project
```bash
cd /path/to/your/project
opencode
```
#### Step 3: Initialize Your Project
Once in the OpenCode TUI, run:
```bash
/init
```
This creates an `AGENTS.md` file in your project root. This file helps OpenCode understand:
- Project structure and organization
- Coding patterns and conventions
- Architecture decisions
- Dependencies and frameworks
**Example AGENTS.md**:
```markdown
# Project Context
## Overview
This is a Next.js 14 application with TypeScript, using Prisma for database access and tRPC for type-safe APIs.
## Architecture
- `/app`: Next.js app router pages
- `/components`: Reusable React components
- `/server`: tRPC routers and procedures
- `/prisma`: Database schema and migrations
## Coding Standards
- Use functional components with TypeScript
- Prefer server components over client components
- All database queries go through tRPC procedures
- Use Zod for validation schemas
```
### Configuration File: `opencode.json`
Create a configuration file to customize OpenCode's behavior:
**Global Config**: `~/.config/opencode/opencode.json`
**Project Config**: `./opencode.json` (takes precedence)
**Example Configuration**:
```json
{
"$schema": "https://opencode.ai/config.json",
"model": "anthropic/claude-3-5-sonnet-20241022",
"provider": {
"anthropic": {
"apiKey": "process.env.ANTHROPIC_API_KEY"
},
"ollama": {
"npm": "@ai-sdk/openai-compatible",
"name": "Ollama (Local)",
"options": {
"baseURL": "http://localhost:11434/v1"
},
"models": {
"qwen3-coder:30b": {
"name": "Qwen3 Coder 30B (Local)"
}
}
}
},
"share": "manual",
"lsp": {
"typescript": {
"disabled": false
}
}
}
```
---
## Advanced Features Deep Dive
### 1. Multi-Session Agents
OpenCode supports two types of agents:
**Primary Agents** (switch between them):
- **Build**: Full tool access, makes changes autonomously
- **Plan**: Restricted tools, focuses on planning and architecture
**Subagents** (invoked automatically or via @mention):
- **General**: Handles general coding questions
- **Explore**: Code exploration and understanding
**Switch agents**: Press `Tab` or use `Ctrl+X` keybindings
### 2. Custom Commands
Create reusable prompts as custom slash commands:
**File**: `.opencode/commands/review.md`
```markdown
---
description: "Review code for security issues"
---
Review all files in the current directory for:
- SQL injection vulnerabilities
- XSS attack vectors
- Authentication/authorization bugs
- Hardcoded secrets or API keys
Provide a security report with severity ratings.
```
**Usage**:
```bash
/review
```
### 3. Session Management and Sharing
**Create shareable links**:
```bash
/share
```
Generates a public URL (e.g., `opncd.ai/s/abc123`) that syncs in real-time. Perfect for:
- Code reviews with teammates
- Debugging assistance
- Onboarding new developers
- Documentation of problem-solving sessions
**Disable sharing** (for sensitive projects):
```json
{
"share": "disabled"
}
```
### 4. Undo/Redo with Time Travel
OpenCode v0.3.85+ includes powerful undo/redo functionality:
```bash
/undo # Reverts last message AND all file changes
/redo # Re-applies changes
```
This isn't just chat history—it actually reverts file modifications and can even undo bash commands that were executed. Granular time travel UI is planned for future releases.
### 5. GitHub & GitLab Integration
Run OpenCode directly in your CI/CD workflows:
**Setup**:
1. Install the OpenCode GitHub App
2. Add `.github/workflows/opencode.yml`:
```yaml
name: OpenCode
on:
issue_comment:
types: [created]
pull_request_review_comment:
types: [created]
jobs:
opencode:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: opencode-ai/action@v1
with:
model: anthropic/claude-sonnet-4
env:
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
```
**Usage in Issues/PRs**:
```markdown
/opencode explain this issue
/opencode fix the bug described above
/opencode add dark mode support
```
OpenCode will:
- Read the entire issue/PR thread
- Create a new branch
- Implement the changes
- Open a pull request with the solution
### 6. Desktop Application (Beta)
OpenCode now offers a native desktop app for Windows, macOS, and Linux for developers who prefer a GUI over the TUI:
- Beautiful visual interface with theming
- All TUI capabilities in a graphical environment
- Seamless file diffing and change visualization
- Perfect for onboarding team members less comfortable with terminals
Download: [opencode.ai/download](https://opencode.ai/download)
---
## Real-World Use Cases and Applications
### Use Case 1: Legacy Codebase Refactoring
**Scenario**: You have a 500-line Python monolith that needs to be split into modules.
**OpenCode Workflow**:
```bash
opencode start "Take main.py. Split the database logic into db.py and the utils into utils.py. Update all imports. Run pytest after the move to ensure nothing broke."
```
**What Happens**:
1. OpenCode reads `main.py`
2. Identifies database-related functions
3. Creates `db.py` and moves them
4. Identifies utility functions
5. Creates `utils.py` and moves them
6. Updates all import statements across the codebase
7. Runs `pytest` to verify functionality
8. Reports any test failures and fixes them
**Time Saved**: What would take 2-3 hours of manual work completes in 10-15 minutes.
### Use Case 2: Test-Driven Development (TDD) Loop
**Scenario**: You want to implement a new feature with full test coverage.
**Workflow**:
```bash
# Write failing test first
opencode run "Create tests/feature.test.ts with tests for user authentication flow. Tests should fail initially."
# Implement the feature
opencode run "Read tests/feature.test.ts. Implement src/auth.ts to make all tests pass."
# Verify
opencode run "Run npm test. If any tests fail, analyze and fix until all pass."
```
**Advantage**: OpenCode gets immediate feedback from test runners, allowing it to iterate rapidly until all tests are green.
### Use Case 3: API Development with Backend Engineers
**Scenario**: Building a REST API with proper error handling and validation.
**Prompt**:
```bash
opencode start "Create a REST API endpoint POST /api/users with:
- Zod validation for email, password (min 8 chars)
- bcrypt password hashing
- Prisma database insert
- Error handling for duplicate emails
- Return 201 on success with user data (no password)
- Follow RESTful conventions"
```
**Output**: Fully functional, production-ready endpoint with proper validation, security, and error handling.
### Use Case 4: Docker and Deployment Configuration
**Scenario**: You need to containerize your Next.js application.
**Prompt**:
```bash
opencode run "Create a production-ready Dockerfile for this Next.js app. Include multi-stage build, optimize for caching, and create a docker-compose.yml with PostgreSQL."
```
**What OpenCode Delivers**:
- Multi-stage Dockerfile with build and production stages
- `.dockerignore` for optimal build context
- `docker-compose.yml` with app + PostgreSQL services
- Health checks and restart policies
- Environment variable configuration
### Use Case 5: Documentation Generation
**Scenario**: Your README is outdated compared to your actual API.
**Workflow**:
```bash
opencode run "Read all exported functions in src/api. Update docs/API.md to match current function signatures, parameters, and return types. Add usage examples for each function."
```
**Result**: Automatically synchronized documentation that reflects your actual codebase.
### Use Case 6: Security Audit with Local Models
**Scenario**: Scan for secrets before committing (without sending code to external APIs).
**Setup**: Use local Ollama model (privacy-first)
```bash
opencode run "Scan src/ for any hardcoded API keys, passwords, or secrets. Report file paths and line numbers."
```
**Privacy Benefit**: Because you're using a local model, potentially sensitive data never leaves your machine.
---
## OpenCode vs. Alternatives: Head-to-Head Comparison
### OpenCode vs. Cursor
| Feature | OpenCode | Cursor |
|---------|----------|--------|
| **Interface** | Terminal-first (+ desktop app) | Full IDE (VS Code fork) |
| **Cost** | Free (pay for LLM usage only) | $20-200/month |
| **Model Support** | 75+ providers | Limited to supported models |
| **Privacy** | Local storage, no data uploads | Code uploaded to servers |
| **LSP Integration** | Automatic for 40+ languages | VS Code LSP support |
| **Customization** | Highly customizable via config | IDE-level settings |
| **Best For** | Terminal users, privacy-conscious devs | IDE-centric workflows |
**Winner for Terminal Developers**: OpenCode
**Winner for IDE Users**: Cursor
### OpenCode vs. GitHub Copilot
| Feature | OpenCode | GitHub Copilot |
|---------|----------|----------------|
| **Mode** | Autonomous agent | Autocomplete + chat |
| **Context** | Full project via LSP | File-level context |
| **Autonomy** | Makes and tests changes | Suggests changes for approval |
| **Pricing** | Free tool + LLM costs | $10-19/month subscription |
| **GitHub Integration** | Via GitHub Actions | Native |
| **Open Source** | ✅ Yes | ⌠No |
**Winner for Autonomous Work**: OpenCode
**Winner for Inline Suggestions**: GitHub Copilot
### OpenCode vs. Aider
Both are open-source terminal agents, but with key differences:
| Feature | OpenCode | Aider |
|---------|----------|-------|
| **Autonomy** | Highly autonomous, iterates without asking | Asks permission for each change |
| **Context Control** | Auto-compacting, less granular | Explicit file add/remove control |
| **LSP Integration** | ✅ Built-in | ⌠Not available |
| **UI** | Polished TUI with status bar | Simple REPL-style interface |
| **Git Integration** | Standard | Deep Git-aware editing |
| **Speed** | Many small iterations | Longer contiguous responses |
**Winner for Autonomous Workflows**: OpenCode
**Winner for Git-First Development**: Aider
### OpenCode vs. Claude Code
| Feature | OpenCode | Claude Code |
|---------|----------|-------------|
| **Models** | Any provider (Claude, GPT, Gemini, local) | Claude only |
| **Cost** | LLM API costs | $20-200/month |
| **Local Models** | ✅ Full support | ⌠Not available |
| **Desktop App** | ✅ Available | ⌠Terminal only |
| **Open Source** | ✅ Yes | ⌠Proprietary |
| **Slash Commands** | Custom commands supported | Built-in commands |
**Winner for Flexibility**: OpenCode
**Winner for Simplicity**: Claude Code
### Benchmark Results (Real-World Projects)
In a recent benchmark comparing OpenCode, Cursor, Claude Code, and Gemini CLI on building a full-stack todo application (conducted by Render.com):
**Results**:
| Tool | Error-Free Code | Docker Support | Follow-up Prompts | Score |
|------|-----------------|----------------|-------------------|-------|
| **Cursor** | ✅ | ✅ Full (Compose + migrations) | 3 | 9/10 |
| **OpenCode** | ✅ | âš ï¸ Basic | 4 | 8/10 |
| **Claude Code** | âš ï¸ | ⌠| 5 | 7/10 |
| **Gemini CLI** | ✅ | ⌠| 6 | 7/10 |
**Key Takeaway**: Cursor currently leads on complex scaffolding tasks, but OpenCode delivers excellent code quality with strong LSP-powered refactoring capabilities.
---
## Privacy, Security, and Local Models
### Privacy Architecture
OpenCode's privacy-first design:
1. **Local Storage**: All conversations stored in local SQLite database (`~/.local/share/opencode/`)
2. **No Telemetry**: Zero analytics or usage tracking sent to OpenCode servers
3. **Explicit Sharing**: Sessions only uploaded when you explicitly run `/share`
4. **API Key Security**: Credentials stored locally, never transmitted to OpenCode infrastructure
### Running Completely Offline with Ollama
For maximum privacy, run OpenCode with local LLMs:
**Step 1: Install Ollama**
```bash
curl -fsSL https://ollama.com/install.sh | sh
```
**Step 2: Download a Model**
```bash
ollama pull qwen3-coder:30b # 30B parameter coding model
# or
ollama pull deepseek-coder-v2:16b # DeepSeek V2 16B
```
**Step 3: Configure OpenCode**
Create `opencode.json`:
```json
{
"$schema": "https://opencode.ai/config.json",
"model": "ollama/qwen3-coder:30b",
"provider": {
"ollama": {
"npm": "@ai-sdk/openai-compatible",
"name": "Ollama (Local)",
"options": {
"baseURL": "http://localhost:11434/v1"
},
"models": {
"qwen3-coder:30b": {
"name": "Qwen3 Coder 30B",
"tools": true
}
}
}
}
}
```
**Step 4: Run OpenCode**
```bash
opencode
/models # Select your local Ollama model
```
**Privacy Achieved**: Your code, prompts, and AI responses never leave your machine. Perfect for:
- Regulated industries (healthcare, finance)
- Proprietary codebases
- Air-gapped development environments
- Traveling without internet access
### Docker Model Runner Integration
For enterprise teams, combine OpenCode with Docker Model Runner (DMR) for infrastructure-controlled AI:
**Benefits**:
- Models run in Docker containers you control
- No external API dependencies
- Full audit trail of all inference requests
- Cost transparency (pay only for compute, not per-token)
**Configuration Example**:
```json
{
"$schema": "https://opencode.ai/config.json",
"provider": {
"dmr": {
"npm": "@ai-sdk/openai-compatible",
"name": "Docker Model Runner",
"options": {
"baseURL": "http://localhost:12434/v1"
},
"models": {
"gpt-oss": {
"name": "gpt-oss:128K"
}
}
}
}
}
```
**Enterprise Use Case**: Run OpenCode in CI/CD pipelines with DMR-hosted models, ensuring no code leaves your VPC.
### Security Best Practices
1. **Permissions Management**: Configure agent permissions to restrict file access:
```json
{
"agents": {
"build": {
"tools": {
"write": true,
"bash": false // Disable shell execution for safety
}
}
}
}
```
2. **Environment Variable Protection**: Never commit API keys in config files:
```json
{
"provider": {
"anthropic": {
"apiKey": "process.env.ANTHROPIC_API_KEY"
}
}
}
```
3. **Disable Sharing for Sensitive Projects**:
```json
{
"share": "disabled"
}
```
4. **Audit Trail**: OpenCode maintains full session history in SQLite, allowing security teams to audit all AI-generated changes.
---
## Integration with Development Workflows
### Neovim Integration
For Neovim users, OpenCode offers exceptional terminal compatibility:
**Setup**: Run OpenCode in a tmux pane or terminal split alongside Neovim
```bash
# Terminal 1: Neovim
nvim src/api/users.ts
# Terminal 2: OpenCode
opencode
```
**Workflow**:
1. Edit code in Neovim
2. Switch to OpenCode terminal
3. Prompt: "Refactor the UserService class to use dependency injection"
4. OpenCode makes changes
5. Review diff in OpenCode, then `:e!` in Neovim to reload
**Pro Tip**: Use Neovim's terminal mode (`:term`) to run OpenCode inline.
### VS Code Extension
While OpenCode is terminal-first, it also offers a VS Code extension for developers who prefer IDE integration:
**Installation**:
```bash
code --install-extension opencode.opencode-vscode
```
**Features**:
- OpenCode terminal panel within VS Code
- Side-by-side diff viewer
- Integrated file change tracking
### Docker Development Workflow
Run OpenCode in a containerized environment to isolate it from your host system:
**Dockerfile Example**:
```dockerfile
FROM ubuntu:latest
# Install dependencies
RUN apt-get update && apt-get install -y \
curl \
git \
nodejs \
npm
# Install OpenCode
RUN curl -fsSL https://opencode.ai/install | bash
# Set up user and permissions
RUN useradd -m developer
USER developer
WORKDIR /home/developer
# Copy project and OpenCode config
COPY --chown=developer:developer . /home/developer/project
COPY --chown=developer:developer opencode.json /home/developer/.config/opencode/
CMD ["/home/developer/.opencode/bin/opencode", "."]
```
**Run Script** (`run-opencode-docker.sh`):
```bash
#!/bin/bash
docker build -t opencode-dev .
docker run -it \
-v ~/.local/share/opencode/auth.json:/home/developer/.local/share/opencode/auth.json \
-v $(pwd):/home/developer/project \
opencode-dev
```
**Use Case**: Keep OpenCode experiments isolated from production environments.
### CI/CD Pipeline Integration
**GitHub Actions Example** (Automated Code Review):
```yaml
name: AI Code Review
on: [pull_request]
jobs:
review:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Install OpenCode
run: curl -fsSL https://opencode.ai/install | bash
- name: Review Code
env:
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
run: |
opencode run "Review this PR for:
- Code quality issues
- Security vulnerabilities
- Performance concerns
Generate a markdown report"
- name: Post Review
uses: actions/github-script@v6
with:
script: |
github.rest.issues.createComment({
issue_number: context.issue.number,
owner: context.repo.owner,
repo: context.repo.repo,
body: '## AI Code Review\n\n' + fs.readFileSync('review.md', 'utf8')
})
```
---
## Best Practices and Pro Tips
### 1. Project Initialization is Critical
Always run `/init` and create a comprehensive `AGENTS.md`:
**Good AGENTS.md**:
```markdown
# Project: E-commerce Platform
## Tech Stack
- Next.js 14 (App Router)
- TypeScript 5.3
- Prisma ORM
- PostgreSQL 15
- tRPC for API layer
- TailwindCSS for styling
## Architecture Decisions
- Server components by default, client only when necessary
- All mutations through tRPC procedures
- Database queries only in server components or tRPC
- Optimistic UI updates for better UX
## Coding Conventions
- Use `async/await`, avoid callbacks
- Prefer `const` over `let`, never `var`
- Component files: PascalCase (e.g., `UserProfile.tsx`)
- Utility files: camelCase (e.g., `formatDate.ts`)
- All exports named, no default exports
- TypeScript strict mode enabled
## Testing
- Unit tests: Vitest
- E2E tests: Playwright
- Run `npm test` before committing
```
**Impact**: OpenCode uses this context to make decisions aligned with your project's patterns.
### 2. Iterative Prompting for Complex Tasks
Break complex tasks into steps:
**⌠Poor Approach**:
```
"Build a complete authentication system with OAuth, email verification, password reset, and role-based access control"
```
**✅ Better Approach**:
```
Step 1: "Create database schema for users, sessions, and roles using Prisma"
Step 2: "Implement signup endpoint with email/password validation"
Step 3: "Add OAuth integration for Google and GitHub"
Step 4: "Create email verification flow with token expiry"
```
**Why**: Allows you to review and adjust after each step, catching issues early.
### 3. Leverage LSP Feedback
OpenCode's LSP integration is its superpower. Let it work:
**Example**:
```
"Refactor the UserService class to use constructor injection instead of property injection. Run the TypeScript compiler after changes to catch errors."
```
OpenCode will:
1. Make the refactor
2. Receive TypeScript errors from LSP
3. Automatically fix type mismatches
4. Iterate until errors clear
### 4. Use Custom Commands for Repetitive Tasks
Create commands for common workflows:
**`.opencode/commands/migration.md`**:
```markdown
---
description: "Create database migration"
---
1. Read prisma/schema.prisma
2. Generate a migration for: $ARGUMENTS
3. Create migration file with timestamp
4. Run `npx prisma migrate dev` to apply
5. Verify migration applied successfully
```
**Usage**:
```bash
/migration add user profile image URL field
```
### 5. Session Management Strategy
Use sessions strategically:
- **New Feature**: Start a new session (`/new`)
- **Bug Fix**: Continue existing session (loads context)
- **Unrelated Task**: New session to avoid context pollution
**Compact Sessions** when context grows large:
```bash
/compact # Summarizes conversation, frees up tokens
```
### 6. Model Selection Based on Task
Different models excel at different tasks:
| Task | Recommended Model | Reasoning |
|------|-------------------|-----------|
| Complex refactoring | Claude 3.5 Sonnet | Superior reasoning |
| Quick fixes | GPT-4o-mini | Fast, cost-effective |
| Embedded systems | DeepSeek Coder | Excellent C/C++ |
| Frontend (React/Vue) | Gemini 1.5 Pro | Strong TypeScript/JSX |
| Large context | Claude 3.5 Sonnet 200K | Massive context window |
| Local/offline | Qwen3 Coder 30B | Best local coding model |
**Switch models mid-session**:
```bash
/models
# Select different model for next tasks
```
### 7. Debugging Workflow
When OpenCode's solution doesn't work:
1. **Ask for explanation**: "Explain why you chose this approach"
2. **Provide error output**: Paste full error messages
3. **Request alternatives**: "The previous solution failed. Try a different approach"
4. **Narrow scope**: "Focus only on fixing the database connection issue"
### 8. Cost Optimization
**Strategies to minimize LLM API costs**:
1. **Use local models for exploration**: Ollama for understanding codebases
2. **Cloud models for production**: Claude/GPT for critical implementations
3. **Context pruning**: Run `/compact` frequently
4. **Smaller models for simple tasks**: GPT-3.5 Turbo for documentation, comments
5. **Monitor usage**: Track token consumption via OpenCode Monitor CLI tool
---
## Future Roadmap and Community
### Planned Features (2026)
Based on GitHub discussions and the OpenCode team's roadmap:
1. **Enhanced Time Travel UI**: Visual timeline of all code changes with granular undo/redo
2. **Workspaces**: Sandboxed Docker/cloud environments for isolated execution
3. **Advanced MCP Integration**: Deeper tool ecosystem with pre-built MCP servers
4. **Multi-Agent Orchestration**: Multiple specialized agents working in parallel (already available via "Oh My OpenCode" plugin)
5. **Voice Interface**: Natural language voice commands for hands-free coding
6. **Mobile App**: Control OpenCode backend from mobile devices
7. **Collaborative Features**: Real-time pair programming with multiple users
8. **Enhanced LSP Support**: Even more languages and deeper semantic understanding
### Community and Support
**Active Community Channels**:
- **GitHub**: [github.com/opencode-ai/opencode](https://github.com/opencode-ai/opencode) (70K+ stars)
- **Discord**: Active community for real-time help
- **Reddit**: r/opencodeCLI for discussions and tips
- **X/Twitter**: @opencode_ai for updates
**Contributing**:
OpenCode welcomes contributions:
- Bug reports and feature requests via GitHub Issues
- Pull requests for new features or fixes
- LSP server integrations for additional languages
- Custom agents and commands shared with the community
**Documentation**:
- Official Docs: [opencode.ai/docs](https://opencode.ai/docs)
- API Reference: Comprehensive API documentation for extensions
- Tutorial Videos: YouTube channels like "Darren Builds AI" and "World of AI"
---
## Conclusion: Is OpenCode Right for You?
### OpenCode is Perfect For:
✅ **Terminal-First Developers**: If you live in the command line and use tools like Neovim, tmux, or prefer minimal UIs, OpenCode is built for you.
✅ **Privacy-Conscious Teams**: Enterprises handling sensitive code, regulated industries, or teams requiring air-gapped development environments.
✅ **Budget-Conscious Developers**: Avoid expensive subscriptions—pay only for LLM usage or use local models for free.
✅ **Multi-Model Users**: Teams wanting to experiment with different LLMs (Claude for reasoning, GPT for speed, local models for privacy).
✅ **Open-Source Advocates**: Developers who value transparency, customization, and community-driven development over proprietary black boxes.
✅ **Autonomous Workflow Seekers**: If you want an AI that iterates on problems autonomously rather than requiring constant hand-holding.
### OpenCode Might Not Be Ideal For:
⌠**Pure GUI Users**: If you're uncomfortable with terminals and prefer fully graphical IDEs, Cursor or GitHub Copilot might suit you better.
⌠**Beginners Wanting Simplicity**: The configuration and setup require some technical knowledge. Claude Code or Cursor offer more plug-and-play experiences.
⌠**Teams Needing Enterprise Support**: As an open-source project, OpenCode lacks dedicated enterprise SLAs (though community support is strong).
### Final Thoughts
OpenCode represents a fundamental shift in how developers interact with AI coding assistants. By prioritizing **privacy**, **flexibility**, and **developer autonomy**, it challenges the subscription-based, proprietary model dominating the industry.
Whether you're a solo developer building side projects, a startup team optimizing costs, or an enterprise requiring maximum data control, OpenCode offers a compelling alternative. Its open-source nature means it will evolve based on real developer needs, not corporate roadmaps.
The future of AI-assisted development is open, transparent, and in your control. OpenCode is leading that future.
---
## Getting Started Today
Ready to transform your coding workflow?
1. **Install OpenCode**: `curl -fsSL https://opencode.ai/install | bash`
2. **Configure your provider**: `opencode auth login`
3. **Initialize your project**: `opencode` → `/init`
4. **Start coding smarter**: Try your first prompt!
**Join the Community**:
- â Star the repo: [github.com/opencode-ai/opencode](https://github.com/opencode-ai/opencode)
- 💬 Join Discord for support and tips
- 📚 Read the docs: [opencode.ai/docs](https://opencode.ai/docs)
---
## Additional Resources
- **Official Website**: [opencode.ai](https://opencode.ai)
- **Documentation**: [opencode.ai/docs](https://opencode.ai/docs)
- **GitHub Repository**: [github.com/opencode-ai/opencode](https://github.com/opencode-ai/opencode)
- **Model Context Protocol**: [modelcontextprotocol.io](https://modelcontextprotocol.io)
- **Ollama Models**: [ollama.com/library](https://ollama.com/library)
- **Docker Model Runner**: [docs.docker.com/model-runner](https://docs.docker.com)
---
**Keywords**: OpenCode AI, AI coding agent, terminal coding assistant, open-source AI coding tool, GitHub Copilot alternative, Cursor alternative, local AI models, Ollama integration, privacy-first coding, LSP integration, autonomous coding agent, free AI developer tools, 2026 AI coding tools
**Meta Description**: Complete guide to OpenCode AI—the open-source, terminal-first coding agent supporting 75+ LLM providers. Learn installation, advanced features, real-world use cases, and how it compares to Cursor, GitHub Copilot, and Aider. Perfect for privacy-conscious developers in 2026.