OpenCode: Config, TUI, Themes, Keybindings, Modes & Plugins

{
  "$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")

# Create plugin directory
mkdir -p .opencode/plugins

# Write plugin
nvim .opencode/plugins/my-plugin.ts

# OpenCode auto-discovers and loads on next session start
# No registration needed -- file existence is sufficient