Getting Started

Get up and running in a few minutes.

1

Install opencode

Run this command in your terminal to install opencode:

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

This downloads and installs opencode — a terminal-based AI coding tool — onto your computer.

macOS users: After installation completes, open a new terminal window to ensure opencode is available in your PATH.

2

Connect a provider

A provider is the AI service that powers opencode. Think of it like connecting opencode to a brain.

We recommend GitHub Copilot Pro+ for the best experience. It provides access to Claude and GPT models with high rate limits.

Launch opencode in your terminal:

opencode

Then run the connect command:

/connect

You'll see a provider selection screen:

opencode
┌─ Connect Provider ────────────────────────────────────┐
│                                                       │
│  Select a provider:                                   │
│                                                       │
│  ▸ GitHub Copilot         Recommended                 │
│    Anthropic API          Requires API key            │
│    OpenAI API             Requires API key            │
│    AWS Bedrock            Requires AWS credentials    │
│    Google Vertex          Requires GCP credentials    │
│                                                       │
│  ↑/↓: Navigate  Enter: Select  Esc: Cancel           │
│                                                       │
└───────────────────────────────────────────────────────┘

For GitHub Copilot, you'll authenticate via device flow:

opencode
┌─ GitHub Device Authentication ────────────────────────┐
│                                                       │
│  To authenticate with GitHub Copilot:                 │
│                                                       │
│  1. Open: https://github.com/login/device             │
│                                                       │
│  2. Enter code: ABCD-1234                             │
│                                                       │
│  Waiting for authentication...                        │
│                                                       │
└───────────────────────────────────────────────────────┘

Open the URL in your browser, enter the code shown, and authorize access. Once complete, opencode will confirm the connection.

Tip: After connecting, type /models to see available models, then /exit to quit and continue setup.

3

Install the yo, go toolkit

This installs the agents, skills, and project templates that make opencode work for structured software development.

curl -fsSL https://raw.githubusercontent.com/mdmagnuson-creator/yo-go/main/install.sh | bash

This installs agents, skills, and scaffolds to ~/.config/opencode/. After that, you're ready to start using @planner, @builder, and the rest of the agent system.

Note: When piped to bash, the installer reads prompts from /dev/tty so you can answer yes/no questions interactively. In non-interactive environments (like CI), prompts default to n (no) for safety.

4

Go to your project folder

opencode works inside your project. You need to point your terminal at the folder you want to work on.

cd ~/code/your-project

Replace your-project with your project folder name.

Starting from scratch? Create a new project folder:

mkdir ~/code/my-project && cd ~/code/my-project
5

Launch opencode

Start opencode from your project directory:

opencode

You'll see the opencode TUI:

opencode
┌─ opencode ─────────────────────────────────────────────┐
│                                                        │
│  Welcome to opencode                                   │
│                                                        │
│  Model: claude-sonnet-4-20250514                       │
│  Provider: GitHub Copilot                              │
│                                                        │
│  Type a message or invoke an agent with @              │
│                                                        │
│  > _                                                   │
│                                                        │
└────────────────────────────────────────────────────────┘

Select an agent

Press Tab to open the agent selector, pick an agent (like @planner or @builder), then type your message.

opencode
┌─ opencode ─────────────────────────────────────────────┐
│                                                        │
│  ┌─ Select Agent ────────────────────────────────────┐ │
│  │ ▸ @planner      Plan features and create PRDs     │ │
│  │   @builder      Build and ship code               │ │
│  │   @toolkit      Manage the agent toolkit          │ │
│  │   @e2e-reviewer Review and write E2E tests        │ │
│  └───────────────────────────────────────────────────┘ │
│                                                        │
│  > @planner _                                          │
│                                                        │
└────────────────────────────────────────────────────────┘

For a simple first interaction, select @planner, type yo, and press Enter.

What happens next

When you invoke a primary agent like @planner, it will ask you to select or register a project:

═══════════════════════════════════════════════════════════════
                     SELECT PROJECT
═══════════════════════════════════════════════════════════════

  #   Project                    Agent System
  1   My Web App                 ✅ Yes
  2   API Service                ✅ Yes
  3   New Project                ❌ No

  0   ➕ Add New Project

Which project? _

Select an existing project or add a new one. The agent will then bootstrap project configuration and guide you through creating your first PRD.

6

Select or add a project

The agent immediately shows you a project selection table:

═══════════════════════════════════════════════════════════════
                     SELECT PROJECT
═══════════════════════════════════════════════════════════════

  #   Project                    Agent System
  1   My Web App                 ✅ Yes
  2   API Service                ✅ Yes
  3   New Project                ❌ No

  0   ➕ Add New Project

Which project? _

Select an existing project by number, or choose 0 to add a new one.

7

Bootstrap new projects

When you select "Add New Project", the agent uses a streamlined quick intake flow:

  • Enter your project name and a brief description (paste text, images, or a spec)
  • Optionally provide a GitHub repo URL to clone
  • Auto-detect your tech stack from the codebase or create from a scaffold
  • Generate docs/project.json with your configuration
  • Create docs/CONVENTIONS.md with coding patterns
  • Set up the PRD registry for tracking features

After bootstrap, the agent automatically offers to create your first PRD with architecture options — so you can start building right away.

8

Define your first PRD

After setup, the agent immediately kicks off PRD creation. You'll define:

  • Feature scope and user stories
  • Architecture decisions (database schema, API design, etc.)
  • Acceptance criteria for each story

Once the PRD is ready, hand off to @builder to start implementation.

Project Structure After Setup

your-project/
├── docs/
│   ├── project.json          # Project configuration
│   ├── CONVENTIONS.md        # Coding patterns & style guide
│   ├── prd-registry.json     # Tracks all PRDs
│   ├── prds/                 # Active PRDs
│   └── completed/            # Finished PRDs
├── src/                      # Your application code
└── ...

Key Agents to Know

@builder

Build Features

Implement PRDs, write code, run tests, and ship features end-to-end.

@planner

Plan Work

Create PRDs, prioritize features, and coordinate multi-session work.

@e2e-reviewer

Review E2E Tests

Identifies UI areas changed by a PR and delegates E2E test writing to specialist agents.

@toolkit

Extend the Toolkit

Modify agents, skills, and scaffolds in yo, go itself.

Learn More

Concepts →

Understand how agents, skills, and projects work together

Browse Agents →

Explore all 65 agents and their capabilities

Browse Skills →

See the specialized skills that extend agent capabilities

The Agent Loop →

Learn the Plan-Build-Test-Ship development cycle

Authentication →

Configure auth for E2E tests and authenticated screenshots

Testing →

Unit tests, E2E tests, and Electron desktop testing