Customization

OpenCode is highly configurable. This page covers themes, keybinds, commands, agents, formatters, and more.

Themes

Set your theme in tui.json:

{
  "$schema": "https://opencode.ai/tui.json",
  "theme": "tokyonight"
}

You can also create custom themes in ~/.config/opencode/themes/ or .opencode/themes/.

See Themes Documentation for available themes and customization options.

Keybinds

Customize keybinds in tui.json:

{
  "$schema": "https://opencode.ai/tui.json",
  "keybinds": {}
}

Key default keybinds:

Key	Action
Tab	Switch between Build and Plan modes
@	Fuzzy search for files to reference
/	Open command menu

See Keybinds Documentation for the full list and customization options.

Commands

Slash Commands

OpenCode has built-in slash commands (/init, /connect, /models, /share, /undo, /redo). You can also create custom ones.

Custom Commands

Define reusable commands in opencode.json:

{
  "command": {
    "test": {
      "template": "Run the full test suite with coverage report and show any failures.\nFocus on the failing tests and suggest fixes.",
      "description": "Run tests with coverage",
      "agent": "build",
      "model": "anthropic/claude-haiku-4-5"
    },
    "component": {
      "template": "Create a new React component named $ARGUMENTS with TypeScript support.\nInclude proper typing and basic structure.",
      "description": "Create a new component"
    }
  }
}

You can also define commands as markdown files in:

• ~/.config/opencode/commands/ — global commands
• .opencode/commands/ — project-specific commands

See Commands Documentation for details.

Formatters

Configure code formatters to run after OpenCode modifies files:

{
  "formatter": {
    "prettier": {
      "disabled": true
    },
    "custom-prettier": {
      "command": ["npx", "prettier", "--write", "$FILE"],
      "environment": {
        "NODE_ENV": "development"
      },
      "extensions": [".js", ".ts", ".jsx", ".tsx"]
    }
  }
}

See Formatters Documentation for details.

Agents

Built-in Agents

OpenCode ships with two primary agents:

Agent	Description
Build	Can read, write, and execute — the default mode
Plan	Can only read and suggest, no modifications

Custom Agents

Define specialized agents in opencode.json:

{
  "agent": {
    "code-reviewer": {
      "description": "Reviews code for best practices and potential issues",
      "model": "anthropic/claude-sonnet-4-5",
      "prompt": "You are a code reviewer. Focus on security, performance, and maintainability.",
      "tools": {
        "write": false,
        "edit": false
      }
    }
  }
}

Or create agent markdown files in:

• ~/.config/opencode/agents/ — global agents
• .opencode/agents/ — project-specific agents

Set the default agent:

{
  "default_agent": "build"
}

See Agents Documentation for details.

LSP Servers

OpenCode automatically loads LSP servers to provide code intelligence for the LLM. You can configure which servers are available.

See LSP Documentation for configuration options.

Plugins

Plugins extend OpenCode with custom tools, hooks, and integrations.

Load from npm:

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

Or place plugin files in:

• .opencode/plugins/ — project-specific plugins
• ~/.config/opencode/plugins/ — global plugins

See Plugins Documentation for details.

Skills

Skills are SKILL.md files that provide specialized knowledge the LLM can load on demand. Place them in:

• .opencode/skills/ — project-specific skills
• ~/.config/opencode/skills/ — global skills

See Skills Documentation for details.

.opencode Directory

The .opencode directory in your project root organizes project-specific customizations:

.opencode/
├── agents/          # Custom agent definitions
├── commands/        # Custom commands
├── modes/           # Custom modes
├── plugins/         # Local plugins
├── skills/          # Skill files
├── tools/           # Custom tool definitions
└── themes/          # Custom themes

The global equivalent is ~/.config/opencode/ with the same structure.

INFO

Both plural (agents/) and singular (agent/) directory names are supported for backwards compatibility.

Further Reading

• Themes
• Keybinds
• Commands
• Formatters
• Agents
• Plugins
• Skills
• Custom Tools