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.
| Option | Purpose |
|---|---|
enabled | Start with Vim mode enabled |
vim_initial_mode | Start in insert (default) or normal mode |
toggle_key | Keybind for Toggle vim mode |
indicator | Show the prompt Vim indicator |
vim_enter_submit | Submit with Enter from insert mode |
vim_insert_after_submit | Return to insert mode after submit |
vim_system_clipboard_register | Use the system clipboard as Vim register |
vim_langmap | Map non-English keys or simple aliases |
vim_normal_leader | Removed in v2. Configure the host leader keybind instead |
normal_keybinds | Extra keybinds active only in Vim normal mode |
keybinds["vim.normal"] | Nested normal-mode keybind configuration |
vim_escape_sequence | Use 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/pbpasteon macOS, PowerShell clipboard commands on Windows, andwl-copy/wl-paste,xclip, orxselon 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"
}