Plugin: Configuration

Configuration

Configure the plugin in cli.json, OpenCode v2's TUI configuration file:

{
  "plugins": [
    {
      "package": "@leohenon/opencode-vim-plugin",
      "options": {
        "enabled": true,
        "toggle_key": "ctrl+shift+v",
        "indicator": true,
        "vim_enter_submit": false,
        "vim_insert_after_submit": false,
        "vim_system_clipboard_register": false
      }
    }
  ]
}

Unless marked as top-level cli.json settings, the examples below go inside the plugin's options object.

Options

For options beginning with vim_, the prefix may be omitted in plugin configuration.

OptionPurpose
enabledStart with Vim mode enabled
vim_initial_modeStart in insert (default) or normal mode
toggle_keyKeybind for Toggle vim mode
indicatorShow the prompt Vim indicator
vim_enter_submitSubmit with Enter from insert mode
vim_insert_after_submitReturn to insert mode after submit
vim_system_clipboard_registerUse the system clipboard as Vim register
vim_langmapMap non-English keys or simple aliases
vim_normal_leaderRemoved in v2. Configure the host leader keybind instead
normal_keybindsExtra keybinds active only in Vim normal mode
keybinds["vim.normal"]Nested normal-mode keybind configuration
vim_escape_sequenceUse a two-key escape sequence like jk

Note

Unsupported OCV options: vim_line_motions

Initial mode

Vim mode starts in insert mode by default. To start in normal mode instead, use:

{
  "vim_initial_mode": "normal"
}

Mode-scoped keybinds

Bind existing OpenCode commands only in Vim normal mode:

{
  "normal_keybinds": {
    "<leader>s": "session.list",
    "j": "session.line.down",
    "k": "session.line.up"
  }
}

<leader> in a keybind is resolved by OpenCode itself, so configure it in the top-level keybinds object in cli.json:

{
  "keybinds": {
    "leader": "space"
  }
}

normal_keybinds values can be command strings or objects:

{
  "normal_keybinds": {
    "j": {
      "command": "session.line.down"
    }
  }
}

Nested normal-mode keybind configuration is also accepted inside the plugin options:

{
  "keybinds": {
    "vim.normal": {
      "session_list": "<leader>s",
      "messages_line_up": "<leader>k",
      "messages_line_down": "<leader>j"
    }
  }
}

Submit behavior

By default, insert mode uses Enter for newlines and normal mode uses Enter to submit.

To submit from insert mode too:

{
  "vim_enter_submit": true
}

To always default to insert mode after a prompt submission:

{
  "vim_insert_after_submit": true
}

To keep newline available when vim_enter_submit is enabled, configure OpenCode's top-level input_newline keybind:

{
  "keybinds": {
    "input_newline": "alt+return"
  }
}

Or configure a separate OpenCode submit key in top-level cli.json settings:

{
  "keybinds": {
    "prompt_submit": "alt+return"
  }
}

input_newline and prompt_submit are OpenCode keybinds, not plugin options.

System clipboard register

Use the system clipboard as Vim's register:

{
  "vim_system_clipboard_register": true
}

Yank and delete operations sync to the system clipboard, p / P paste from it.

Note

Clipboard sync uses pbcopy / pbpaste on macOS, PowerShell clipboard commands on Windows, and wl-copy / wl-paste, xclip, or xsel on Linux.

Vim langmap

Map non-English keyboard layout characters to Vim command keys.

Keys and values should be single characters.

{
  "vim_langmap": {
    "р": "h",
    "о": "j",
    "л": "k",
    "д": "l"
  }
}

Or for simple aliases:

{
  "vim_langmap": {
    "H": "^",
    "L": "$"
  }
}

Vim escape sequence

Set a two-character sequence to leave insert mode without pressing Escape:

{
  "vim_escape_sequence": "jk"
}