Skip to main content

Quick Start

Get opencode up and running with a provider and your project in under five minutes.

1. Install opencode​

If you haven't already, install opencode using the method that works best for your system:

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

Or via npm:

npm install -g opencode-ai

See the Installation guide for all supported methods (Homebrew, Arch Linux, Docker, Windows, and more).

After installing, verify it works:

opencode --version

2. Launch opencode​

Navigate to an existing project or create a new directory to experiment in:

mkdir -p ~/my-project && cd ~/my-project
opencode

This starts the opencode Terminal User Interface (TUI). You'll see a chat interface with a prompt at the bottom. This is where you'll interact with opencode's AI agents.

3. Configure an LLM Provider​

opencode needs access to an LLM to function. Run the /connect command in the TUI:

/connect

A provider selection menu appears. You have two main paths:

Option A: OpenCode Zen (Simplest)​

OpenCode Zen is opencode's curated model service. It provides access to tested and verified models without needing separate provider accounts.

  1. Select OpenCode Zen from the provider list
  2. A URL will be displayed for authentication
  3. Open the URL in your browser and sign in (or create an account)
  4. Copy the displayed API key
  5. Paste it into opencode's prompt when asked

Once connected, run /models to see the recommended models for your tasks.

Option B: Third-Party Provider​

If you already have an API key for a supported provider:

  1. Select your provider (e.g., Anthropic, OpenAI, Google, Groq, Together AI)
  2. Enter your API key when prompted
  3. For custom endpoints, choose Add Provider and enter the base URL and API key

Popular providers and their setup guides:

ProviderSetup
Anthropic ClaudeGet key from console.anthropic.com
OpenAIGet key from platform.openai.com
Google GeminiGet key from aistudio.google.com
GroqGet key from console.groq.com
Together AIGet key from api.together.ai
Ollama (local)Run ollama serve locally, connect as provider

4. Initialize Project Context​

Tell opencode about your project by running /init:

/init

This command:

  • Scans your project structure and identifies the tech stack
  • Creates an AGENTS.md file with project context (commit this to git!)
  • Sets up file-watching for automatic context updates
  • Indexes your codebase for fast file search with @ references

For example, if your project uses React, TypeScript, and Tailwind, opencode will note these conventions and apply them when generating code.

5. Start Asking Questions​

You can now interact with opencode using natural language. Try these examples:

Understand your codebase​

What does this project do? Explain the architecture.

Reference specific files​

Use @ to reference files:

How does the authentication flow work in @auth.ts?

Get explanations​

Explain the database schema and how migrations work.

Ask for code changes​

Add a loading spinner to the button component.

Debug issues​

I'm getting a 401 error when calling the /api/users endpoint. Why?

6. Use Plan Mode for Complex Tasks​

Switch to Plan mode by pressing the Tab key. In Plan mode, opencode's agent analyzes your request, researches the codebase, and produces a detailed plan before modifying any files.

This is ideal for:

  • Adding a new feature
  • Refactoring a module
  • Migrating a dependency
  • Setting up CI/CD pipelines

After reviewing the plan, press Tab again to switch back to Build mode and execute the changes.

7. Undo Changes​

opcode automatically creates git snapshots before each modification. To revert the last change:

/undo

To redo:

/redo

You can undo multiple steps sequentially. Each undo reverts to the previous snapshot.

8. Share Your Session​

Share the full session transcript with teammates:

/share

This creates a shareable URL containing the entire conversation, file diffs, and tool outputs. Useful for code reviews, debugging sessions, and onboarding.

9. Session Management​

opencode saves all sessions automatically. List them with:

/sessions

You can switch between sessions, navigate child/parent session trees, and continue previous conversations. Start a fresh session with:

/new

Tips for Effective Use​

Commit AGENTS.md to Git​

When you run /init, opencode creates an AGENTS.md file in your project root. This file contains project context, conventions, and instructions that opencode uses on every interaction. Commit this file to your repository so teammates and CI/CD pipelines benefit from the same context.

Use @ for File References​

When asking questions or requesting changes, reference files with @:

What does @utils/helpers.ts do?
Update the error handling in @api/routes/users.ts
Compare @auth.ts and @auth.test.ts

Press Tab after typing @ to trigger autocomplete.

Drag and Drop Images​

For vision-enabled models, drag and drop images directly into the TUI. This works for:

  • Screenshots of bugs or UI issues
  • Design mockups
  • Diagrams and architecture sketches
  • Error messages

Start Small​

If you're new to AI coding agents, start with simple tasks:

  1. Ask for explanations of existing code
  2. Request small, focused changes (fix a bug, add a comment)
  3. Gradually move to larger tasks (add a feature, refactor a module)

Use Separate Sessions for Different Tasks​

Each /new session is isolated. Use separate sessions for:

  • Bug fixes vs. feature development
  • Different feature branches
  • Exploration vs. execution

Check Provider Context Window​

Models have different context window sizes. If you're working with a large codebase, consider:

  • Using a provider with a large context window (e.g., Gemini 2M, Claude 200K)
  • Being specific about which files to reference
  • Using the /compact command to summarize and compress session history

Next Steps​

  • Key Features -- Learn everything opencode can do
  • CLI Usage -- Use opencode non-interactively in scripts and CI/CD
  • Terminal UI -- Master TUI commands, keybinds, and customization
  • Agents -- Deep dive into the agent system