Settings

CLI settings control the terminal clients only. They are separate from the server and project settings in opencode.json(c).

Press Ctrl+P, then select Open settings to change common settings from the TUI.

Configuration file

OpenCode stores CLI settings in one global file:

~/.config/opencode/cli.json

When $XDG_CONFIG_HOME is set, OpenCode uses:

$XDG_CONFIG_HOME/opencode/cli.json

There is no project-local CLI settings file. Add the published JSON Schema for validation and autocomplete:

{
  "$schema": "https://opencode.ai/v2/cli.json"
}

OpenCode adds $schema when it creates or migrates this file. Unknown settings are rejected, and valid edits reload while the TUI is running.

Inline config

Set OPENCODE_CLI_CONFIG_CONTENT to apply CLI settings from inline JSON:

OPENCODE_CLI_CONFIG_CONTENT='{"tabs":{"mode":"off"}}' opencode

OpenCode merges the inline settings over the global cli.json. Nested objects are merged, while arrays and scalar values from the environment replace global values. Inline settings remain authoritative while the variable is set.

Appearance

Choose a theme, control interface motion, and override the terminal cursor:

{
  "theme": {
    "name": "tokyonight",
    "mode": "system"
  },
  "animations": true,
  "cursor": {
    "style": "block",
    "blinking": true
  }
}

See Theme for selecting and creating themes.

Input

Configure mouse capture, scrolling, editor context, pastes, and prompt image previews:

{
  "mouse": true,
  "scroll": {
    "speed": 3,
    "acceleration": false
  },
  "prompt": {
    "editor": true,
    "paste": "compact",
    "image_preview": false
  }
}

Sessions

Configure how full-screen TUI sessions are presented and where new sessions start:

{
  "session": {
    "sidebar": "auto",
    "scrollbar": false,
    "thinking": "hide",
    "grouping": "auto",
    "image_preview": false,
    "tps": true,
    "markdown": "rendered",
    "new_location": "launch",
    "permissions": "prompt"
  }
}

Tabs

Configure the persistent session tab strip:

{
  "tabs": {
    "mode": "auto",
    "scope": "cwd",
    "layout": "horizontal",
    "indicators": "status"
  }
}

The legacy boolean tabs.enabled setting remains supported: true is on and false is off. OpenCode reads it without rewriting the config file.

Number indicators retain status colors and background animations. Ctrl+number shortcuts switch tabs in either indicator mode.

Diffs

Configure the initial diff scope and presentation:

{
  "diffs": {
    "source": "branch",
    "wrap": "word",
    "tree": true,
    "single": false,
    "view": "auto"
  }
}

branch shows All branch and local changes, committed shows branch commits only, and working shows staged, unstaged, and untracked changes. turn shows Last turn, the files the session changed in its latest turn; it refreshes when the session finishes a turn and falls back to branch when /diff is not opened from a session.

In /diff, press d to change the scope or choose a comparison branch from Base. These in-view choices last until the TUI exits and do not change cli.json.

Alerts

Enable system notifications and attention sounds independently:

{
  "attention": {
    "notifications": true,
    "sound": true,
    "volume": 0.4,
    "sound_pack": "opencode.default",
    "sounds": {
      "permission": "/home/me/sounds/permission.wav"
    }
  }
}

An invalid or unreadable override falls back to the built-in sound for that event.

Terminal

Configure terminal integration:

{
  "terminal": {
    "title": true,
    "copy": "select"
  }
}

Mini

The mini group controls opencode mini, the minimal interactive interface:

{
  "mini": {
    "thinking": "show",
    "tools": "hide",
    "shell_output": "hide",
    "turn_summary": "show",
    "footer": "show",
    "splash": "show",
    "work_spinner": "block-soft-slide",
    "mono": false,
    "replay": true,
    "replay_limit": 200
  }
}

Available spinner IDs are:

block-soft-slide  block-soft-sweep  block-low-comet  block-low-duet
block-shuttle     block-bridge      block-squeeze    small-toggle
square-toggle     grow-shrink       quadrant-orbit   crosshatch
density-wave      seed

Command-line mini replay flags override these settings for that invocation.

Keybinds

Override a command binding and the leader-key timeout:

{
  "keybinds": {
    "leader": "ctrl+x",
    "app.exit": ["ctrl+c", "ctrl+d", "<leader>q"],
    "prompt.paste": {
      "key": "ctrl+v",
      "event": "press",
      "preventDefault": false,
      "fallthrough": false
    },
    "help.show": false
  },
  "leader": {
    "timeout": 2000
  }
}

A binding value can be a string, an array of alternatives, or an object. Use "none" or false to disable a binding. See Keybinds for accepted key syntax, every command ID, and every default binding.

Plugins

Load terminal-only plugins in order:

{
  "plugins": [
    "-opencode.notifications",
    {
      "package": "./plugins/status",
      "options": {
        "compact": true
      }
    }
  ]
}

See Plugins for package forms, local discovery, wildcards, and disable directives.

Debug and experimental

Enable diagnostics or opt in to a currently available experiment:

{
  "debug": {
    "devtools": false,
    "timing": false,
    "turn_tokens": "verbose"
  },
  "experimental": {}
}

Only use feature IDs currently listed by the TUI’s Experiments dialog. Unknown IDs have no effect.