KBA knowledgebase
by Aditya Baindur
Documentation

OpenCode — AI Coding Agent

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

Indexed Nov 5, 2026
Read Markdown ↗Full context ↗

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:

Script

NPM

Homebrew

script

Fastest way to get started:

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

npm

Using Node.js package managers:

# npm
npm install -g opencode-ai

# pnpm
pnpm install -g opencode-ai

# yarn
yarn global add opencode-ai

# bun
bun install -g opencode-ai

homebrew

macOS and Linux via Homebrew:

brew install anomalyco/tap/opencode

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

  1. Select your provider
  2. Head to the authentication portal (e.g., opencode.ai/auth)
  3. Sign up, add billing details, and copy your API key
  4. 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

Share Your Work

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:

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

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