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>
3.0 KiB
Quickstart
Five minutes from
curlto 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.