OpenCode — AI Coding Agent

Master the OpenCode CLI to supercharge your development workflow with an intelligent AI assistant directly in your terminal.

What is OpenCode?

OpenCode is a powerful open-source AI coding agent that runs directly in your terminal. It's your personal junior developer—available 24/7 to ask questions about your codebase, add features, fix bugs, refactor code, and more.

Unlike typical AI tools, OpenCode integrates deeply with your project, understanding your codebase structure, coding patterns, and design philosophy to provide contextual, relevant assistance.

Tired of context switching?

OpenCode lives in your terminal, so you stay focused on what matters.

Prerequisites

Before you get started, ensure you have:

Modern Terminal

A capable terminal emulator supporting rich UI rendering:

• WezTerm (recommended, cross-platform)
• Alacritty (cross-platform)
• Ghostty (Linux, macOS)
• Kitty (Linux, macOS)

LLM Provider

API keys for at least one AI provider:

• OpenCode Zen (recommended, curated)
• OpenAI, Claude, Gemini
• Or any other supported provider

View all providers →

Installation

Choose your preferred installation method:

Fastest way to get started:

bash curl -fsSL https://opencode.ai/install | bash

Windows users

For the best experience, use Windows Subsystem for Linux (WSL). Alternatively, use Chocolatey, Scoop, or Docker.

Configuration & Setup

Step 1: Connect Your AI Provider

Start by running OpenCode:

opencode

Then connect your preferred AI provider:

/connect

First time?

We recommend OpenCode Zen — a curated selection of AI models tested by the team. No complex provider setup needed.

Step 2: Add Your API Key

Select your provider
Head to the authentication portal (e.g., opencode.ai/auth)
Sign up, add billing details, and copy your API key
Paste it into the OpenCode prompt

Step 3: Initialize Your Project

Navigate to your project root and initialize OpenCode:

cd /path/to/your/project
opencode

Inside OpenCode, run:

/init

This command:

Analyzes your project structure
Creates an AGENTS.md file in your project root
Sets up OpenCode's understanding of your codebase

Pro tip

Commit your AGENTS.md file to Git. This helps OpenCode maintain context across team members and sessions.

Core Usage Patterns

1. Ask Questions About Your Codebase

Leverage OpenCode as your instant documentation lookup:

How is authentication handled in @packages/auth/index.ts?

Use @ to fuzzy-search files in your project. Perfect for understanding unfamiliar code.

2. Create a Development Plan

Before making changes, ask OpenCode to plan:

Switch to Plan Mode: Press <TAB>

When a user deletes a note, flag it as deleted in the database.
Create a screen showing recently deleted notes.
Allow users to undelete or permanently delete notes.

This generates a structured implementation plan without making changes.

3. Build Features

Once you're satisfied with the plan, switch back to Build Mode (<TAB>):

Sounds good! Go ahead and make the changes.

OpenCode will implement the feature end-to-end.

4. Make Targeted Changes

For simpler modifications:

Add authentication to the /settings route.
Use the same pattern from @packages/auth/settings.ts

5. Undo & Redo

Made a mistake? No problem:

/undo

Made the wrong choice? Redo it:

/redo

Advanced Features

Conversations with OpenCode can be shared with your team:

/share

This generates a shareable link and copies it to your clipboard. Perfect for code reviews and team knowledge sharing.

View an example conversation →

Customize Your Setup

Make OpenCode your own:

Feature	Learn More
Themes	Personalize colors & appearance
Keybinds	Custom keyboard shortcuts
Tools	Add custom code analysis tools
Rules	Define coding standards
Agents	Create specialized AI agents
Formatters	Auto-format code
MCP Servers	Extend with Model Context Protocol

IDE Integration

Work in your favorite editor:

VS Code | OpenCode Extension
JetBrains | Plugin Support
Neovim | Native Integration

Best Practices

✓ Do This

✓ Provide context and examples

✓ Reference specific files with @

✓ Use Plan Mode before big changes

✓ Commit AGENTS.md to Git

✓ Ask follow-up questions

✓ Share conversations with team

✗ Avoid This

✗ Vague feature requests

✗ Assume OpenCode knows your design

✗ Skip the planning phase

✗ Ignore error messages

✗ Make multiple changes at once

✗ Forget to test implementations

Think like a manager

Give OpenCode clear requirements, context, and examples—just as you would brief a junior developer joining your team.

Integrating with Your Project

Understanding AGENTS.md

The AGENTS.md file generated by /init serves as OpenCode's "memory" of your project:

# Project Structure

- Frontend: React/Next.js
- Backend: Node.js/Express
- Database: PostgreSQL

# Coding Patterns

- Authentication: JWT tokens
- API responses: RESTful with standardized error handling
- Styling: Tailwind CSS with custom design system

# Key Files

- Auth: packages/auth/index.ts
- API: packages/api/routes.ts
- UI: components/

Keep this file updated and committed to Git.

Design Philosophy

This documentation site itself follows the Newsprint Design System—a modern take on editorial design. Your project should too!

Design Principles

Clarity Over Trend: High-contrast, sharp typography, grid-based layouts
Authoritative Design: Black & white with editorial red accents
Information Density: Efficient use of space, no wasted pixels
Sharp Geometry: Zero border radius, perfect rectangles, visible structure

→

Read the complete design system

Getting Help

Resources

Official Docs — Complete reference guide
GitHub Discussions — Community support
Discord Community — Real-time help from the team
Issue Tracker — Report bugs or request features

Common Commands

/init       # Initialize OpenCode for your project
/connect    # Set up AI provider
/undo       # Undo last changes
/redo       # Redo undone changes
/share      # Share conversation with team
/help       # View available commands

What's Next?

Explore Providers

Choose between OpenCode Zen, OpenAI, Claude, Gemini, and more.

View providers →

Create Custom Tools

Extend OpenCode with custom tools for your specific workflow.

Learn more →

Master the CLI

Discover powerful CLI commands and keyboard shortcuts.

CLI reference →

Troubleshooting

Solutions for common issues and FAQs.

Troubleshooting →

Ready to Supercharge Your Development?

curl -fsSL https://opencode.ai/install | bash

Then:

cd /path/to/your/project
opencode
/connect
/init

Welcome aboard. Your coding flow just got a massive upgrade.

Feedback

Found a bug? Open an issue on GitHub
Have suggestions? Join our Discord
Want to contribute? Check out the repo