mirror of
https://github.com/wesammustafa/opencode-primer.git
synced 2026-11-18 18:04:22 +00:00
- Bump every version pin, pricing table, and model ID to the verified 2026-07-05 state (v1.17.13): Claude Fable 5 / Sonnet 5 on Zen, new free tier, deprecation sunset table, v1.17.x changelog section - Cover gaps: OpenCode Go vs Zen billing, Anthropic subscription-login removal (PR #18186), MCP resources, --mini mode, --auto flag, yolo mode - Fix correctness bugs: command-template !`cmd` syntax in docs and .opencode/commands, protect-secrets regex missing 'cat .env', dual plugin exports, quickstart PATH fix, Playwright MCP flags, ctrl+d keybind conflict, agent/command required-field claims - Fix links: cursor.com, windsurf.com, platform.claude.com, code.claude.com, opencode.ai/discord, Vercel Grep announcement - Rebrand: banner (Images/banner.svg), 1280x640 social preview asset, hero redesign with star CTA, ecosystem stats, private vulnerability reporting channel, CI-matching local checks, MD060 lint opt-out
118 lines
3.3 KiB
Markdown
118 lines
3.3 KiB
Markdown
# Quickstart
|
|
|
|
> Five minutes from `curl` to your first AI-assisted commit.
|
|
|
|
## 1. Install
|
|
|
|
Pick one:
|
|
|
|
```bash
|
|
# Recommended: install script (auto-detects OS)
|
|
curl -fsSL https://opencode.ai/install | bash
|
|
|
|
# Or via a package manager you already use:
|
|
npm i -g opencode-ai@latest
|
|
brew install anomalyco/tap/opencode
|
|
scoop install opencode
|
|
choco install opencode
|
|
sudo pacman -S opencode
|
|
paru -S opencode-bin
|
|
mise use -g github:anomalyco/opencode
|
|
nix run nixpkgs#opencode
|
|
```
|
|
|
|
A desktop app (beta) for macOS / Windows / Linux is at [opencode.ai/download](https://opencode.ai/download).
|
|
|
|
Verify:
|
|
|
|
```bash
|
|
opencode --version
|
|
```
|
|
|
|
## 2. Sign in to a provider
|
|
|
|
You need an LLM provider. The fastest path is **OpenCode Zen** — one key, dozens of curated models, pay-as-you-go.
|
|
|
|
```bash
|
|
# Visit https://opencode.ai/auth, sign up, add billing, copy your API key.
|
|
# Then:
|
|
opencode auth login
|
|
# Choose "OpenCode Zen" and paste the key.
|
|
```
|
|
|
|
Or sign in directly to Anthropic, OpenAI, Google, Groq, OpenRouter, AWS Bedrock, Azure, Ollama, LM Studio, etc. See [opencode.ai/docs/providers](https://opencode.ai/docs/providers) for the full list.
|
|
|
|
## 3. Open OpenCode in a real project
|
|
|
|
```bash
|
|
cd ~/your-project
|
|
opencode
|
|
```
|
|
|
|
The TUI launches. Try one of these:
|
|
|
|
| Prompt | What happens |
|
|
|---|---|
|
|
| `explain what this codebase does` | Reads the repo, summarizes |
|
|
| `find every TODO comment` | Greps and lists them |
|
|
| `find and fix the failing test in src/api.test.ts` | Diagnoses, edits, runs tests |
|
|
|
|
## 4. Generate `AGENTS.md`
|
|
|
|
```
|
|
/init
|
|
```
|
|
|
|
This walks you through generating a project-level instructions file (build/test commands, conventions, architecture). Commit it — it's read every session.
|
|
|
|
## 5. Learn the two essential shortcuts
|
|
|
|
| Key | Purpose |
|
|
|---|---|
|
|
| `Tab` | Cycle primary agents (default: `build` ↔ `plan`) |
|
|
| `Esc` | Cancel / dismiss |
|
|
|
|
Two character prefixes that change how you talk to OpenCode in prompts:
|
|
|
|
| Prefix | Purpose | Example |
|
|
|---|---|---|
|
|
| `@<path>` | Attach a file's content (fuzzy resolved) | `look at @src/api/auth.ts` |
|
|
| `!<cmd>` | Run shell, inject output | `!git diff` then ask the model about it |
|
|
|
|
## What next?
|
|
|
|
- **[Custom Commands](commands.md)** — turn prompts into `/<name>` shortcuts (~3 min)
|
|
- **[OpenCode Zen](zen.md)** — model picks, pricing, and BYOK
|
|
- **[Agents](agents.md)** — custom build/plan variants and subagents
|
|
- **[Agent Skills](skills.md)** — workflows the agent discovers and loads on its own
|
|
- **[Plugins](plugins.md)** — run code automatically on lifecycle events
|
|
- **[MCP](mcp.md)** — plug in external tools (browsers, DBs, search)
|
|
|
|
## Common first-day issues
|
|
|
|
**`opencode: command not found`**
|
|
|
|
The install script puts the binary in `~/.opencode/bin`. Add it to your shell config:
|
|
|
|
```bash
|
|
echo 'export PATH="$HOME/.opencode/bin:$PATH"' >> ~/.zshrc # or ~/.bashrc
|
|
source ~/.zshrc
|
|
```
|
|
|
|
(If you installed via `npm i -g`, the binary lands in npm's global bin directory instead — usually already on your `PATH`.)
|
|
|
|
**Auth fails with "no provider configured"**
|
|
|
|
Run `opencode auth login` and pick a provider. Re-run `/connect` from inside the TUI if you want to add another.
|
|
|
|
**Want to upgrade later?**
|
|
|
|
```bash
|
|
opencode upgrade # latest
|
|
opencode upgrade v1.17.13 # specific version
|
|
```
|
|
|
|
---
|
|
|
|
*Last reviewed: 2026-07-05 · Canonical source: [opencode.ai/docs](https://opencode.ai/docs/).*
|