mirror of
https://github.com/wesammustafa/opencode-primer.git
synced 2026-11-18 18:04:22 +00:00
docs(reference): add CLI, slash-commands, permissions, FAQ, changelog, further-reading
Six reference pages, each a single-purpose cheatsheet: - cli.md: full CLI surface (21 commands + global flags + experimental env vars) sourced from packages/web/src/content/docs/cli.mdx - slash-commands.md: every built-in TUI slash command verified against packages/web/src/content/docs/tui.mdx - permissions.md: all 17 permission keys verified against PermissionConfig in the JSON schema (read, edit, bash, glob, grep, list, task, todowrite, question, external_directory, repo_clone, repo_overview, webfetch, websearch, lsp, skill, doom_loop) - faq.md: covers free-vs-paid, OpenCode vs Claude Code, offline, model picks (multi-provider, not Anthropic-only), config locations, sharing, privacy, migration, troubleshooting - changelog.md: notable releases through v1.15.4 (verified via GitHub releases API, published 2026-05-17T17:44Z) - further-reading.md: curated external resources — only links that resolve (link-checked at commit time)
This commit is contained in:
@@ -0,0 +1,64 @@
|
||||
# Changelog Highlights
|
||||
|
||||
> Notable OpenCode releases. For the authoritative, complete list, see [github.com/anomalyco/opencode/releases](https://github.com/anomalyco/opencode/releases).
|
||||
|
||||
This document tracks **what's new at a high level** — the things that change how you use OpenCode. Bug fixes and small polish items aren't listed here.
|
||||
|
||||
## v1.15.x — May 2026
|
||||
|
||||
Current stable line. Run `opencode upgrade` to get the latest.
|
||||
|
||||
**Verified latest release:** `v1.15.4`, published 2026-05-17 17:44 UTC ([GitHub release](https://github.com/anomalyco/opencode/releases/tag/v1.15.4)).
|
||||
|
||||
**Highlights:**
|
||||
|
||||
- **Agent Skills compatibility** — discoverable workflows via `SKILL.md` folders; compatible with Claude Code skill format.
|
||||
- **Glob-pattern bash permissions** — fine-grained `allow`/`ask`/`deny` per command pattern, with most-specific wins.
|
||||
- **Managed configs** — `/Library/Application Support/opencode/` (macOS), `/etc/opencode/` (Linux), `%ProgramData%\opencode` (Windows), plus macOS MDM preferences for enterprise rollouts.
|
||||
- **ACP server** (`opencode acp`) — Agent Client Protocol server for editor integrations.
|
||||
- **Remote MCP with auto-OAuth** — Dynamic Client Registration (RFC 7591) handled automatically.
|
||||
- **Desktop app (beta)** — macOS, Windows, Linux at [opencode.ai/download](https://opencode.ai/download).
|
||||
- **`AGENTS.md` is canonical** — `CLAUDE.md` remains a fallback for migration (`OPENCODE_DISABLE_CLAUDE_CODE=1` disables it).
|
||||
|
||||
## Earlier 2026
|
||||
|
||||
- **Plugin event surface expanded** — `session.idle`, `session.compacted`, `tui.toast.show` and more.
|
||||
- **`opencode pr <num>`** — check out a GitHub PR branch and start a session in it.
|
||||
- **`opencode stats`** — per-day, per-model, per-project breakdowns.
|
||||
- **TUI command palette** (`ctrl+p`) — fuzzy-pick slash commands.
|
||||
- **`tools` glob patterns** — enable/disable groups of MCP tools.
|
||||
- **`/details` and `/thinking`** — toggle tool-output and thinking-block visibility from inside the TUI.
|
||||
|
||||
## 2025
|
||||
|
||||
Founding releases. Highlights from this period:
|
||||
|
||||
- **TUI launch** — terminal UI as the primary interface.
|
||||
- **MCP support** — both local and remote servers.
|
||||
- **Plugin system** — JS/TS event-driven extensions.
|
||||
- **OpenCode Zen** — curated model gateway with pay-as-you-go billing.
|
||||
- **`/share`** — public conversation links via `opncd.ai/s/<id>`.
|
||||
- **`opencode serve` / `opencode web`** — headless and web-UI modes.
|
||||
|
||||
---
|
||||
|
||||
## Coming soon (roadmap topics)
|
||||
|
||||
These are themes the OpenCode team has discussed publicly — not commitments to ship by a specific date.
|
||||
|
||||
- Deeper IDE integrations via ACP
|
||||
- Expanded plugin event surface
|
||||
- More built-in agents and skills
|
||||
- Workspace sync across devices
|
||||
|
||||
For the current state, check the [GitHub repo](https://github.com/anomalyco/opencode), the [discussions](https://github.com/anomalyco/opencode/discussions), and [opencode.ai/docs](https://opencode.ai/docs).
|
||||
|
||||
---
|
||||
|
||||
## Deprecations
|
||||
|
||||
- `CLAUDE.md` as a primary instructions file — use `AGENTS.md`. (Fallback still works; disable with `OPENCODE_DISABLE_CLAUDE_CODE=1`.)
|
||||
|
||||
---
|
||||
|
||||
*Last reviewed: 2026-05-18 · For the authoritative list, see [GitHub releases](https://github.com/anomalyco/opencode/releases) · Canonical docs: [opencode.ai/docs](https://opencode.ai/docs/).*
|
||||
@@ -0,0 +1,311 @@
|
||||
# CLI Reference
|
||||
|
||||
> Complete command-line reference for OpenCode. All commands run from a terminal.
|
||||
|
||||
```
|
||||
opencode [command] [flags]
|
||||
```
|
||||
|
||||
## Default behavior
|
||||
|
||||
Running `opencode` with no command starts the TUI in the current directory. This is the same as `opencode tui`.
|
||||
|
||||
## Global flags
|
||||
|
||||
| Flag | Purpose |
|
||||
|---|---|
|
||||
| `--help`, `-h` | Display help |
|
||||
| `--version`, `-v` | Print version |
|
||||
| `--print-logs` | Print logs to stderr |
|
||||
| `--log-level <level>` | `DEBUG` \| `INFO` \| `WARN` \| `ERROR` |
|
||||
| `--pure` | Run without loading external plugins |
|
||||
|
||||
---
|
||||
|
||||
## `opencode` / `opencode tui`
|
||||
|
||||
Start the terminal UI.
|
||||
|
||||
```bash
|
||||
opencode [project] [flags]
|
||||
```
|
||||
|
||||
| Flag | Purpose |
|
||||
|---|---|
|
||||
| `--continue`, `-c` | Continue the last session |
|
||||
| `--session <id>`, `-s` | Continue a specific session |
|
||||
| `--fork` | Fork the session when continuing |
|
||||
| `--prompt <text>` | Pre-fill prompt |
|
||||
| `--model <id>`, `-m` | Set model (`provider/model-id`) |
|
||||
| `--agent <name>` | Start with a specific agent |
|
||||
| `--port`, `--hostname` | Bind the underlying server |
|
||||
| `--mdns`, `--mdns-domain` | mDNS discovery |
|
||||
| `--cors <origins>` | Additional browser origins for CORS |
|
||||
|
||||
---
|
||||
|
||||
## `opencode run`
|
||||
|
||||
Run OpenCode non-interactively with a prompt.
|
||||
|
||||
```bash
|
||||
opencode run "summarize the last 5 commits"
|
||||
opencode run --format json "list every TODO with file and line"
|
||||
opencode run --agent plan --model anthropic/claude-haiku-4-5 "audit src/ for missing input validation"
|
||||
```
|
||||
|
||||
| Flag | Purpose |
|
||||
|---|---|
|
||||
| `--continue`, `-c` | Continue the last session |
|
||||
| `--session <id>`, `-s` | Continue a specific session |
|
||||
| `--fork` | Fork the session when continuing |
|
||||
| `--share` | Share the session |
|
||||
| `--model <id>`, `-m` | Model in `provider/model-id` form |
|
||||
| `--agent <name>` | Agent to use |
|
||||
| `--file <path>`, `-f` | Attach file(s) to the message |
|
||||
| `--format <default\|json>` | Output format |
|
||||
| `--title <text>` | Title for the session |
|
||||
| `--attach <url>` | Attach to a running OpenCode server |
|
||||
| `--password`, `-p` · `--username`, `-u` | Basic auth for the attached server |
|
||||
| `--dir <path>` | Directory to run in |
|
||||
| `--port` | Port for the local server backing this run |
|
||||
| `--variant <name>` | Model variant |
|
||||
| `--thinking` | Show thinking blocks |
|
||||
| `--command <name>` | Run a saved command |
|
||||
| `--dangerously-skip-permissions` | Auto-approve everything that isn't explicitly denied. **CI only.** |
|
||||
|
||||
---
|
||||
|
||||
## `opencode auth`
|
||||
|
||||
Manage provider credentials.
|
||||
|
||||
```bash
|
||||
opencode auth login [--provider <id>] [--method <label>]
|
||||
opencode auth list # alias: ls
|
||||
opencode auth logout
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## `opencode agent`
|
||||
|
||||
Manage agents.
|
||||
|
||||
```bash
|
||||
opencode agent list
|
||||
opencode agent create [flags]
|
||||
```
|
||||
|
||||
`create` flags:
|
||||
|
||||
| Flag | Purpose |
|
||||
|---|---|
|
||||
| `--path <dir>` | Directory for the new agent file |
|
||||
| `--description <text>` | Agent description |
|
||||
| `--mode <primary\|subagent\|all>` | Agent mode |
|
||||
| `--permissions <list>` | Comma-separated allowed permissions |
|
||||
| `--model <id>`, `-m` | Model to use |
|
||||
|
||||
---
|
||||
|
||||
## `opencode mcp`
|
||||
|
||||
Manage MCP servers.
|
||||
|
||||
```bash
|
||||
opencode mcp add # interactive add
|
||||
opencode mcp list # alias: ls
|
||||
opencode mcp auth <name> # complete OAuth
|
||||
opencode mcp logout <name>
|
||||
opencode mcp debug <name>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## `opencode models`
|
||||
|
||||
List available models.
|
||||
|
||||
```bash
|
||||
opencode models [provider]
|
||||
```
|
||||
|
||||
| Flag | Purpose |
|
||||
|---|---|
|
||||
| `--refresh` | Re-fetch from models.dev |
|
||||
| `--verbose` | Show metadata |
|
||||
|
||||
---
|
||||
|
||||
## `opencode session`
|
||||
|
||||
Manage sessions.
|
||||
|
||||
```bash
|
||||
opencode session list [--max-count <n>] [--format <table\|json>]
|
||||
opencode session delete <sessionID>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## `opencode stats`
|
||||
|
||||
Token usage and cost report.
|
||||
|
||||
```bash
|
||||
opencode stats [flags]
|
||||
```
|
||||
|
||||
| Flag | Purpose |
|
||||
|---|---|
|
||||
| `--days <n>` | Window in days |
|
||||
| `--tools <n>` | Number of tools to show |
|
||||
| `--models` | Show per-model breakdown |
|
||||
| `--project <name>` | Filter by project |
|
||||
|
||||
---
|
||||
|
||||
## `opencode export` / `opencode import`
|
||||
|
||||
Move sessions in and out of OpenCode.
|
||||
|
||||
```bash
|
||||
opencode export <sessionID> [--sanitize] > session.json
|
||||
opencode import session.json
|
||||
opencode import https://opncd.ai/s/<share-id>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## `opencode serve` / `opencode web`
|
||||
|
||||
Run OpenCode as a headless server (`serve`) or with a web UI (`web`).
|
||||
|
||||
```bash
|
||||
opencode serve --port 4096 --hostname 0.0.0.0
|
||||
opencode web --port 4096
|
||||
```
|
||||
|
||||
| Flag | Purpose |
|
||||
|---|---|
|
||||
| `--port` | Listening port |
|
||||
| `--hostname` | Bind address |
|
||||
| `--mdns`, `--mdns-domain` | mDNS |
|
||||
| `--cors <origins>` | Browser CORS origins |
|
||||
|
||||
---
|
||||
|
||||
## `opencode attach`
|
||||
|
||||
Attach a TUI to an already-running OpenCode server.
|
||||
|
||||
```bash
|
||||
opencode attach http://localhost:4096
|
||||
```
|
||||
|
||||
| Flag | Purpose |
|
||||
|---|---|
|
||||
| `--dir <path>` | Working dir to start in |
|
||||
| `--continue`, `-c` · `--session <id>` · `--fork` | Session controls |
|
||||
| `--username`, `-u` · `--password`, `-p` | Basic auth |
|
||||
|
||||
---
|
||||
|
||||
## `opencode acp`
|
||||
|
||||
Start an Agent Client Protocol server (for editor integrations).
|
||||
|
||||
```bash
|
||||
opencode acp --cwd . --port 4099
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## `opencode plugin`
|
||||
|
||||
Install or update a plugin.
|
||||
|
||||
```bash
|
||||
opencode plugin <module> # alias: opencode plug
|
||||
opencode plugin --global opencode-wakatime
|
||||
opencode plugin --force opencode-helicone-session@1.2.3
|
||||
```
|
||||
|
||||
| Flag | Purpose |
|
||||
|---|---|
|
||||
| `--global`, `-g` | Install in global config |
|
||||
| `--force`, `-f` | Replace existing plugin version |
|
||||
|
||||
---
|
||||
|
||||
## `opencode github`
|
||||
|
||||
Manage the GitHub agent integration.
|
||||
|
||||
```bash
|
||||
opencode github install # add workflow file to repo
|
||||
opencode github run [--event <name>] [--token <token>]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## `opencode pr`
|
||||
|
||||
Check out a GitHub PR and start OpenCode in that workspace.
|
||||
|
||||
```bash
|
||||
opencode pr 123
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## `opencode db`
|
||||
|
||||
Database tools (advanced).
|
||||
|
||||
```bash
|
||||
opencode db path # print the database path
|
||||
opencode db "<query>" [--format json|tsv]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## `opencode debug`
|
||||
|
||||
Various debugging utilities. Run `opencode debug --help` for the live subcommand list.
|
||||
|
||||
---
|
||||
|
||||
## `opencode upgrade`
|
||||
|
||||
Update OpenCode to the latest or a specific version.
|
||||
|
||||
```bash
|
||||
opencode upgrade
|
||||
opencode upgrade v1.15.0
|
||||
opencode upgrade --method brew # force the install method
|
||||
```
|
||||
|
||||
| Flag | Purpose |
|
||||
|---|---|
|
||||
| `--method <m>` | `curl` \| `npm` \| `pnpm` \| `bun` \| `brew` |
|
||||
|
||||
---
|
||||
|
||||
## `opencode uninstall`
|
||||
|
||||
Remove OpenCode and (optionally) all related data.
|
||||
|
||||
```bash
|
||||
opencode uninstall [--keep-config] [--keep-data] [--dry-run] [--force]
|
||||
```
|
||||
|
||||
| Flag | Purpose |
|
||||
|---|---|
|
||||
| `--keep-config`, `-c` | Keep configuration files |
|
||||
| `--keep-data`, `-d` | Keep session data and snapshots |
|
||||
| `--dry-run` | Print what would be removed |
|
||||
| `--force`, `-f` | Skip confirmation |
|
||||
|
||||
> 📚 Full live CLI reference: [opencode.ai/docs/cli](https://opencode.ai/docs/cli).
|
||||
@@ -0,0 +1,252 @@
|
||||
# FAQ & Troubleshooting
|
||||
|
||||
## Getting started
|
||||
|
||||
### Q: Is OpenCode free?
|
||||
|
||||
The software is free and open-source (MIT). You pay for whichever LLM provider you use:
|
||||
|
||||
- **OpenCode Zen** — pay-as-you-go, fractions of a cent per request. Free models available for learning.
|
||||
- **Direct providers** — your own Anthropic/OpenAI/Google/etc. account; pricing is whatever they charge.
|
||||
- **Local models** — free if you're running Ollama/LM Studio/llama.cpp on your own hardware.
|
||||
|
||||
### Q: What's the difference between OpenCode and Claude Code?
|
||||
|
||||
Briefly: OpenCode is **provider-agnostic and open source**; Claude Code is **Anthropic-only and proprietary**.
|
||||
|
||||
| | OpenCode | Claude Code |
|
||||
|---|---|---|
|
||||
| License | MIT | Proprietary |
|
||||
| Models | Any provider | Anthropic only |
|
||||
| Pricing | Pay-as-you-go or BYOK | Subscription |
|
||||
| Config | `opencode.json` + `.opencode/` | `.claude/settings.json` + `.claude/` |
|
||||
| Hooks | JS/TS plugins | Python scripts |
|
||||
|
||||
OpenCode reads `CLAUDE.md` and `.claude/skills/` as fallbacks for easier migration.
|
||||
|
||||
### Q: Does OpenCode work offline?
|
||||
|
||||
Yes, if you point it at a local model (Ollama, LM Studio, llama.cpp). Internet access is needed for hosted providers, remote MCP servers, sharing, and updates.
|
||||
|
||||
### Q: Which model should I use?
|
||||
|
||||
Honest answer: **try a few on your actual workload.** Benchmarks generalize poorly to specific codebases. Below are starting suggestions, not a ranking — different teams report different winners.
|
||||
|
||||
| Task | Reasonable options |
|
||||
|---|---|
|
||||
| Day-to-day coding | Claude Sonnet (4.5 direct or 4.6 via Zen), GPT-5.4, Gemini 3.1 Pro |
|
||||
| Complex multi-file refactors | Claude Opus 4.7, GPT-5.5, GPT-5.5 Pro |
|
||||
| Fast, lightweight tasks | Claude Haiku 4.5, GPT-5.4 Mini, GPT-5.4 Nano, GLM/Kimi |
|
||||
| Long-context (>200K tokens) | GPT-5.5 (272K), Claude Sonnet 4.5/4 (>200K tier) |
|
||||
| Budget-friendly | Qwen3.6 Plus, GPT-5.4 Nano, Qwen3.5 Plus, MiniMax M2.7 |
|
||||
| Local / offline | Ollama or LM Studio with a coding-tuned model that fits your hardware (Qwen 2.5 Coder, DeepSeek Coder, CodeLlama — quality varies hugely with model size and quantization) |
|
||||
|
||||
Use a cheaper model for `explore`/`scout` subagents — they read a lot but don't need to write. See [`../zen.md`](../zen.md) for full pricing and the cheap-explorer / strong-executor pattern.
|
||||
|
||||
> No single model wins every benchmark, and benchmarks don't predict your code. If a model feels wrong, switch — model identity matters more than people often think.
|
||||
|
||||
---
|
||||
|
||||
## Configuration
|
||||
|
||||
### Q: Where does OpenCode store config?
|
||||
|
||||
| Type | Path |
|
||||
|---|---|
|
||||
| User config | `~/.config/opencode/opencode.json` |
|
||||
| Project config | `opencode.json` in project root |
|
||||
| Project assets | `.opencode/` in project root |
|
||||
| Sessions / cache | `~/.local/share/opencode/` (Linux/macOS) |
|
||||
| Logs | `~/.local/share/opencode/log/` |
|
||||
| Custom path | Set `OPENCODE_CONFIG=<path>` |
|
||||
|
||||
Configs merge from low to high priority: remote `.well-known/opencode` → global → custom path → project → `.opencode/` → inline env var → managed → macOS MDM.
|
||||
|
||||
### Q: How do I share config across a team?
|
||||
|
||||
Commit `opencode.json`, `AGENTS.md`, `.opencode/agents/`, `.opencode/commands/`, `.opencode/skills/`, and `.opencode/plugins/` to your repo. Every contributor's OpenCode picks them up.
|
||||
|
||||
For org-wide defaults, use **managed configs** (`/Library/Application Support/opencode/` on macOS, `/etc/opencode/` on Linux, `%ProgramData%\opencode` on Windows) — they override user config but lose to MDM-pushed configs.
|
||||
|
||||
### Q: How do I use a remote config endpoint?
|
||||
|
||||
Configure your domain's `.well-known/opencode` to return JSON. OpenCode fetches it as the lowest-priority config layer — useful for org-wide defaults that users can override.
|
||||
|
||||
---
|
||||
|
||||
## Commands & skills
|
||||
|
||||
### Q: Custom command vs. skill vs. agent — which should I write?
|
||||
|
||||
| You want… | Reach for… |
|
||||
|---|---|
|
||||
| A `/<name>` the user types | **Custom command** in `.opencode/commands/` |
|
||||
| Workflow the agent **discovers** when the description matches | **Skill** in `.opencode/skills/<name>/SKILL.md` |
|
||||
| A persistent role with its own model and permissions | **Agent** in `.opencode/agents/<name>.md` |
|
||||
|
||||
See [`../commands.md`](../commands.md), [`../skills.md`](../skills.md), [`../agents.md`](../agents.md).
|
||||
|
||||
### Q: My skill isn't being discovered. Why?
|
||||
|
||||
Almost always the `description` is too vague. Skills load when the model decides the description matches the task. Rewrite the description to:
|
||||
|
||||
- Start with what it does (verb-first)
|
||||
- Name the output concretely
|
||||
- Include a trigger phrase ("Use when…")
|
||||
|
||||
Bad: `Helps with releases`
|
||||
Good: `Draft release notes from merged PRs, propose a semver bump, emit a gh release create command. Use when preparing a tagged release.`
|
||||
|
||||
### Q: Why is my agent slow?
|
||||
|
||||
Most common culprits:
|
||||
|
||||
1. **Too many MCP tools loaded** → run `opencode mcp list`, disable noisy ones in `tools`.
|
||||
2. **Big context** → `/compact` aggressively.
|
||||
3. **Slow model** → switch to a faster one with `/models`.
|
||||
4. **Watcher choking on large repo** → add ignore patterns under `watcher.ignore` in `opencode.json`.
|
||||
|
||||
---
|
||||
|
||||
## CLI & headless
|
||||
|
||||
### Q: How do I run OpenCode in CI?
|
||||
|
||||
```bash
|
||||
curl -fsSL https://opencode.ai/install | bash
|
||||
opencode run --agent plan --format json "audit src/ for security issues" > findings.json
|
||||
```
|
||||
|
||||
For unattended runs, `--dangerously-skip-permissions` auto-approves anything that isn't explicitly denied — only after auditing what your prompt and tools can do.
|
||||
|
||||
### Q: Can I attach a remote OpenCode server?
|
||||
|
||||
Yes:
|
||||
|
||||
```bash
|
||||
# Server side
|
||||
opencode serve --port 4096 --hostname 0.0.0.0
|
||||
|
||||
# Client side
|
||||
opencode attach http://server.local:4096
|
||||
```
|
||||
|
||||
The TUI talks to the remote server. Add `--username` / `--password` for basic auth.
|
||||
|
||||
### Q: How do I track token cost?
|
||||
|
||||
```bash
|
||||
opencode stats --days 30 --models # by model
|
||||
opencode stats --days 30 --tools # by tool
|
||||
opencode stats --days 30 --project myrepo
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Migration
|
||||
|
||||
### Q: I'm coming from Claude Code. What changes?
|
||||
|
||||
See [`../migration.md`](../migration.md) for the full guide. Quick version:
|
||||
|
||||
- Rename `CLAUDE.md` → `AGENTS.md`
|
||||
- Move `.claude/commands/` → `.opencode/commands/`
|
||||
- Move `.claude/skills/` → `.opencode/skills/`
|
||||
- Rewrite Python hooks as JS/TS plugins in `.opencode/plugins/`
|
||||
- Update agent frontmatter — different field names
|
||||
|
||||
### Q: Do my Cursor rules work?
|
||||
|
||||
Yes — reference them from `opencode.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"instructions": [".cursor/rules/*.md", "AGENTS.md"]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Privacy & data
|
||||
|
||||
### Q: Where does my code go?
|
||||
|
||||
- **Local models** — nowhere. Code stays on your machine.
|
||||
- **Direct providers** — the prompt and edited files go to whichever provider you authenticated with, subject to their policy.
|
||||
- **Zen** — Zen is a gateway; the underlying provider's policy still applies, plus Zen's policy for billing/routing. Check [opencode.ai/docs/zen](https://opencode.ai/docs/zen) for the current statement.
|
||||
- **Sharing** (`/share`) — opt-in. Shared conversations live on OpenCode's servers until you unshare them.
|
||||
|
||||
### Q: How do I disable sharing entirely?
|
||||
|
||||
```json
|
||||
{ "share": "disabled" }
|
||||
```
|
||||
|
||||
Commit this to `opencode.json` to enforce it across the team. Enterprise builds can also push this via managed config.
|
||||
|
||||
### Q: How do I protect secrets?
|
||||
|
||||
Three layers:
|
||||
|
||||
1. `permission.external_directory: "deny"` so OpenCode can't read outside the project.
|
||||
2. A plugin that blocks `edit`/`write` to `.env*`/`secrets/` paths (see [`../plugins.md`](../plugins.md#4-block-sensitive-paths)).
|
||||
3. Don't commit secrets in the first place. `gitleaks` or similar in CI.
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Q: `opencode: command not found` after install
|
||||
|
||||
Add the install path to your shell:
|
||||
|
||||
```bash
|
||||
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
|
||||
source ~/.zshrc
|
||||
```
|
||||
|
||||
### Q: Authentication fails
|
||||
|
||||
```bash
|
||||
opencode auth logout
|
||||
opencode auth login # re-authenticate
|
||||
```
|
||||
|
||||
If using Zen, regenerate the API key on the [dashboard](https://opencode.ai/auth).
|
||||
|
||||
### Q: MCP server won't connect
|
||||
|
||||
```bash
|
||||
opencode mcp debug <server-name>
|
||||
opencode --log-level DEBUG --print-logs
|
||||
```
|
||||
|
||||
For OAuth servers, clear creds and re-auth:
|
||||
|
||||
```bash
|
||||
opencode mcp logout <server-name>
|
||||
opencode mcp auth <server-name>
|
||||
```
|
||||
|
||||
### Q: Editor (`/editor`) opens the wrong program
|
||||
|
||||
OpenCode uses `$EDITOR`. Set it in your shell:
|
||||
|
||||
```bash
|
||||
export EDITOR='code --wait' # VS Code
|
||||
export EDITOR='nvim' # Neovim
|
||||
```
|
||||
|
||||
### Q: TUI looks broken / colors wrong
|
||||
|
||||
- Make sure your terminal supports truecolor. Test: `echo $COLORTERM` should show `truecolor` or `24bit`.
|
||||
- Try a built-in theme: `/themes` → pick `tokyonight` or `gruvbox`.
|
||||
- Update OpenCode: `opencode upgrade`.
|
||||
|
||||
### Q: How do I report a bug?
|
||||
|
||||
[github.com/anomalyco/opencode/issues](https://github.com/anomalyco/opencode/issues). Include `opencode --version`, your OS, and a minimal reproduction.
|
||||
|
||||
---
|
||||
|
||||
*Last reviewed: 2026-05-18 · Canonical source: [opencode.ai/docs](https://opencode.ai/docs/).*
|
||||
@@ -0,0 +1,69 @@
|
||||
# Further Reading
|
||||
|
||||
> Curated external resources — official docs, primary sources, and adjacent tooling. Nothing speculative.
|
||||
|
||||
## Official OpenCode
|
||||
|
||||
- **[opencode.ai](https://opencode.ai)** — Home
|
||||
- **[opencode.ai/docs](https://opencode.ai/docs/)** — Full documentation
|
||||
- **[opencode.ai/docs/zen](https://opencode.ai/docs/zen)** — Zen model gateway
|
||||
- **[opencode.ai/download](https://opencode.ai/download)** — Desktop app (beta)
|
||||
- **[github.com/anomalyco/opencode](https://github.com/anomalyco/opencode)** — Source code (MIT)
|
||||
- **[github.com/anomalyco/opencode/releases](https://github.com/anomalyco/opencode/releases)** — Release notes
|
||||
- **[github.com/anomalyco/opencode/discussions](https://github.com/anomalyco/opencode/discussions)** — Community discussions
|
||||
- **[opencode.ai/config.json](https://opencode.ai/config.json)** — JSON schema for `opencode.json`
|
||||
- **[opencode.ai/tui.json](https://opencode.ai/tui.json)** — JSON schema for `tui.json`
|
||||
|
||||
## Topic-specific OpenCode docs
|
||||
|
||||
- **[opencode.ai/docs/cli](https://opencode.ai/docs/cli)** — CLI reference
|
||||
- **[opencode.ai/docs/tui](https://opencode.ai/docs/tui)** — TUI reference
|
||||
- **[opencode.ai/docs/config](https://opencode.ai/docs/config)** — Config reference
|
||||
- **[opencode.ai/docs/agents](https://opencode.ai/docs/agents)** — Agents
|
||||
- **[opencode.ai/docs/commands](https://opencode.ai/docs/commands)** — Custom commands
|
||||
- **[opencode.ai/docs/skills](https://opencode.ai/docs/skills)** — Skills
|
||||
- **[opencode.ai/docs/plugins](https://opencode.ai/docs/plugins)** — Plugins
|
||||
- **[opencode.ai/docs/mcp-servers](https://opencode.ai/docs/mcp-servers)** — MCP
|
||||
- **[opencode.ai/docs/rules](https://opencode.ai/docs/rules)** — `AGENTS.md` and rules
|
||||
- **[opencode.ai/docs/themes](https://opencode.ai/docs/themes)** — Themes
|
||||
- **[opencode.ai/docs/keybinds](https://opencode.ai/docs/keybinds)** — TUI keybinds
|
||||
- **[opencode.ai/docs/share](https://opencode.ai/docs/share)** — Session sharing
|
||||
- **[opencode.ai/docs/permissions](https://opencode.ai/docs/permissions)** — Permission model
|
||||
|
||||
## Model Context Protocol
|
||||
|
||||
- **[modelcontextprotocol.io](https://modelcontextprotocol.io/)** — Protocol home
|
||||
- **[registry.modelcontextprotocol.io](https://registry.modelcontextprotocol.io/)** — Official registry
|
||||
- **[github.com/modelcontextprotocol/servers](https://github.com/modelcontextprotocol/servers)** — Reference server implementations
|
||||
|
||||
## Adjacent AI coding tools (for comparison or coexistence)
|
||||
|
||||
- **[Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview)** — Anthropic's CLI; shares the `.claude/skills/` and `CLAUDE.md` formats OpenCode reads as fallbacks
|
||||
- **[Aider](https://aider.chat/)** — Earlier terminal AI coding tool
|
||||
- **[Cursor](https://cursor.sh/)** — VS Code fork with embedded AI
|
||||
|
||||
## Provider docs (for direct-provider setup)
|
||||
|
||||
- **[Anthropic API](https://docs.anthropic.com/en/api/getting-started)**
|
||||
- **[OpenAI API](https://platform.openai.com/docs)**
|
||||
- **[Google AI / Gemini API](https://ai.google.dev/gemini-api/docs)**
|
||||
- **[Groq](https://console.groq.com/docs)**
|
||||
- **[OpenRouter](https://openrouter.ai/docs)**
|
||||
- **[Ollama](https://ollama.com/library)** — local model runner
|
||||
- **[LM Studio](https://lmstudio.ai/docs)** — local model GUI
|
||||
|
||||
## Prompt engineering — general background
|
||||
|
||||
These aren't OpenCode-specific, but the patterns transfer.
|
||||
|
||||
- **[Anthropic — Prompt engineering overview](https://docs.anthropic.com/en/docs/build-with-claude/prompt-engineering/overview)**
|
||||
- **[Anthropic — Building effective agents](https://www.anthropic.com/engineering/building-effective-agents)**
|
||||
- **[OpenAI — Prompt engineering guide](https://platform.openai.com/docs/guides/prompt-engineering)**
|
||||
|
||||
---
|
||||
|
||||
> Spot a useful resource that should be here? Send a PR — see [`../../CONTRIBUTING.md`](../../CONTRIBUTING.md).
|
||||
|
||||
---
|
||||
|
||||
*Last reviewed: 2026-05-18 · Canonical source: [opencode.ai/docs](https://opencode.ai/docs/).*
|
||||
@@ -0,0 +1,179 @@
|
||||
# Permissions Reference
|
||||
|
||||
> OpenCode's permission system in one page. Verified against the [config JSON schema](https://opencode.ai/config.json) (`PermissionConfig`).
|
||||
|
||||
## The three values
|
||||
|
||||
Every permission accepts one of:
|
||||
|
||||
| Value | Behavior |
|
||||
|---|---|
|
||||
| `"allow"` | Tool runs without prompting |
|
||||
| `"ask"` | User is prompted to approve each use |
|
||||
| `"deny"` | Tool is blocked outright |
|
||||
|
||||
For `bash` (and any rule-style permission), you can also pass a **glob-pattern map** keyed by command pattern — most-specific wins, `*` is the catch-all.
|
||||
|
||||
## Permission keys → what they gate
|
||||
|
||||
| Key | Gates |
|
||||
|---|---|
|
||||
| `read` | `read` |
|
||||
| `edit` | `write`, `edit`, `apply_patch` |
|
||||
| `bash` | shell — supports glob-pattern overrides |
|
||||
| `glob` · `grep` · `list` | search and listing tools |
|
||||
| `task` | spawning subagents |
|
||||
| `todowrite` | in-session todo list |
|
||||
| `question` | the `question` tool |
|
||||
| `external_directory` | files outside the project root |
|
||||
| `repo_clone` | cloning dependency repos into OpenCode's cache (used by `scout`) |
|
||||
| `repo_overview` | repo-summary operations |
|
||||
| `webfetch` · `websearch` | network access |
|
||||
| `lsp` | language-server tools |
|
||||
| `skill` | loading agent skills |
|
||||
| `doom_loop` | runaway-loop safeguards |
|
||||
|
||||
> Note: `write` and `apply_patch` are both gated under the `edit` key, not separately.
|
||||
|
||||
## Built-in tool list
|
||||
|
||||
| Tool | Purpose | Gated by |
|
||||
|---|---|---|
|
||||
| `bash` | Run shell commands | `bash` |
|
||||
| `read` | Read file contents | `read` |
|
||||
| `write` | Create / overwrite a file | `edit` |
|
||||
| `edit` | String-replace edits | `edit` |
|
||||
| `apply_patch` | Apply a unified diff | `edit` |
|
||||
| `grep` | Regex search in files | `grep` |
|
||||
| `glob` | File pattern matching | `glob` |
|
||||
| `lsp` | LSP queries *(experimental — needs `OPENCODE_EXPERIMENTAL_LSP_TOOL=true`)* | `lsp` |
|
||||
| `skill` | Load a skill file's content | `skill` |
|
||||
| `todowrite` | Manage in-session todo list | `todowrite` |
|
||||
| `webfetch` | Fetch a web URL | `webfetch` |
|
||||
| `websearch` | Web search *(needs OpenCode provider or `OPENCODE_EXPERIMENTAL_EXA=1` to use Exa)* | `websearch` |
|
||||
| `question` | Ask the user something mid-execution | `question` |
|
||||
|
||||
## Setting permissions
|
||||
|
||||
### Project-wide (`opencode.json`)
|
||||
|
||||
```json
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"permission": {
|
||||
"edit": "ask",
|
||||
"bash": {
|
||||
"*": "ask",
|
||||
"git status*": "allow",
|
||||
"git diff*": "allow",
|
||||
"pnpm test*": "allow",
|
||||
"rm -rf*": "deny"
|
||||
},
|
||||
"webfetch": "allow",
|
||||
"websearch": "allow"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
You can also use a top-level string (`"permission": "ask"`) to set the same value for every permission at once.
|
||||
|
||||
### Per-agent (`opencode.json`)
|
||||
|
||||
Per-agent settings override project-level for that agent:
|
||||
|
||||
```json
|
||||
{
|
||||
"agent": {
|
||||
"plan": {
|
||||
"permission": {
|
||||
"edit": "deny",
|
||||
"bash": "ask"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Per-agent (markdown frontmatter)
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Read-only reviewer
|
||||
mode: subagent
|
||||
permission:
|
||||
edit: deny
|
||||
bash:
|
||||
"*": "ask"
|
||||
"git diff*": "allow"
|
||||
---
|
||||
```
|
||||
|
||||
## Glob-pattern bash
|
||||
|
||||
The `bash` key accepts a glob-pattern map. Patterns are matched against the full command line.
|
||||
|
||||
```json
|
||||
{
|
||||
"permission": {
|
||||
"bash": {
|
||||
"rm -rf*": "deny",
|
||||
"git push --force*": "deny",
|
||||
"git status*": "allow",
|
||||
"git diff*": "allow",
|
||||
"pnpm test*": "allow",
|
||||
"*": "ask"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Matching rules:**
|
||||
|
||||
- Patterns are evaluated by specificity — most specific match wins; `*` is the catch-all.
|
||||
- `*` matches zero or more characters (including spaces).
|
||||
- `?` matches exactly one character.
|
||||
- Literal text matches exactly.
|
||||
|
||||
## Tool-level on/off (`tools`)
|
||||
|
||||
`tools` is independent from `permission`. It enables/disables a tool entirely.
|
||||
|
||||
```json
|
||||
{
|
||||
"tools": { "websearch": false },
|
||||
"agent": {
|
||||
"research-agent": {
|
||||
"tools": { "websearch": true }
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Glob patterns work too — useful for MCP tools:
|
||||
|
||||
```json
|
||||
{
|
||||
"tools": {
|
||||
"github_*": false,
|
||||
"slack_*": false
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Defaults
|
||||
|
||||
- All tools are **enabled by default**.
|
||||
- Most permissions default to `"allow"` for the `build` agent.
|
||||
- The built-in `plan` agent sets `edit` and `bash` to `"ask"` so analysis sessions can't surprise-write files.
|
||||
- `external_directory` is **opt-in** — files outside the project root require explicit `"allow"`.
|
||||
|
||||
## When to lock things down
|
||||
|
||||
| Scenario | Recommendation |
|
||||
|---|---|
|
||||
| Shared repo, multiple contributors | Commit a restrictive `opencode.json` so everyone's agent has the same guardrails |
|
||||
| CI / headless | Use `--dangerously-skip-permissions` only after auditing what the prompt can reach |
|
||||
| Working with secrets | `external_directory: "deny"` plus a plugin that blocks edits to `.env`/`secrets/` |
|
||||
| First time on a repo | Set `bash: "ask"` everywhere until you trust the workflows |
|
||||
|
||||
> 📚 Live reference: [opencode.ai/docs/permissions](https://opencode.ai/docs/permissions) and [opencode.ai/docs/agents](https://opencode.ai/docs/agents).
|
||||
@@ -0,0 +1,58 @@
|
||||
# Slash Commands Reference
|
||||
|
||||
> Every slash command OpenCode ships in the TUI. Aliases are noted in parentheses.
|
||||
|
||||
## Session
|
||||
|
||||
| Command | Aliases | What it does |
|
||||
|---|---|---|
|
||||
| `/new` | `/clear` | Start a new session |
|
||||
| `/sessions` | `/resume`, `/continue` | List and switch between sessions |
|
||||
| `/compact` | `/summarize` | Compact the current session to free up context |
|
||||
| `/share` | — | Generate a public link (`opncd.ai/s/<id>`); also configurable via `share` in `opencode.json` (`manual` \| `auto` \| `disabled`) |
|
||||
| `/unshare` | — | Revoke the public link |
|
||||
| `/export` | — | Export the conversation to Markdown |
|
||||
|
||||
## Provider & model
|
||||
|
||||
| Command | What it does |
|
||||
|---|---|
|
||||
| `/connect` | Add a provider — interactive picker |
|
||||
| `/models` | Browse and switch models |
|
||||
|
||||
## Customization
|
||||
|
||||
| Command | What it does |
|
||||
|---|---|
|
||||
| `/themes` | Switch theme — interactive picker |
|
||||
| `/editor` | Open `$EDITOR` to compose a long prompt |
|
||||
| `/details` | Toggle visibility of tool execution details |
|
||||
| `/thinking` | Toggle visibility of thinking/reasoning blocks |
|
||||
|
||||
## Repo & docs
|
||||
|
||||
| Command | What it does |
|
||||
|---|---|
|
||||
| `/init` | Guided generation of `AGENTS.md` |
|
||||
| `/help` | Show the help dialog |
|
||||
|
||||
## Edits
|
||||
|
||||
| Command | What it does |
|
||||
|---|---|
|
||||
| `/undo` | Undo the last message |
|
||||
| `/redo` | Redo a previously undone message |
|
||||
|
||||
## Exit
|
||||
|
||||
| Command | Aliases | What it does |
|
||||
|---|---|---|
|
||||
| `/exit` | `/quit`, `/q` | Exit OpenCode |
|
||||
|
||||
---
|
||||
|
||||
## Custom slash commands
|
||||
|
||||
Any markdown file in `.opencode/commands/<name>.md` (or `~/.config/opencode/commands/`) creates a `/<name>` slash command. See [`../commands.md`](../commands.md) for the file format.
|
||||
|
||||
> 📚 Source: [opencode.ai/docs/tui](https://opencode.ai/docs/tui). Built-in command set may evolve — check the docs for the current set.
|
||||
Reference in New Issue
Block a user