OpenCode is a full-featured AI coding agent available as a command-line tool, with optional IDE and desktop integrations. It's built on Node.js and works on macOS, Linux, and Windows.
# Recommended: Install script
curl -fsSL https://opencode.ai/install | bash
# Or via npm
npm install -g opencode-ai
# Or via Homebrew (macOS)
brew install anomalyco/tap/opencode
Homebrew (Recommended):
# Add the anomalyco tap for latest releases
brew install anomalyco/tap/opencode
# Alternative: Official Homebrew formula (updated less frequently)
brew install opencode
npm:
npm install -g opencode-ai
Arch Linux:
# Stable release
sudo pacman -S opencode
# Latest from AUR
paru -S opencode-bin
npm:
npm install -g opencode-ai
# Using Mise (Node version manager)
mise use -g github:anomalyco/opencode
Chocolatey:
choco install opencode
Scoop:
scoop install opencode
npm:
npm install -g opencode-ai
Docker:
docker run -it --rm ghcr.io/anomalyco/opencode
git clone https://github.com/anomalyco/opencode.git
cd opencode
npm install
npm run build
npm install -g .
You'll need a modern terminal that supports:
Recommended:
You'll need credentials for at least one LLM provider:
opencode
This opens the TUI (text user interface) with an interactive prompt.
In the TUI, run:
/connect
Options:
Navigate to your project:
cd ~/Projects/my-app
opencode
Then run:
/init
This creates an AGENTS.md file that documents your project structure, coding standards, and build/test commands. OpenCode reads this in every conversation.
Ask OpenCode to help:
Add authentication to the /settings route.
Look at how it's done in /notes and use the same pattern.
| Command | Purpose |
|---|---|
Tab | Toggle between Plan Mode and Build Mode |
Ctrl+C | Exit OpenCode |
| Command | Purpose |
|---|---|
/init | Initialize project (create AGENTS.md) |
/connect | Set up or switch LLM provider |
/theme | Change terminal theme |
| Command | Purpose |
|---|---|
/undo | Revert last set of changes |
/redo | Restore undone changes |
/share | Generate shareable link to conversation |
| Command | Purpose |
|---|---|
/model | Switch LLM model mid-conversation |
/providers | List available providers |
In Plan Mode, OpenCode analyzes your request and suggests an approach without making changes.
Use this for:
Example:
I want to add soft delete support to notes.
Users should see a deleted notes recovery screen.
They can undelete or permanently delete from there.
OpenCode responds with a detailed plan:
Plan:
1. Add `deletedAt` timestamp to notes table
2. Update queries to exclude soft-deleted notes
3. Create new recovery screen component
4. Add restore/permanent delete endpoints
In Build Mode, OpenCode makes actual code changes.
Example (continuing from plan):
Looks good! Go ahead and implement it.
Or for simple changes, skip planning:
Add form validation to the email field in AuthComponent.
Match the pattern used in PasswordField.
How is authentication handled in src/api/middleware.ts?
What are the security assumptions?
OpenCode will:
/plan-mode
Then:
Add a rate limiter to the API endpoints.
- Limit to 100 requests per minute per IP
- Return 429 with Retry-After header
- Exclude health check endpoints
OpenCode creates a plan. Review it, ask follow-ups:
Can you make it configurable in environment variables?
Should we also rate limit by API key in addition to IP?
Once happy, switch to build mode:
/build-mode
Implement the plan.
Refactor the processOrder function to use async/await
instead of promise chains. Keep the same error handling.
OpenCode:
Error: TypeError: Cannot read property 'id' of undefined
in pages/settings.js line 42
Can you find the root cause and fix it?
OpenCode analyzes the error, finds the issue, proposes a fix.
/share
OpenCode generates a URL like https://opencode.ai/s/abc123xyz
Share this with your team for:
After /init, you have an AGENTS.md file that looks like:
# Project: MyApp
## Overview
Full-stack TypeScript application using Next.js and PostgreSQL.
## Tech Stack
- **Runtime**: Node.js 18+
- **Frontend**: React 18 with Next.js 13
- **Backend**: Next.js API routes
- **Database**: PostgreSQL with Prisma ORM
## Project Structure
src/ ├── api/ # Backend handlers ├── components/ # React components ├── pages/ # Next.js pages └── utils/ # Shared utilities
## Coding Standards
- TypeScript with strict mode
- ESLint configured
- Prettier for formatting
- Functional components (no class components)
- Error handling with try/catch
## Key Files
- `tsconfig.json` - TypeScript config
- `next.config.js` - Next.js config
- `.eslintrc.json` - Linting rules
- `prisma/schema.prisma` - Database schema
## Build & Deploy
- `npm install` - Install dependencies
- `npm run dev` - Local development
- `npm run build` - Production build
- `npm run test` - Run tests
- `npm run lint` - Check code style
## Important URLs
- Local dev: http://localhost:3000
- Staging: https://staging.example.com
- Production: https://example.com
OpenCode reads this before every conversation, so it always understands your stack.
Create a .opencoderc file in your home directory for global settings:
{
"defaultModel": "claude-opus",
"defaultProvider": "anthropic",
"theme": "nord",
"editorKeymap": "vim"
}
WezTerm works great with OpenCode on all platforms. Here's a basic config:
-- ~/.wezterm/wezterm.lua
local wezterm = require 'wezterm'
return {
font = wezterm.font('JetBrains Mono'),
font_size = 12,
color_scheme = 'Nord',
-- Enable kitty graphics protocol
enable_kitty_graphics = true,
-- Window padding for readability
window_padding = {
left = 2,
right = 2,
top = 2,
bottom = 2,
},
}
The better your prompt, the better OpenCode's response:
❌ Bad:
Fix the bug in authentication.
✅ Good:
Users can't log in with Google OAuth.
Error: "redirect_uri_mismatch"
The OAuth config is in src/config/oauth.ts.
Check what the redirect URI should be.
Drag/drop a screenshot or design image into OpenCode:
Implement a UI component matching this design:
[drag image here]
OpenCode understands @filename references:
Look at @src/utils/auth.ts and implement similar logic
in @src/utils/api.ts
For complex work, always ask for a plan:
How would you implement infinite scroll pagination
in this infinite list component?
Review, iterate, then ask it to implement.
Not happy with changes? No problem:
/undo
Tweak your prompt and try again:
/redo
OpenCode will fall back to text-only output. Update your terminal:
/connect
Re-enter your API key. Check that:
/init
OpenCode will create it. It needs to understand your project structure.
Check that you're in Build Mode (not Plan Mode). Press Tab to toggle.
OpenCode commits are normal git commits:
git log --oneline
# Shows OpenCode's commits alongside human commits
Always review before pushing:
git diff HEAD~1
git push # After review
Implement Linear issue RFX-40:
[paste acceptance criteria]
Context files: [list relevant files]
No vendor lock-in. You control your data and costs.
npm install -g opencode-aiopencode → /connect → choose providercd ~/project → opencode → /initOpenCode in one sentence: Open source, privacy-first, terminal-native AI coding agent that pairs well with Linear, GitHub, and your favorite editor.