{
  "$schema": "https://opencode.ai/config.json",
  "provider": { },       // LLM provider configurations
  "agent": { },          // Custom agent definitions
  "mcp": { },            // MCP server connections
  "permission": { },     // Tool allow/deny/ask rules
  "instructions": [ ],   // Additional instruction file paths
  "snapshot": true,       // Enable file change tracking for undo/redo
  "share": {              // Session sharing configuration
    "provider": "opencode"
  }
}

{
  "provider": {
    "<provider-name>": {
      "id": "provider-id",
      "api": {
        "apiKey": "{env:PROVIDER_API_KEY}",
        "baseURL": "https://api.provider.com/v1"
      },
      "models": {
        "<model-alias>": {
          "id": "model-id",
          "name": "Display Name",
          "attachment": true,       // Supports file attachments
          "reasoning": true,        // Extended thinking capable
          "temperature": 0,
          "context_length": 200000
        }
      }
    }
  }
}

{
  "permission": {
    "allow": [
      "bash(git *)",
      "bash(make *)",
      "read(**/*.adoc)",
      "edit(**/*.adoc)"
    ],
    "deny": [
      "bash(rm -rf *)",
      "read(.env*)",
      "read(~/.secrets/*)"
    ],
    "ask": [
      "bash(docker *)"
    ]
  }
}

{
  "instructions": [
    ".opencode/context/*.md",
    "~/.config/opencode/global-rules.md"
  ]
}

{
  "snapshot": true
}

{
  "$schema": "https://opencode.ai/tui.json",
  "theme": "catppuccin",
  "keybinds": { },
  "scroll": {
    "speed": 3,
    "page_fraction": 0.8
  },
  "diff": {
    "style": "unified"
  }
}

{
  "theme": "catppuccin"
}

{
  "scroll": {
    "speed": 3,
    "page_fraction": 0.8
  }
}

{
  "diff": {
    "style": "unified"
  }
}

// tui.json
{
  "theme": "catppuccin"
}

// ~/.config/opencode/themes/catppuccin-domus.json
{
  "name": "catppuccin-domus",
  "colors": {
    "primary": "#cba6f7",         // Mauve
    "secondary": "#a6e3a1",       // Green
    "accent": "#f5c2e7",          // Pink
    "error": "#f38ba8",           // Red
    "warning": "#fab387",         // Peach
    "success": "#a6e3a1",         // Green
    "text": "#cdd6f4",            // Text
    "background": "#1e1e2e",      // Base
    "border": "#585b70",          // Surface2
    "muted": "#6c7086",           // Overlay0
    "diff": {
      "added": "#a6e3a1",
      "removed": "#f38ba8",
      "changed": "#f9e2af"
    },
    "markdown": {
      "heading": "#cba6f7",
      "code": "#a6e3a1",
      "link": "#89b4fa",
      "bold": "#f5c2e7",
      "italic": "#f5c2e7"
    },
    "syntax": {
      "keyword": "#cba6f7",
      "string": "#a6e3a1",
      "number": "#fab387",
      "comment": "#6c7086",
      "function": "#89b4fa",
      "type": "#f9e2af",
      "variable": "#cdd6f4",
      "operator": "#89dceb"
    }
  }
}

{
  "colors": {
    "dark": {
      "background": "#1e1e2e",
      "text": "#cdd6f4"
    },
    "light": {
      "background": "#eff1f5",
      "text": "#4c4f69"
    }
  }
}

ctrl+x → n    # New session
ctrl+x → s    # Share session
ctrl+x → q    # Quit

// tui.json
{
  "keybinds": {
    "leader": "ctrl+x",
    "chat": {
      "submit": "ctrl+enter",
      "new_session": "ctrl+x n",
      "share": "ctrl+x s",
      "model_picker": "ctrl+x m",
      "agent_picker": "ctrl+x a",
      "toggle_mode": "tab"
    },
    "global": {
      "quit": "ctrl+x q",
      "help": "ctrl+x ?",
      "history": "ctrl+x h"
    }
  }
}

{
  "keybinds": {
    "chat": {
      "share": "none"
    }
  }
}

---
description: Read-only mode for AsciiDoc documentation review
tools:
  allow:
    - read
    - grep
    - glob
    - list
    - skill
  deny:
    - write
    - edit
    - bash
    - apply_patch
---

# Review Mode

You are in review mode. You can read, search, and analyze files but cannot modify anything.

Focus on:
- Convention violations
- Missing attributes
- Broken cross-references
- Structural issues

Report findings as a numbered list with file:line references.

