Files
opencode-primer/docs/quickstart.md
T
Wesam AbousaidandClaude Opus 4.8 29a69a35b0 docs: refresh for OpenCode v1.16.2 and fix correctness bugs
Update the guide to the current release (v1.16.2, 2026-06-05), verified
against opencode.ai/docs and github.com/anomalyco/opencode.

Correctness fixes:
- Plugins: tool.execute.before/after and shell.env are top-level hooks
  with an (input, output) signature, not event.type values. Rewrite both
  shipped example plugins plus the docs/migration examples so they fire.
- Permissions: bash glob maps resolve last-matching-rule-wins (catch-all
  "*" first), not most-specific-wins. Fix prose, reorder examples, and fix
  the shipped opencode.json (rm -rf* deny was shadowed by a later rm *).
- Drop non-existent permission keys repo_clone/repo_overview (15 keys, not
  17); fix steps (integer), deprecate maxSteps/tools, move reasoningEffort
  into model options; fix the `mise` install command.

Currency updates:
- v1.15.4 -> v1.16.2; add v1.16 highlights and a changelog section.
- Refresh OpenCode Zen lineup/pricing (Claude Opus 4.8, gpt-5.4,
  gemini-3.5-flash, qwen3.7, grok-build-0.1; correct free-tier IDs).
- Add `opencode mcp add`, run --replay, extra skill paths, shift+tab, and
  native GitHub commands; correct the specialist-prompt count; bump dates.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-08 19:00:39 +02:00

3.0 KiB

Quickstart

Five minutes from curl to your first AI-assisted commit.

1. Install

Pick one:

# 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.

Verify:

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.

# 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 for the full list.

3. Open OpenCode in a real project

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 Claude about it

What next?

  • Custom Commands — turn prompts into /<name> shortcuts (~3 min)
  • OpenCode Zen — model picks, pricing, and BYOK
  • Agents — custom build/plan variants and subagents
  • MCP — plug in external tools (browsers, DBs, search)

Common first-day issues

opencode: command not found

Add the install path to your shell config:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc   # or ~/.bashrc
source ~/.zshrc

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?

opencode upgrade            # latest
opencode upgrade v1.16.0    # specific version

Last reviewed: 2026-06-08 · Canonical source: opencode.ai/docs.