pantheon-ai/opencode-toolkit

Complete toolkit for configuring and extending OpenCode: agent creation, custom slash commands, configuration management, plugin development, and SDK usage.

Quality

98%

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Advisory

Suggest reviewing before use

OpenCode Agent Configuration Reference

Name: pantheon-ai/opencode-toolkit
Rating: 0.98 (1 reviews)
Author: pantheon-ai

file_locations

Agent definitions are markdown files in:

.opencode/agents/<name>.md (project)
~/.config/opencode/agents/<name>.md (global)

frontmatter_schema

---
# Core Configuration
model: "provider/model-id"           # Model override
temperature: 0.7                     # Sampling temperature
top_p: 0.9                           # Nucleus sampling
prompt: "Custom system prompt"       # Or use markdown body
description: "Agent description"     # Shown in listings, triggers agent
mode: "subagent" | "primary" | "all" # Agent availability
color: "#FF5733"                     # UI color
maxSteps: 25                         # Max tool call steps
disable: false                       # Disable agent

# Tool Access Control
tools:
  edit: true
  write: true
  bash: true
  read: true
  glob: true
  grep: true
  webfetch: true
  task: true
  skill: true

# Permissions
permission:
  edit: "ask" | "allow" | "deny"
  bash:
    "*": "allow"
    "git *": "deny"
  skill:
    "*": "allow"
    "my-skill": "deny"
  webfetch: "ask" | "allow" | "deny"
  doom_loop: "ask" | "allow" | "deny"
  external_directory: "ask" | "allow" | "deny"
---

agent_modes

Mode	Description
`primary`	User-selectable, can be default, spawns subagents
`subagent`	Only callable via `task` tool by other agents
`all`	Both primary and subagent (default)

permissions

Permission Values

Value	Behavior
`"allow"`	Automatically permit
`"ask"`	Prompt user for approval
`"deny"`	Automatically reject

Permission Categories

`edit`

Controls edit and write tools.

`bash`

Controls command execution. Supports wildcard patterns:

bash:
  "*": "ask"              # Ask for everything by default
  "git *": "allow"        # Allow all git commands
  "npm *": "allow"        # Allow npm commands
  "rm *": "deny"          # Block deletion

`skill`

Controls skill access:

skill:
  "*": "deny"             # Deny all by default
  "my-skill": "allow"     # Allow specific skill

`webfetch`

Controls web fetching. "ask" prompts for each URL.

`doom_loop`

Controls doom loop detection (agent stuck in repetitive patterns).

`external_directory`

Controls access to files outside working directory. Affects:

bash commands referencing external paths
read/edit/write for external files

Default Permissions

If not specified, agents inherit from global config:

permission:
  edit: "allow"
  bash: { "*": "allow" }
  skill: { "*": "allow" }
  webfetch: "allow"
  doom_loop: "ask"
  external_directory: "ask"

available_tools

File Operations

Tool	Purpose	Key Parameters
`read`	Read file contents	`filePath`, `offset`, `limit`
`edit`	String replacement in files	`filePath`, `oldString`, `newString`, `replaceAll`
`write`	Create/overwrite files	`filePath`, `content`

Search & Navigation

Tool	Purpose	Key Parameters
`glob`	Find files by pattern	`pattern`, `path`
`grep`	Search file contents (regex)	`pattern`, `path`, `include`
`list`	List directory contents	`path`

Command Execution

Tool	Purpose	Key Parameters
`bash`	Execute shell commands	`command`, `timeout`, `workdir`, `description`

Default timeout: 120000ms. Permissions: bash, external_directory.

Web & External

Tool	Purpose	Key Parameters
`webfetch`	Fetch web content	`url`, `format` (text/markdown/html), `timeout`
`websearch`	Web search via Exa AI	`query`, `numResults`
`codesearch`	Code/SDK documentation search	`query`, `tokensNum`

Task Management

Tool	Purpose	Key Parameters
`task`	Launch subagents	`description`, `prompt`, `subagent_type`, `session_id`
`todowrite`	Update todo list	`todos` array
`todoread`	Read todo list	(none)

Other Tools

Tool	Purpose	Notes
`skill`	Load skill instructions	Parameter: `name`
`batch`	Parallel tool execution	Experimental: `config.experimental.batch_tool`
`lsp`	Language Server Protocol	Experimental: `OPENCODE_EXPERIMENTAL_LSP_TOOL`

tool_access_control

Disable specific tools for an agent:

tools:
  bash: false      # No shell access
  webfetch: false  # No web access
  task: false      # Cannot spawn subagents

All tools inherit from global config.tools by default.

examples

Restricted Code Review Agent (Primary)

---
description: Safe code reviewer.
mode: primary
permission:
  edit: "ask"
  bash: "deny"
  external_directory: "deny"
---
You are a code review specialist...

Research Agent (Subagent)

---
description: |-
  Web research agent. Use when user says "research topic", "find info".
  
  Examples:
  - user: "research" -> search web
mode: subagent
permission:
  skill:
    "*": "deny"
    "web-research": "allow"
---
You are a research specialist...

Deployment Agent (Standard/Undefined)

---
description: Deployment helper.
permission:
  skill:
    "*": "deny"
    "deploy-checklist": "allow"
---
You are a deployment specialist...