// .opencode/plugins/asciidoc-validator.ts
export const AsciidocValidator = async ({ project, client, $, directory, worktree }) => {
  // Context parameters:
  // project  -- current project information
  // client   -- OpenCode SDK client (for logging, etc.)
  // $        -- Bun's shell API for running commands
  // directory -- working directory
  // worktree -- git worktree path

  return {
    // Hook: After file is edited
    "tool.execute.after": async (event) => {
      if (event.input.tool === "edit" &&
          event.output.args.filePath?.endsWith(".adoc")) {
        // Validate attributes against antora.yml
        client.app.log("info", "Validating AsciiDoc attributes...")
      }
    },

    // Hook: Before tool execution
    "tool.execute.before": async (event) => {
      if (event.input.tool === "bash" &&
          event.output.args.command?.includes("rm -rf")) {
        client.app.log("warn", "Blocked destructive operation")
        // Return deny to block
      }
    },
  }
};

{
  "plugin": [
    "opencode-helicone-session",
    "opencode-wakatime",
    "@my-org/custom-plugin"
  ]
}

// .opencode/package.json
{
  "dependencies": {
    "shescape": "^2.1.0"
  }
}

client.app.log("debug", "Detailed info")
client.app.log("info", "General info")
client.app.log("warn", "Warning message")
client.app.log("error", "Error occurred")

=== Event Hooks (30+ Events)

Organized by category from the actual OpenCode plugin API:

==== Command Events

[cols="1,2"]
|===
| Event | When

| `command.executed`
| A slash command was executed
|===

==== File Events

[cols="1,2"]
|===
| Event | When

| `file.edited`
| A file was modified (edit, write, patch)

| `file.watcher.updated`
| File watcher detected external change
|===

==== Session Events

[cols="1,2"]
|===
| Event | When

| `session.created`
| New session started

| `session.updated`
| Session state changed

| `session.compacted`
| Context was compacted (summarized)

| `session.deleted`
| Session was deleted

| `session.diff`
| File diff generated

| `session.error`
| Session error occurred

| `session.idle`
| Session became idle

| `session.status`
| Session status changed
|===

==== Message Events

[cols="1,2"]
|===
| Event | When

| `message.updated`
| Message content changed

| `message.removed`
| Message was deleted

| `message.part.updated`
| Part of a message changed

| `message.part.removed`
| Part of a message removed
|===

==== Tool Events

[cols="1,2"]
|===
| Event | When

| `tool.execute.before`
| Before tool execution (can intercept)

| `tool.execute.after`
| After tool execution
|===

==== Permission Events

[cols="1,2"]
|===
| Event | When

| `permission.asked`
| User was prompted for permission

| `permission.replied`
| User responded to permission prompt
|===

==== Other Events

[cols="1,2"]
|===
| Event | When

| `server.connected`
| Client connected to server

| `todo.updated`
| Todo list changed

| `shell.env`
| Shell environment variable set

| `lsp.client.diagnostics`
| LSP diagnostics received

| `lsp.updated`
| LSP state changed

| `installation.updated`
| OpenCode installation updated

| `tui.prompt.append`
| Text appended to TUI input

| `tui.command.execute`
| TUI command executed

| `tui.toast.show`
| Toast notification displayed
|===

==== Experimental Hooks

[cols="1,2"]
|===
| Hook | Purpose

| `experimental.session.compacting`
| Customize what context is preserved during auto-compaction
|===

=== Plugin vs Claude Code Hooks Comparison

[cols="1,2,2"]
|===
| Aspect | Claude Code Hooks | OpenCode Plugins

| Language
| Bash scripts only
| JavaScript/TypeScript

| Event model
| 5 lifecycle events
| 9+ event types with richer payloads

| Blocking
| Exit code 2 blocks action
| Return `deny: true` with reason

| Custom tools
| Not possible
| Plugins can define new tools

| State
| Stateless between invocations
| Persistent module state

| Dependencies
| System packages
| npm ecosystem (auto-installed via Bun)

| Debugging
| Shell output parsing
| Full JS debugging, stack traces

| Distribution
| Copy files
| npm packages or git-managed files
|===

=== Planned Plugins

[cols="1,2,1"]
|===
| Plugin | Purpose | Priority

| `asciidoc-validator`
| Validate {attributes} against antora.yml after every .adoc edit
| P1

| `auto-backup`
| Snapshot files before edit/write (mirrors Claude Code PreToolUse hook)
| P1

| `security-guard`
| Block sensitive file access, warn on credential staging
| P1

| `shellcheck-runner`
| Run ShellCheck on .sh/.bash/.zsh after edits
| P2

| `session-logger`
| Log all tool calls and model switches for cost tracking
| P2

| `cost-tracker`
| Estimate token usage and cost per provider per session
| P2
|===

=== Plugin Development Workflow

[source,bash]