Skip to content

CowboyLogic/ai-dev / skills/client-config-opencode

client-config-opencode

Verified

Manage OpenCode configuration files (V2 native format by default, V1 supported) including MCP servers, providers, models, agents, commands, permissions, policies, skills, plugins, CLI/TUI settings, keybinds, and themes. Use this skill whenever the user wants to view, edit, add, migrate, or understand any opencode setting in opencode.json(c), cli.json, or tui.json. Trigger on: "configure opencode", "add provider", "set model", "add MCP server", "create agent", "configure permissions", "change theme", "add keybind", "show opencode config", "add custom command", "migrate opencode config to V2", or "opencode cli.json".

FileKindSize
CHANGELOG.mdmarkdown18.6 KB
README.mdmarkdown3.9 KB
SKILL.mdskill md8.8 KB
evals/evals.jsonconfig6.7 KB
references/agents.mdmarkdown5.4 KB
references/config-schema.mdmarkdown14.1 KB
references/mcp.mdmarkdown5.1 KB
references/permissions.mdmarkdown5.2 KB
references/providers.mdmarkdown10.8 KB
references/tui.mdmarkdown12.7 KB
references/v2/agents.mdmarkdown5.1 KB
references/v2/cli.mdmarkdown11.1 KB
references/v2/config-schema.mdmarkdown31.8 KB
references/v2/mcp.mdmarkdown10.3 KB
references/v2/migration.mdmarkdown8.9 KB
references/v2/permissions.mdmarkdown16.1 KB
references/v2/plugins.mdmarkdown8.6 KB
references/v2/providers.mdmarkdown21.4 KB
scripts/show-config.pyscript14.2 KB
scripts/update-references.pyscript3.9 KB
sources.jsonconfig7.1 KB

references/permissions.md

View on GitHub
# V1 Permissions Reference

> [!NOTE]
> This file covers the **V1** `permission` object. Native V2 uses an ordered `permissions` array with
> `{action, resource, effect}` rules and renamed actions (`bash` → `shell`, `task` → `subagent`). See
> [v2/permissions.md](v2/permissions.md).

## Structure

Permissions can be set globally (top-level) or per-agent. Agent permissions merge with the global config, and agent
rules take precedence. Since `v1.1.1` the legacy `tools` boolean map is deprecated and merged into `permission`
(still honored for backwards compatibility).

Shorthands:

```json
{ "permission": "allow" }
{ "permission": { "*": "ask", "bash": "allow", "edit": "deny" } }
```

```json
{
  "permission": {
    "bash": "ask",
    "edit": "allow",
    "read": "allow",
    "webfetch": "ask"
  },
  "agent": {
    "build": {
      "permission": {
        "bash": "allow",
        "edit": "allow"
      }
    },
    "plan": {
      "permission": {
        "bash": "ask",
        "edit": "ask"
      }
    }
  }
}
```

---

## Permission actions

| Action | Behavior |
|--------|----------|
| `"allow"` | Runs without prompting |
| `"ask"` | Prompts for confirmation each time |
| `"deny"` | Blocked entirely |

---

## Permission types

The V1 schema accepts additional keys as pattern rules, which suggests custom and MCP tool names (e.g.
`"mymcp_*"`) can be keyed directly; the V1 docs don't show this, so verify before relying on it. Wildcards: `*` = zero or more characters, `?` = exactly one; everything else is literal.
`~` or `$HOME` at the start of a pattern expands to the home directory.

### Rule-based (support glob patterns per-command)

| Key | Gates | Description |
|-----|-------|-------------|
| `read` | `read` | File reading |
| `edit` | `write`, `edit`, `apply_patch` | File editing/writing |
| `glob` | `glob` | File pattern matching |
| `grep` | `grep` | File content searching |
| `list` | `list` | Directory listing |
| `bash` | `bash` | Shell command execution |
| `task` | `task` | Which subagents this agent can launch (matches the subagent name) |
| `lsp` | `lsp` | LSP queries (currently non-granular) |
| `skill` | `skill` | Loading a skill (matches the skill name) |
| `external_directory` | any path-taking tool | Paths outside the working directory; default `ask` |

### Simple action (single value only)

| Key | Gates | Description |
|-----|-------|-------------|
| `todowrite` | `todowrite`, `todoread` | Task list writing/reading |
| `question` | `question` | Asking clarifying questions |
| `webfetch` | `webfetch` | Fetching URLs |
| `websearch` | `websearch` | Web search queries |
| `doom_loop` | — | Same tool call repeated 3 times with identical input; default `ask` |

> [!NOTE]
> `codesearch` is not in the current V1 schema — don't rely on it.

---

## Defaults

Most permissions default to `"allow"`; `doom_loop` and `external_directory` default to `"ask"`; `read` denies
`.env` files by default:

```json
{ "permission": { "read": { "*": "allow", "*.env": "deny", "*.env.*": "deny", "*.env.example": "allow" } } }
```

## Approvals and auto mode

When prompted: `once` approves this request; `always` approves requests matching the tool's suggested patterns for
the **rest of the current session**; `reject` denies. Start with `opencode --auto` (or `opencode run --auto`) to
auto-approve anything not explicitly denied; the TUI command palette can toggle auto-approve too.

## External directories

```json
{
  "permission": {
    "external_directory": { "~/projects/personal/**": "allow" },
    "edit": { "~/projects/personal/**": "deny" }
  }
}
```

Allowed external directories inherit workspace defaults (so `read` is allowed unless overridden).

---

## Glob patterns for bash

The `bash` permission supports an object with glob patterns as keys:

```json
{
  "permission": {
    "bash": {
      "*": "ask",
      "git status": "allow",
      "git diff *": "allow",
      "git add *": "allow",
      "git commit *": "allow",
      "git push *": "deny",
      "npm run *": "allow",
      "npm install *": "ask",
      "rm *": "ask",
      "rm -rf *": "deny"
    }
  }
}
```

Rules are evaluated in order and **the last matching rule wins** — put `"*"` first and more specific patterns after it, not the other way around (a trailing `"*"` would override everything above it).

---

## Common patterns

### Permissive (trust all)

```json
{
  "permission": {
    "bash": "allow",
    "edit": "allow",
    "read": "allow",
    "webfetch": "allow"
  }
}
```

### Cautious (ask for writes)

```json
{
  "permission": {
    "read": "allow",
    "glob": "allow",
    "grep": "allow",
    "list": "allow",
    "edit": "ask",
    "bash": "ask",
    "webfetch": "ask"
  }
}
```

### Read-only agent

```json
{
  "agent": {
    "my-analyzer": {
      "permission": {
        "read": "allow",
        "glob": "allow",
        "grep": "allow",
        "list": "allow",
        "edit": "deny",
        "bash": "deny",
        "webfetch": "deny"
      }
    }
  }
}
```

### Safe git workflow

```json
{
  "permission": {
    "bash": {
      "*": "ask",
      "git status": "allow",
      "git log *": "allow",
      "git diff *": "allow",
      "git add *": "allow",
      "git commit *": "allow",
      "git push *": "deny"
    }
  }
}
```
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 469kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 321kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 321kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 321kUpdated Claude CodeCodexVerifiedInstall