Skip to content
Showcase Ecosystem Docs

OpenCode Quick Start Guide

Get up and running with OpenCode in less than 5 minutes.

Prerequisites

  • macOS, Linux, or Windows (WSL2 supported)
  • Node.js 18+ (for some language servers)
  • An API Key (optional with built-in models)

Installation

Run the following command in your terminal to download and install the binary:

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

For more installation options, see the Installation page.

Authentication

OpenCode offers multiple authentication options to get you started quickly.

Option 1: Built-in Free Models (Zen)

The easiest way to get started is with OpenCode Zen, which provides curated AI models optimized for coding:

opencode auth login --provider zen

No API key required - just start coding!

Option 2: GitHub Copilot

If you have a GitHub Copilot subscription:

opencode auth login --provider github

This will open your browser to authenticate with GitHub.

Option 3: ChatGPT Plus/Pro

If you have a ChatGPT Plus or Pro subscription:

opencode auth login --provider openai

This will use your ChatGPT subscription directly.

Option 4: Custom API Keys

For other providers, you can configure your own API keys:

# Start interactive authentication
opencode auth login

# Or authenticate with a specific provider
opencode auth login --provider anthropic
opencode auth login --provider google

Supported Providers:

Your API keys are securely stored in ~/.local/share/opencode/auth.json.

Project Initialization

To help OpenCode understand your project structure better, initialize your project with the /init command.

Using the /init Command

Option 1: From the Terminal

Navigate to your project directory and run:

opencode init

Option 2: From the TUI

Start the OpenCode TUI:

opencode tui

Then type the /init command:

/init

What the /init Command Does

The /init command:

  1. Scans your project directory structure
  2. Identifies key files and components
  3. Creates an AGENTS.md file in your project root
  4. Documents important project information for the AI to reference

This helps the AI understand your codebase better, leading to more accurate and relevant responses.

Your First Task

Now that you’ve configured authentication and initialized your project, you’re ready to start using OpenCode.

Start the TUI

opencode tui

Switch Between Agents

OpenCode includes two built-in agents:

  • build (default): Full-access agent for development work
  • plan: Read-only agent for analysis and code exploration

Press Tab to switch between agents.

Example Tasks

Here are some example tasks you can try:

  1. Code Explanation: “Explain how the authentication flow works in this project”
  2. Bug Fixing: “Find and fix the bug in the login component”
  3. Refactoring: “Refactor the user profile component to use hooks”
  4. Documentation: “Generate documentation for the API endpoints”
  5. Testing: “Write unit tests for the checkout functionality”

Multi-Session Support

You can run multiple agents in parallel within the same project:

# Start a new session
opencode tui

# In another terminal, start another session
opencode tui

Each session operates independently, allowing you to work on different tasks simultaneously.

You can share any session link for reference or debugging:

opencode share <session-id>

This generates a shareable link that others can use to view your session.

Verification

To verify your setup is working correctly:

  1. Run opencode models to see the available models from your configured provider
  2. Run opencode stats to check your usage statistics
  3. Try a simple query like “Explain how to use promises in JavaScript”

Next Steps

Happy coding with OpenCode!