mirror of
https://github.com/wesammustafa/opencode-primer.git
synced 2026-11-19 02:17:58 +00:00
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)
180 lines
4.8 KiB
Markdown
180 lines
4.8 KiB
Markdown
# 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).
|