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.
Type @ followed by a filename to include specific files in your conversation context.
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 B: Third-Party Provider
If you already have an API key for a supported provider:
- Select your provider (e.g., Anthropic, OpenAI, Google, Groq, Together AI)
- Enter your API key when prompted
- For custom endpoints, choose Add Provider and enter the base URL and API key
Popular providers and their setup guides:
| Provider | Setup |
|---|---|
| Anthropic Claude | Get key from console.anthropic.com |
| OpenAI | Get key from platform.openai.com |
| Google Gemini | Get key from aistudio.google.com |
| Groq | Get key from console.groq.com |
| Together AI | Get 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
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.
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