KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#dsh #dsh-plugin #developer-tools #ai-agent #claude-code #codex #typescript #ai-agents #deepseek-harness #mcp #cli #rust

opencode.nvim

★ 923 Open GitHub ↗

neovim frontend for opencode - a terminal-based AI coding agent

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# 🤖 opencode.nvim

> neovim frontend for opencode - a terminal-based AI coding agent

![Neovim](https://img.shields.io/badge/NeoVim-%2357A143.svg?&style=for-the-badge&logo=neovim&logoColor=white)
[![GitHub stars](https://img.shields.io/github/stars/sudo-tee/opencode.nvim?style=for-the-badge)](https://github.com/sudo-tee/opencode.nvim/stargazers)
![Last Commit](https://img.shields.io/github/last-commit/sudo-tee/opencode.nvim?style=for-the-badge)

</div>

## ✨ Description

This plugin provides a bridge between neovim and the [opencode](https://github.com/sst/opencode) AI agent, creating a chat interface while capturing editor context (current file, selections) to enhance your prompts. It maintains persistent sessions tied to your workspace, allowing for continuous conversations with the AI assistant similar to what tools like Cursor AI offer.

## Main Features

### Chat Panel

The chat panel is a dedicated window inside Neovim that lets you hold a persistent conversation with the opencode AI agent. It displays your previous messages and responses, and automatically uses your current workspace and editor state as context so you can iterate on code without leaving Neovim. You can type prompts, review answers, and navigate back to your code buffer while keeping the ongoing chat session open.

### Quick buffer chat (<leader>o/) EXPERIMENTAL

This is an experimental feature that allows you to chat with the AI using the current buffer context. In visual mode, it captures the selected text as context, while in normal mode, it uses the current line. The AI will respond with quick edits to the files that are applied by the plugin.

Don't hesitate to give it a try and provide feedback!

Refer to the [Quick Chat](#-quick-chat) section for more details.

## 📑 Table of Contents

- [⚠️Caution](#caution)
- [Requirements](#-requirements)
- [Installation](#-installation)
- [Configuration](#️-configuration)
- [Usage](#-usage)
- [Permissions](#-permissions)
- [Context](#-context)
- [Agents](#-agents)
- [Custom/External Server Configuration](#-customexternal-server-configuration)
- [User Commands and Slash Commands](#user-commands-and-slash-commands)
- [Contextual Actions for Snapshots](#-contextual-actions-for-snapshots)
- [Contextual Restore points](#-contextual-restore-points)
- [Highlight Groups](#highlight-groups)
- [Prompt Guard](#️-prompt-guard)
- [Custom user hooks](#-custom-user-hooks)
- [Server-Sent Events (SSE) autocmds](#-server-sent-events-sse-autocmds)
- [Quick Chat](#quick-chat)
- [Setting up Opencode](#-setting-up-opencode)
- [Recipes](./docs/recipes)

## ⚠️Caution

This plugin is in early development and may have bugs and breaking changes. It is not recommended for production use yet. Please report any issues you encounter on the [GitHub repository](https://github.com/sudo-tee/opencode.nvim/issues).

[Opencode](https://github.com/sst/opencode) is also in early development and may have breaking changes. Ensure you are using a compatible version of the Opencode CLI (v0.6.3+ or more).

If your upgrade breaks the plugin, please open an issue or downgrade to the last working version.

## 📋 Requirements

- Opencode (v0.6.3+ or more) CLI installed and available (see [Setting up opencode](#-setting-up-opencode) below)

## 🚀 Installation

Install the plugin with your favorite package manager. See the [Configuration](#️-configuration) section below for customization options.

### With lazy.nvim

```lua
{
  "sudo-tee/opencode.nvim",
  config = function()
    require("opencode").setup({})
  end,
  dependencies = {
    {
      "MeanderingProgrammer/render-markdown.nvim",
      opts = {
        anti_conceal = { enabled = false },
        file_types = { 'markdown', 'opencode_output' },
      },
      ft = { 'markdown', 'Avante', 'copilot-chat', 'opencode_output' },
    },
    -- Optional, for file mentions and commands completion, pick only one
    'saghen/blink.cmp',
    -- 'hrsh7th/nvim-cmp',

-- Optional, for file mentions picker, pick only one
    'folke/snacks.nvim',
    -- 'nvim-telescope/telescope.nvim',
    -- 'ibhagwan/fzf-lua',
    -- 'nvim_mini/mini.nvim',
  },
}
```

## ⚙️ Configuration

```lua
-- Default configuration with all available options
require('opencode').setup({
  preferred_picker = nil, -- 'telescope'/'telescope.nvim', 'fzf'/'fzf-lua', 'mini.pick', 'snacks'/'snacks.nvim', 'select', if nil, it will use the best available picker. Note mini.pick does not support multiple selections
  preferred_completion = nil, -- 'blink', 'nvim-cmp','vim_complete' if nil, it will use the best available completion
  default_global_keymaps = true, -- If false, disables all default global keymaps
  default_mode = 'build', -- 'build' or 'plan' or any custom configured. @see [OpenCode Agents](https://opencode.ai/docs/modes/)
  default_system_prompt = nil, -- Custom system prompt to use for all sessions. If nil, uses the default built-in system prompt
  keymap_prefix = '<leader>o', -- Default keymap prefix for global keymaps change to your preferred prefix and it will be applied to all keymaps starting with <leader>o
  opencode_executable = 'opencode', -- Name of your opencode binary
  snapshot_path = nil, -- Override base path for the snapshot git directory (default: $XDG_DATA_HOME/opencode). Appends /snapshot/<project_id>/<worktree_hash>

-- Server configuration for custom/external opencode servers
  server = {
    url = nil,             -- URL/hostname (e.g., 'http://192.168.1.100', 'localhost', 'https://myserver.com')
    port = nil,            -- Port number (e.g., 8080), 'auto' for random port
    timeout = 5,           -- Health check timeout in seconds when connecting
    spawn_command = nil,   -- Optional function to start the server: function(port, url) ... end
    auto_kill = true,      -- Kill spawned servers when last nvim instance exits (default: true) Only applies to servers spawned by the plugin with spawn_command/kill_command
    path_map = nil,        -- Map host paths to server paths: string ('/app') or function(path) -> string
    username = nil,        -- Username for Basic auth. Falls back to OPENCODE_SERVER_USERNAME env var, then "opencode"
    password = nil,        -- Password for Basic auth. Falls back to OPENCODE_SERVER_PASSWORD env var
  },

keymap = {
    editor = {
      ['<leader>og'] = { 'toggle' }, -- Open opencode. Close if opened
      ['<leader>oi'] = { 'open_input' }, -- Opens and focuses on input window on insert mode
      ['<leader>oI'] = { 'open_input_new_session' }, -- Opens and focuses on input window on insert mode. Creates a new session
      ['<leader>oo'] = { 'open_output' }, -- Opens and focuses on output window
      ['<leader>ot'] = { 'toggle_focus' }, -- Toggle focus between opencode and last window
      ['<leader>oT'] = { 'timeline' }, -- Display timeline picker to navigate/undo/redo/fork messages
      ['<leader>oq'] = { 'close' }, -- Close UI windows
      ['<leader>os'] = { 'select_session' }, -- Select and load a opencode session
      ['<leader>oR'] = { 'rename_session' }, -- Rename current session
      ['<leader>op'] = { 'configure_provider' }, -- Quick provider and model switch from predefined list
      ['<leader>oV'] = { 'configure_variant' }, -- Switch model variant for the current model
      ['<leader>oy'] = { 'add_visual_selection', mode = {'v'} },
      ['<leader>oY'] = { 'add_visual_selection_inline', mode = {'v'} }, -- Insert visual selection as inline code block in the input buffer
      ['<leader>oz'] = { 'toggle_zoom' }, -- Zoom in/out on the Opencode windows
      ['<leader>ov'] = { 'paste_image'}, -- Paste image from clipboard into current session
      ['<leader>od'] = { 'diff_open' }, -- Opens a diff tab of a modified file since the last opencode prompt
      ['<leader>o]'] = { 'diff_next' }, -- Navigate to next file diff
      ['<leader>o['] = { 'diff_prev' }, -- Navigate to previous file diff
      ['<leader>oc'] = { 'diff_close' }, -- Close diff view tab and return to normal editing
      ['<leader>ora'] = { 'diff_revert_all_last_prompt' }, -- Revert all file changes since the last opencode prompt
      ['<leader>ort'] = { 'diff_revert_this_last_prompt' }, -- Revert current file changes since the last opencode prompt
      ['<leader>orA'] = { 'diff_revert_all' }, -- Revert all file changes since the last opencode session
      ['<leader>orT'] = { 'diff_revert_this' }, -- Revert current file changes since the last opencode session
      ['<leader>orr'] = { 'diff_restore_snapshot_file' }, -- Restore a file to a restore point
      ['<leader>orR'] = { 'diff_restore_snapshot_all' }, -- Restore all files to a restore point
      ['<leader>ox'] = { 'swap_position' }, -- Swap Opencode pane left/right
      ['<leader>ott'] = { 'toggle_tool_output' }, -- Toggle tools output (diffs, cmd output, etc.)
      ['<leader>otr'] = { 'toggle_reasoning_output' }, -- Toggle reasoning output (thinking steps)
      ['<leader>o/'] = { 'quick_chat', mode = { 'n', 'x' } }, -- Open quick chat input with selection context in visual mode or current line context in normal mode
    },
    input_window = {
      ['<S-cr>'] = { 'submit_input_prompt', mode = { 'n', 'i' } }, -- Submit prompt (normal mode and insert mode)
      ['<esc>'] = { 'close', defer_to_completion = true }, -- Close UI windows
      ['<C-c>'] = { 'cancel', defer_to_completion = true }, -- Cancel opencode request while it is running
      ['~'] = { 'mention_file', mode = 'i' }, -- Pick a file and add to context. See File Mentions section
      ['@'] = { 'mention', mode = 'i' }, -- Insert mention (file/agent)
      ['/'] = { 'slash_commands', mode = 'i' }, -- Pick a command to run in the input window
      ['#'] = { 'context_items', mode = 'i' }, -- Manage context items (current file, selection, diagnostics, mentioned files)
      ['<M-v>'] = { 'paste_image', mode = 'i' }, -- Paste image from clipboard as attachment
      ['<tab>'] = { 'toggle_pane', mode = { 'n', 'i' }, defer_to_completion = true }, -- Toggle between input and output panes
      ['<up>'] = { 'prev_prompt_history', mode = { 'n', 'i' }, defer_to_completion = true }, -- Navigate to previous prompt in history
      ['<down>'] = { 'next_prompt_history', mode = { 'n', 'i' }, defer_to_completion = true }, -- Navigate to next prompt in history
      ['<M-m>'] = { 'switch_mode' }, -- Switch between modes (build/plan)
      ['<M-r>'] = { 'cycle_variant', mode = { 'n', 'i' } }, -- Cycle through available model variants
    },
    output_window = {
      ['<esc>'] = { 'close' }, -- Close UI windows
      ['<C-c>'] = { 'cancel' }, -- Cancel opencode request while it is running
      [']]'] = { 'next_message' }, -- Navigate to next message in the conversation
      ['[['] = { 'prev_message' }, -- Navigate to previous message in the conversation
      ['<tab>'] = { 'toggle_pane', mode = { 'n', 'i' } }, -- Toggle between input and output panes
      ['i'] = { 'focus_input', 'n' }, -- Focus on input window and enter insert mode at the end of the input from the output window
      ['gf'] = { 'jump_to_file', mode = { 'n' } }, -- Jump to file at cursor in output window
      ['<M-r>'] = { 'cycle_variant', mode = { 'n' } }, -- Cycle through available model variants
      ['<leader>oS'] = { 'select_child_session' }, -- Select and load a child session
      ['<leader>oP'] = { 'select_parent_session' }, -- Go to parent session
      ['<leader>oB'] = { 'select_sibling_session' }, -- Select sibling session (children of same parent)
      ['<leader>oD'] = { 'debug_message' }, -- Open raw message in new buffer for debugging
      ['<leader>oO'] = { 'debug_output' }, -- Open raw output in new buffer for debugging
      ['<leader>ods'] = { 'debug_session' }, -- Open raw session in new buffer for debugging
    },
    session_picker = {
      rename_session = { '<C-r>' }, -- Rename selected session in the session picker
      delete_session = { '<C-d>' }, -- Delete selected session in the session picker
      new_session = { '<C-s>' }, -- Create and switch to a new session in the session picker
    },
    timeline_picker = {
      undo = { '<C-u>', mode = { 'i', 'n' } }, -- Undo to selected message in timeline picker
      fork = { '<C-f>', mode = { 'i', 'n' } }, -- Fork from selected message in timeline picker
    },
    history_picker = {
      delete_entry = { '<C-d>', mode = { 'i', 'n' } }, -- Delete selected entry in the history picker
      clear_all = { '<C-X>', mode = { 'i', 'n' } }, -- Clear all entries in the history picker
    },
    model_picker = {
      toggle_favorite = { '<C-f>', mode = { 'i', 'n' } },
    },
    mcp_picker = {
      toggle_connection = { '<C-t>', mode = { 'i', 'n' } }, -- Toggle MCP server connection in the MCP picker
    },
  },
  ui = {
    enable_treesitter_markdown = true, -- Use Treesitter for markdown rendering in the output window (default: true).
    position = 'right', -- 'right' (default), 'left' or 'current'. Position of the UI split. 'current' uses the current window for the output.
    input_position = 'bottom', -- 'bottom' (default) or 'top'. Position of the input window
    window_width = 0.40, -- Width as percentage of editor width
    zoom_width = 0.8, -- Zoom width as percentage of editor width
    display_model = true, -- Display model name on top winbar
    display_context_size = true, -- Display context size in the footer
    display_cost = true, -- Display cost in the footer
    window_highlight = 'Normal:OpencodeBackground,FloatBorder:OpencodeBorder', -- Highlight group for the opencode window
    persist_state = true, -- Keep buffers when toggling/closing UI so window state restores quickly
    icons = {
      preset = 'nerdfonts', -- 'nerdfonts' | 'text'. Choose UI icon style (default: 'nerdfonts')
      overrides = {}, -- Optional per-key overrides, see section below
    },
    questions = {
      use_vim_ui_select = false, -- If true, render questions/prompts with vim.ui.select instead of showing them inline in the output buffer.
      inline_other_input = true, -- If true, show an inline floating input for "Other" instead of vim.ui.input.
    },
    output = {
      filetype = 'opencode_output', -- Filetype assigned to the output buffer (default: 'opencode_output')
       compact_assistant_headers = false, -- 'full' (default), 'minimal' (compact if same mode), or 'hidden' (no headers for assistant)
       tools = {
         show_output = true, -- Show tools output [diffs, cmd output, etc.] (default: true)
         show_reasoning_output = true, -- Show reasoning/thinking steps output (default: true)
         use_folds = true, -- Use folds for tool output (default: true)
         folding_threshold = 25, -- Number of lines to show before folding when show_output is true (default: 25)
         fold_exclude = { -- Tools that should never be folded (default: sequential-thinking)
           'bash', -- built-in tool name (exact match)
           { server = 'sequential-thinking', tool = 'sequentialthinking' }, -- MCP tool (server + tool match)
         },
       },
      rendering = {
        markdown_debounce_ms = 250, -- Debounce time for markdown rendering on new data (default: 250ms)
        on_data_rendered = nil, -- Called when new data is rendered; set to false to disable default RenderMarkdown/Markview behavior
      },
      max_messages = nil, -- Max number of messages to keep in the output buffer; older messages will be removed as new ones arrive (default: nil, which means no limit)
    },
    input = {
      min_height = 0.10, -- min height of prompt input as percentage of window height
      max_height = 0.25, -- max height of prompt input as percentage of window height
      text = {
        wrap = false, -- Wraps text inside input window
      },
      -- Auto-hide input window when prompt is submitted or focus switches to output window
      auto_hide = false,
    },
    picker = {
      snacks_layout = nil -- `layout` opts to pass to Snacks.picker.pick({ layout = ... })
    },
    completion = {
      file_sources = {
        enabled = true,
        preferred_cli_tool = 'server', -- 'fd','fdfind','rg','git','server' if nil, it will use the best available tool, 'server' uses opencode cli to get file list (works cross platform) and supports folders
        ignore_patterns = {
          '^%.git/',
          '^%.svn/',
          '^%.hg/',
          'node_modules/',
          '%.pyc$',
          '%.o$',
          '%.obj$',
          '%.exe$',
          '%.dll$',
          '%.so$',
          '%.dylib$',
          '%.class$',
          '%.jar$',
          '%.war$',
          '%.ear$',
          'target/',
          'build/',
          'dist/',
          'out/',
          'deps/',
          '%.tmp$',
          '%.temp$',
          '%.log$',
          '%.cache$',
        },
        max_files = 10,
        max_display_length = 50, -- Maximum length for file path display in completion, truncates from left with "..."
      },
    },
  },
  context = {
    enabled = true, -- Enable automatic context capturing
    cursor_data = {
      enabled = false, -- Include cursor position and line content in the context
      context_lines = 5, -- Number of lines before and after cursor to include in context
    },
    diagnostics = {
      info = false, -- Include diagnostics info in the context (default to false
      warning = true, -- Include diagnostics warnings in the context
      error = true, -- Include diagnostics errors in the context
      only_closest = false, -- If true, only diagnostics for cursor/selection
    },
    current_file = {
      enabled = true, -- Include current file path and content in the context
      show_full_path = true,
    },
    files = {
      enabled = true,
      show_full_path = true,
    },
    selection = {
      enabled = true, -- Include selected text in the context
    },
    buffer = {
      enabled = false, -- Disable entire buffer context by default, only used in quick chat
    },
    git_diff = {
      enabled = false,
    },
  },
  logging = {
    enabled = false,
    level = 'warn', -- debug, info, warn, error
    outfile = nil,
  },
  debug = {
    enabled = false, -- Enable debug messages in the output window
    capture_streamed_events = false,
    show_ids = true,
    quick_chat = {
      keep_session = false, -- Keep quick_chat sessions for inspection, this can pollute your sessions list
      set_active_session = false,
    },
  },
  prompt_guard = nil, -- Optional function that returns boolean to control when prompts can be sent (see Prompt Guard section)
  child_readonly = true, -- When true (default), child sessions are read-only: messaging is blocked and input window is hidden on switch

-- User Hooks for custom behavior at certain events
  hooks = {
    on_file_edited = nil, -- Called after a file is edited by opencode.
    on_session_loaded = nil, -- Called after a session is loaded.
    on_done_thinking = nil, -- Called when opencode finishes thinking (all jobs complete).
    on_permission_requested = nil, -- Called when a permission request is issued.
  },
  quick_chat = {
    default_model = nil,   -- works better with a fast model like gpt-4.1
    default_agent = nil, -- Uses the current mode when nil
    instructions = nil, -- Use built-in instructions if nil
  },
})
```

### Keymap Configuration

The keymap configuration has been restructured for better organization and clarity:

- **`editor`**: Global keymaps that are available throughout Neovim
- **`input_window`**: Keymaps specific to the input window
- **`output_window`**: Keymaps specific to the output window
- **`permission`**: Special keymaps for responding to permission requests (available in input/output windows when there's a pending permission)

Configure keymaps with the current nested tables directly: `keymap.editor`, `keymap.input_window`, and `keymap.output_window`.

Each keymap entry is a table consising of:

- The string name of an api function = `{ 'toggle' }`
- Or a custom function: `{ function() ... end }`
- An optional mode: `{ 'toggle', mode = { 'n', 'i' } }`
- An optional desc: `{'toggle', desc = 'Toggle Opencode' }`
- An optional defer_to_completion: `{'toggle', defer_to_completion = true }` if true, when completion menu is open, it will defer to the completion keymaps instead of triggering the action

#### Disabling Specific Keymaps

You can disable specific default keymaps by setting them to `false` in your configuration:

```lua
require('opencode').setup({
  keymap = {
    input_window = {
      ['<cr>'] = false, -- Disable Enter key for submitting prompts
      -- Other keymaps not specified will keep their default bindings
    }
  }
})
```

### Model Sorting and Favorites

The provider/model picker supports intelligent sorting based on your favorites and usage history:

#### Sorting Priority

When you open the model picker (`<leader>op`), models are sorted in the following order:

1. **Favorite models** - shown with a ⭐ icon and sorted by the order they were favorited
2. **Recently accessed models** - sorted by most recent usage
3. **Other models** - sorted alphabetically

#### Managing Favorites

In the model picker, press **`<C-f>`** to toggle the currently selected model as a favorite. Favorite models will:

- Display with a ⭐ star icon prefix
- Always appear at the top of the list
- Persist across Neovim sessions

No configuration is needed - the plugin respects and updates the OpenCode CLI format automatically.

### Model Variants

Some models support multiple variants (e.g., different context window sizes or optimization modes). The plugin provides convenient ways to switch between available variants for the currently active model.

#### Switching Variants

- **Via picker**: Press `<leader>oV` to open the variant picker showing all available variants for the current model
- **Via cycling**: Press `<M-r>` (Alt+R) in the input or output window to cycle through available variants
- **Via slash command**: Type `/variant` in the input window

When you switch variants, the plugin remembers your selection per model, so the next time you use that model, it will automatically use the last selected variant.

### Avoid automatic blink.cmp menus while writing prompts

If blink.cmp opens completion menus while you are writing ordinary text in an OpenCode prompt, scope its automatic presentation to the `opencode` filetype. This keeps every configured source available, including buffer, path, environment, and AI sources; it only stops them from automatically interrupting ordinary prompt text. Explicit blink.cmp trigger characters and your existing manual completion keymap continue to work.

This Lazy.nvim recipe wraps your existing blink.cmp settings. Outside `opencode` buffers, it preserves your current `auto_show` and ghost-text behavior. In an OpenCode prompt, ghost text remains disabled unless you had enabled it already and the completion menu is open.

```lua
return {
  {
    "saghen/blink.cmp",
    optional = true,
    opts = function(_, opts)
      opts.completion = opts.completion or {}
      opts.completion.menu = opts.completion.menu or {}
      opts.completion.ghost_text = opts.completion.ghost_text or {}

local inherited_auto_show = opts.completion.menu.auto_show
      local inherited_ghost_text_enabled = opts.completion.ghost_text.enabled

opts.completion.menu.auto_show = function(ctx, items)
        if vim.bo[ctx.bufnr].filetype == "opencode" then
          -- Do not auto-open while writing prose; explicit Blink triggers still open it.
          return ctx.trigger.kind == "trigger_character"
        end

if type(inherited_auto_show) == "function" then
          return inherited_auto_show(ctx, items)
        end
        return inherited_auto_show ~= false
      end

opts.completion.ghost_text.enabled = function()
        local ghost_text_enabled = type(inherited_ghost_text_enabled) == "function"
            and inherited_ghost_text_enabled()
          or inherited_ghost_text_enabled == true

if vim.bo.filetype == "opencode" then
          return ghost_text_enabled and require("blink.cmp").is_menu_visible()
        end
        return ghost_text_enabled
      end

return opts
    end,
  },
}
```

### UI icons (disable emojis or customize)

By default, opencode.nvim uses emojis for icons in the UI. If you prefer a plain, emoji-free interface, you can switch to the `text` preset or override icons individually.

Minimal config to disable emojis everywhere:

```lua
require('opencode').setup({
  ui = {
    icons = {
      preset = 'text', -- switch all icons to text
    },
  },
})
```

Override specific icons while keeping the preset:

```lua
require('opencode').setup({
  ui = {
    icons = {
      preset = 'emoji',
      overrides = {
        header_user = '> U',
        header_assistant = 'AI',
        search = 'FIND',
        border = '|',
      },
    },
  },
})
```

Available icon keys (see implementation at lua/opencode/ui/icons.lua lines 7-29):

- header_user, header_assistant
- run, task, read, edit, write
- plan, search, web, list, tool
- snapshot, restore_point, restore_count, file
- status_on, status_off
- border, bullet

### Window Persistence Behavior

`ui.persist_state` controls how `toggle` behaves:

- `persist_state = true` (default): `toggle()` hides/restores the UI and keeps buffers/session view in memory for fast restore.
- `persist_state = false`: `toggle()` fully tears down UI buffers and recreates them on next open.

Related APIs:

- `require('opencode.api').toggle()` follows the `persist_state` behavior above.
- `require('opencode.api').close()` always fully closes and clears hidden snapshot state.
- `require('opencode.api').hide()` preserves buffers only when `persist_state = true`; otherwise it behaves like close.

### Picker Layout

You can customize the layout of the picker used for history, session, references, and timeline

#### Snacks Picker Integration with Opencode

You can configure a custom action in Snacks pickers to send selected files directly to opencode as context. This works with any file-based picker (files, git_files, buffers, git_status, etc.).

```lua
-- In your snacks.nvim configuration
{
  "folke/snacks.nvim",
  opts = {
    picker = {
      actions = {
        opencode_send = function(picker)
          local selected = picker:selected({ fallback = true })
          if selected and #selected > 0 then
            local files = {}
            for _, item in ipairs(selected) do
              if item.file then
                table.insert(files, item.file)
              end
            end
            picker:close()

require("opencode.core").open({
              new_session = false,
              focus = "input",
              start_insert = true,
            })

local context = require("opencode.context")
            for _, file in ipairs(files) do
              context.add_file(file)
            end
          end
        end,
      },
      win = {
        input = {
          keys = {
            -- Use <localleader>o or any preferred key to send files to opencode
            ["<localleader>o"] = { "opencode_send", mode = { "n", "i" } },
          },
        },
      },
    },
  },
}
```

This allows you to:

1. Open any Snacks file picker (`:Snacks picker files`, `:Snacks picker git_files`, etc.)
2. Select one or more files using multi-select
3. Press `<localleader>o` to send those files to opencode as context

#### Snacks Picker Layout

There's 3 main ways on how to change the snacks picker layout

1. Don't specify the new options -> it'll just default to the user's snack picker layout preset from their snacks config
2. Specify the new options for opencode, e.g.

```lua
   require("opencode").setup({
     ui = {
       picker = {
        ---@module "snacks"
        ---@type snacks.picker.layout.Config | nil
         snacks_layout = {
           layout = { border = "none", box = "vertical", ... }
         },
       },
     },
   })
   ```

3. Specify a [builtin layout preset](https://github.com/folke/snacks.nvim/blob/main/docs/picker.md#%EF%B8%8F-layouts) for snacks picker OR a custom layout defined in your snacks config's `opts.picker.layouts`

```lua
   -- opencode.lua
   require("opencode").setup({
     ui = {
       picker = {
        ---@module "snacks"
        ---@type snacks.picker.layout.Config | nil
         snacks_layout = {
           preset = "custom_layout" -- or builtin snacks, like "select", "default", etc
         },
       },
     },
   })
   ```

```lua
   -- snacks.lua
   {
     "folke/snacks.nvim",
     opts = {
       picker = {
         layouts = {
           custom_layout  = {
             layout = { border = "none", box = "vertical", ... }
             -- ...
   }
   ```

## 🧰 Usage

### Available Actions

The plugin provides the following actions that can be triggered via keymaps, commands, slash commands (typed in the input window), or the Lua API:

| Action                                                      | Default keymap                        | Command                                     | API Function                                                           |
| ----------------------------------------------------------- | ------------------------------------- | ------------------------------------------- | ---------------------------------------------------------------------- |
| Open opencode. Close if opened                              | `<leader>og`                          | `:Opencode`                                 | `require('opencode.api').toggle()`                                     |
| Open input window (current session)                         | `<leader>oi`                          | `:Opencode open input`                      | `require('opencode.api').open_input()`                                 |
| Open input window (new session)                             | `<leader>oI`                          | `:Opencode open input_new_session`          | `require('opencode.api').open_input_new_session()`                     |
| Open output window                                          | `<leader>oo`                          | `:Opencode open output`                     | `require('opencode.api').open_output()`                                |
| Create and switch to a named session                        | -                                     | `:Opencode session new <name>`              | `:Opencode session new <name>` (user command)                          |
| Rename current session                                      | `<leader>oR`                          | `:Opencode session rename <name>`           | `:Opencode session rename <name>` (user command)                       |
| Toggle focus opencode / last window                         | `<leader>ot`                          | `:Opencode toggle focus`                    | `require('opencode.api').toggle_focus()`                               |
| Close UI windows                                            | `<leader>oq`                          | `:Opencode close`                           | `require('opencode.api').close()`                                      |
| Select and load session                                     | `<leader>os`                          | `:Opencode session select`                  | `require('opencode.api').select_session()`                             |
| **Select and load child session**                           | `<leader>oS`                          | `:Opencode session child`                   | `require('opencode.api').select_child_session()`                       |
| **Select sibling session**                                  | `<leader>oB`                          | `:Opencode session sibling`                 | `require('opencode.api').select_sibling_session()`                     |
| **Go to parent session**                                    | `<leader>oP`                          | `:Opencode session parent`                  | `require('opencode.api').select_parent_session()`                      |
| Open timeline picker (navigate/undo/redo/fork to message)   | `<leader>oT`                          | `:Opencode timeline`                        | `require('opencode.api').timeline()`                                   |
| Browse code references from conversation                    | `gr` (window)                         | `:Opencode references` / `/references`      | `require('opencode.api').references()`                                 |
| Jump to file referenced at cursor in output window          | `gf` (window)                         | `:Opencode jump_to_file` / `/jump_to_file`  | `require('opencode.api').jump_to_file()`                               |
| Configure provider and model                                | `<leader>op`                          | `:Opencode configure provider`              | `require('opencode.api').configure_provider()`                         |
| Configure model variant                                     | `<leader>oV`                          | `:Opencode variant` / `/variant`            | `require('opencode.api').configure_variant()`                          |
| Cycle through model variants                                | `<M-r>` (window)                      | -                                           | `require('opencode.api').cycle_variant()`                              |
| Open diff view of changes                                   | `<leader>od`                          | `:Opencode diff open`                       | `require('opencode.api').diff_open()`                                  |
| Navigate to next file diff                                  | `<leader>o]`                          | `:Opencode diff next`                       | `require('opencode.api').diff_next()`                                  |
| Navigate to previous file diff                              | `<leader>o[`                          | `:Opencode diff prev`                       | `require('opencode.api').diff_prev()`                                  |
| Close diff view tab                                         | `<leader>oc`                          | `:Opencode diff close`                      | `require('opencode.api').diff_close()`                                 |
| Revert all file changes since last prompt                   | `<leader>ora`                         | `:Opencode revert all prompt`               | `require('opencode.api').diff_revert_all_last_prompt()`                |
| Revert current file changes last prompt                     | `<leader>ort`                         | `:Opencode revert this prompt`              | `require('opencode.api').diff_revert_this_last_prompt()`               |
| Revert all file changes since last session                  | `<leader>orA`                         | `:Opencode revert all session`              | `require('opencode.api').diff_revert_all_session()`                    |
| Revert current file changes last session                    | `<leader>orT`                         | `:Opencode revert this session`             | `require('opencode.api').diff_revert_this_session()`                   |
| Revert all files to a specific snapshot                     | -                                     | `:Opencode revert all_to_snapshot`          | `require('opencode.api').diff_revert_all(snapshot_id)`                 |
| Revert current file to a specific snapshot                  | -                                     | `:Opencode revert this_to_snapshot`         | `require('opencode.api').diff_revert_this(snapshot_id)`                |
| Restore a file to a restore point                           | -                                     | `:Opencode restore snapshot_file`           | `require('opencode.api').diff_restore_snapshot_file(restore_point_id)` |
| Restore all files to a restore point                        | -                                     | `:Opencode restore snapshot_all`            | `require('opencode.api').diff_restore_snapshot_all(restore_point_id)`  |
| Initialize/update AGENTS.md file                            | -                                     | `:Opencode session agents_init`             | `require('opencode.api').initialize()`                                 |
| Run prompt (continue session) [Run opts](#run-opts)         | -                                     | `:Opencode run <prompt> <opts>`             | `require('opencode.api').run("prompt", opts)`                          |
| Run prompt (new session) [Run opts](#run-opts)              | -                                     | `:Opencode run new_session <prompt> <opts>` | `require('opencode.api').run_new_session("prompt", opts)`              |
| Cancel opencode while it is running                         | `<C-c>`                               | `:Opencode cancel`                          | `require('opencode.api').cancel()`                                     |
| Set mode to Build                                           | -                                     | `:Opencode agent build`                     | `require('opencode.api').agent_build()`                                |
| Set mode to Plan                                            | -                                     | `:Opencode agent plan`                      | `require('opencode.api').agent_plan()`                                 |
| Select and switch mode/agent                                | -                                     | `:Opencode agent select`                    | `require('opencode.api').select_agent()`                               |
| Browse and select available skills                          | -                                     | `:Opencode skills` / `/skills`              | -                                                                      |
| Display list of available mcp servers                       | -                                     | `:Opencode mcp`                             | `require('opencode.api').mcp()`                                        |
| Run user commands                                           | -                                     | `:Opencode run user_command`                | `require('opencode.api').run_user_command()`                           |
| Share current session and get a link                        | -                                     | `:Opencode session share` / `/share`        | `require('opencode.api').share()`                                      |
| Unshare current session (disable link)                      | -                                     | `:Opencode session unshare` / `/unshare`    | `require('opencode.api').unshare()`                                    |
| Compact current session (summarize)                         | -                                     | `:Opencode session compact` / `/compact`    | `require('opencode.api').compact_session()`                            |
| Undo last opencode action                                   | -                                     | `:Opencode undo` / `/undo`                  | `require('opencode.api').undo()`                                       |
| Redo last opencode action                                   | -                                     | `:Opencode redo` / `/redo`                  | `require('opencode.api').redo()`                                       |
| Respond to permission requests (accept once)                | `a` (window) / `<leader>opa` (global) | `:Opencode permission accept`               | `require('opencode.api').permission_accept()`                          |
| Respond to permission requests (accept all)                 | `A` (window) / `<leader>opA` (global) | `:Opencode permission accept_all`           | `require('opencode.api').permission_accept_all()`                      |
| Respond to permission requests (deny)                       | `d` (window) / `<leader>opd` (global) | `:Opencode permission deny`                 | `require('opencode.api').permission_deny()`                            |
| Insert mention (file/ agent)                                | `@`                                   | -                                           | -                                                                      |
| [Pick a file and add to context](#file-mentions)            | `~`                                   | -                                           | -                                                                      |
| Navigate to next message                                    | `]]`                                  | -                                           | -                                                                      |
| Navigate to previous message                                | `[[`                                  | -                                           | -                                                                      |
| Navigate to previous prompt in history                      | `<up>`                                | -                                           | `require('opencode.api').prev_history()`                               |
| Navigate to next prompt in history                          | `<down>`                              | -                                           | `require('opencode.api').next_history()`                               |
| Toggle input/output panes                                   | `<tab>`                               | -                                           | -                                                                      |
| Swap Opencode pane left/right                               | `<leader>ox`                          | `:Opencode swap position`                   | `require('opencode.api').swap_position()`                              |
| Toggle tools output (diffs, cmd output, etc.)               | `<leader>ott`                         | `:Opencode toggle_tool_output`              | `require('opencode.api').toggle_tool_output()`                         |
| Toggle reasoning output (thinking steps)                    | `<leader>otr`                         | `:Opencode toggle_reasoning_output`         | `require('opencode.api').toggle_reasoning_output()`                    |
| Open a quick chat input with selection/current line context | `<leader>o/`                          | `:Opencode quick_chat`                      | `require('opencode.api').quick_chat()`                                 |
| Add visual selection to context                             | `<leader>oy`                          | `:Opencode add_visual_selection`            | `require('opencode.api').add_visual_selection(opts?)`                  |
| Insert visual selection inline into input                   | `<leader>oY`                          | `:Opencode add_visual_selection_inline`     | `require('opencode.api').add_visual_selection_inline(opts?)`           |

**add_visual_selection opts:**

- `open_input` (boolean, default: `true`): Whether to open the input window after adding the selection. Set to `false` to add selection silently without changing focus.

Example keymap for silent add:

```lua
['<leader>oy'] = { 'add_visual_selection', { open_input = false }, mode = {'v'} }
```

**add_visual_selection_inline** inserts the visually selected code directly into the input buffer as a Markdown code block, prefixed with the file path:

````
**`path/to/file.lua`**

```lua
<selected text>
````

````

The cursor is left in normal mode in the input buffer so you can type your prompt around the inserted snippet.

### Run opts

You can pass additional options when running a prompt via command or API:

- `agent=<agent_name>`: Specify the agent to use for this prompt (overrides current agent)
- `model=<provider/model_name>`: Specify the model to use for this prompt (overrides current model) e.g. `model=github-copilot/gpt-4.1`
- `context.<context_type>.enabled=<true|false>`: Enable/disable specific context types for this prompt only. Available context types:
  - `current_file`
  - `selection`
  - `diagnostics.info`
  - `diagnostics.warning`
  - `diagnostics.error`
  - `cursor_data`

#### Example

Run a prompt in a new session using the Plan agent and disabling current file context:

```vim
:Opencode run new_session "Please help me plan a new feature" agent=plan context.current_file.enabled=false
:Opencode run "Fix the bug in the current file" model=github-copilot/claude-sonnet-4
````

## 👮 Permissions

Opencode can issue permission requests for potentially destructive operations (file edits, reverting files, running shell commands, or enabling persistent tool access). Permission requests appear inline in the output and must be responded to before the agent performs the action. Visit [Opencode Permissions Documentation](https://opencode.ai/docs/permissions/) for more details.

### Responding to Permission Requests

- **Respond via the dialog:** Focus the Opencode window, move with `j`/`k` or arrow keys, then confirm with `<CR>`. Number shortcuts `1-3` also work for the visible options.
- **Command:** Use `:Opencode permission accept`, `:Opencode permission accept_all`, or `:Opencode permission deny`. You can pass an index to target a specific queued permission.
- **API:** Programmatic responses are available: `require('opencode.api').permission_accept()`, `require('opencode.api').permission_accept_all()`, `require('opencode.api').permission_deny()` which map to responses `"once"`, `"always"`, and `"reject"` respectively.
- **Behavior:** `accept once` allows the single requested action, `accept all` grants persistent permission for similar requests in the current session, and `deny` rejects the request.

---

## 📝 Context

The following editor context is automatically captured and included in your conversations.

| Context Type    | Description                                          |
| --------------- | ---------------------------------------------------- |
| Current file    | Path to the focused file before entering opencode    |
| Selected text   | Text and lines currently selected in visual mode     |
| Mentioned files | File info added through [mentions](#file-mentions)   |
| Diagnostics     | Diagnostics from the current file (if any)           |
| Cursor position | Current cursor position and line content in the file |

### Adding more files to context through file mentions

You can reference files in your project directly in your conversations with Opencode. This is useful when you want to ask about or provide context about specific files. Type `@` in the input window to trigger the file picker.
Supported pickers include [`fzf-lua`](https://github.com/ibhagwan/fzf-lua), [`telescope`](https://github.com/nvim-telescope/telescope.nvim), [`mini.pick`](https://github.com/echasnovski/mini.nvim/blob/main/readmes/mini-pick.md), [`snacks`](https://github.com/folke/snacks.nvim/blob/main/docs/picker.md)

### Context bar

You can quickly see the current context items in the context bar at the top of the input window:

For `Current file`, the color indicates whether it will be sent with the next prompt:

- Regular highlight: file is pending and will be included.
- Dimmed/gray highlight: file was already sent and has not changed, so it will be skipped (delta behavior).

If the file content changes, it becomes pending again and will be sent on the next prompt.

### Context Items Completion

You can quickly reference available context items by typing `#` in the input window. This will show a completion menu with all available context items:

- **Current File** - The currently focused file in the editor
- **Selection** - Currently selected text in visual mode
- **Diagnostics** - LSP diagnostics from the current file
- **Cursor Data** - Current cursor position and line content
- **[filename]** - Files that have been mentioned in the conversation
- **Agents** - Available agents to switch to
- **Selections** - Previously made selections in visual mode

Context items that are not currently available will be shown as disabled in the completion menu.

You should also see the list of files agents and selections in the menu, selecting them in the menu will remove them from the context.

## 🔄 Agents

Opencode provides two built-in agents and supports custom ones:

### Built-in Agents

- **Build** (default): Full development agent with all tools enabled for making code changes
- **Plan**: Restricted agent for planning and analysis without making file changes. Useful for code review and understanding code without modifications

### Switching Agent

Press `<M-m>` (Alt+M) in the input window to switch between agents during a session.

### Custom Agents

You can create custom agents through your opencode config file. Each agent can have its own:

- Agent configuration
- Custom prompt
- Enabled/disabled tools
- And more

See [Opencode Agents Documentation](https://opencode.ai/docs/agents/) for full configuration options.

## 🔌 Custom/External Server Configuration

By default, opencode.nvim spawns a local `opencode serve` process. You can instead connect to an external or containerized opencode server by configuring the `server` table.

### Basic Connection

Connect to an existing server:

```lua
require('opencode').setup({
  server = {
    url = 'localhost',     -- or 'http://192.168.1.100'
    port = 8080,
    timeout = 5,
  },
})
```

### Authentication

If your opencode server requires authentication, or if you would like the server that `opencode.nvim` starts to be behind authentication, you have a few options on how to provide the username and password.

If Neovim has the `OPENCODE_SERVER_PASSWORD` environment variable set the plugin will automatically use them for authentication. The username is optional (will default to `opencode`), but can also be set with `OPENCODE_SERVER_USERNAME`.

You can also supply the username and password directly in the config:

```lua
require('opencode').setup({
  server = {
    url = 'localhost',
    port = 8080,
    username = 'your_username_here', -- Optional, defaults to 'opencode' if not provided.
    password = 'your_password_here',
  }
})
```

Both the `username` and `password` fields accept a `function` that returns a string. The results will be cached for the session, and are only called when first attempting to start or connect to a server:

```lua
require('opencode').setup({
  server = {
    url = 'localhost',
    port = 8080,
    username = function()
      local keyfile = vim.fn.expand('~/.config/opencode/server-username')
      if vim.fn.filereadable(keyfile) == 1 then
        return vim.fn.trim(vim.fn.readfile(keyfile)[1])
      end
    end,
    password = function()
      local keyfile = vim.fn.expand('~/.config/opencode/server-password')
      if vim.fn.filereadable(keyfile) == 1 then
        return vim.fn.trim(vim.fn.readfile(keyfile)[1])
      end
    end,
  }
})
```

### Auto-Spawning with Docker

Use `spawn_command` to automatically start your server and `kill_command` to stop it:

```lua
require('opencode').setup({
  server = {
    url = 'https://localhost',
    port = 'auto',  -- Random port for project isolation
    -- Path mapping: translate host paths to container paths
    path_map = function(host_path)
      local cwd = vim.fn.getcwd()
      -- Replace host project directory with container mount point
      return host_path:gsub(vim.pesc(cwd), '/app')
    end,
    -- Spawn command: start Docker container with opencode server
    spawn_command = function(port, url)
      local dir_name = string.lower(vim.fn.fnamemodify(vim.fn.getcwd(), ":t"))
      local cwd = vim.fn.getcwd()
      local container_name = string.format('opencode-%s', dir_name)

-- Check if container is already running
      local check_cmd = string.format('docker ps --filter "name=%s" --format "{{.Names}}"', container_name)
      local handle = io.popen(check_cmd)
      local result = handle:read("*a")
      handle:close()

if result and result:match(container_name) then
        print(string.format("[opencode.nvim] Container %s is already running, skipping start", container_name))
        return true
      end

-- First, try to stop any existing container with the same name
      os.execute(string.format('docker stop %s 2>/dev/null || true', container_name))

local cmd = string.format([[
docker run -d --rm \
--name %s \
-p %d:4096 \
-v ~/.local/state/opencode:/home/node/.local/state/opencode \
-v ~/.local/share/opencode:/home/node/.local/share/opencode \
-v ~/.config/opencode:/home/node/.config/opencode \
-v "%s":/app:rw \
ghcr.io/anomalyco/opencode:latest serve --port 4096 --hostname '0.0.0.0']],
        container_name,
        port,
        cwd
      )

print(string.format("[opencode.nvim] Starting OpenCode container: %s on port %d", container_name, port))
      return os.execute(cmd)
    end,
    -- Kill command: stop Docker container when auto_kill is triggered
    kill_command = function(port, url)
      local dir_name = string.lower(vim.fn.fnamemodify(vim.fn.getcwd(), ":t"))
      local container_name = string.format('opencode-%s', dir_name)

print(string.format("[opencode.nvim] Stopping OpenCode container: %s", container_name))
      return os.execute(string.format('docker stop %s 2>/dev/null', container_name))
    end,
    auto_kill = true,  -- Enable automatic cleanup when last nvim exits
  },
})
```

### Path Mapping for Containers/WSL

When paths on the server differ from your host (e.g., `/app` in container vs `/home/user/project` on host):

```lua
require('opencode').setup({
  server = {
    url = 'localhost',
    port = 8080,
    path_map = '/app',  -- Simple string replacement
  },
})
```

### Auto-Spawning with WSL

Run opencode server inside WSL while using Neovim on Windows:

```lua
require('opencode').setup({
  server = {
    url = 'localhost',
    port = 'auto',  -- Random port for project isolation

-- Spawn opencode server inside WSL
    spawn_command = function(port, url)
      local cmd = string.format(
        'wsl.exe -e bash -c "opencode serve --hostname 127.0.0.1 --port %d"',
        port
      )
      print(string.format('[opencode.nvim] Starting WSL server on port %d', port))
      return vim.fn.jobstart(cmd, { detach = 1 })
    end,

-- Kill WSL opencode process
    kill_command = function(port, url)
      print(string.format('[opencode.nvim] Stopping WSL server on port %d', port))
      vim.fn.jobstart('wsl.exe -e pkill -f "opencode serve.*--port ' .. port .. '"')
    end,

-- Windows → WSL path translation (for requests)
    path_map = function(host_path)
      if vim.fn.has('win32') == 1 then
        -- Convert C:\Users\... → /mnt/c/Users/...
        local drive, rest = host_path:match('^([A-Za-z]):(.*)$')
        if drive then
          local wsl_path = '/mnt/' .. drive:lower() .. rest:gsub('\\', '/')
          return wsl_path
        end
      end
      return host_path
    end,

-- WSL → Windows path translation (for responses)
    reverse_path_map = function(server_path)
      -- Convert /mnt/c/Users/... → C:\Users\...
      local drive, rest = server_path:match('^/mnt/([a-z])(.*)$')
      if drive then
        local windows_path = drive:upper() .. ':' .. rest:gsub('/', '\\')
        return windows_path
      end
      return server_path
    end,

auto_kill = true,  -- Kill server when last nvim instance exits
  },
})
```

### Configuration Options

- `url` (string | nil): Server hostname/URL (e.g., 'localhost', 'http://192.168.1.100')
- `port` (number | 'auto' | nil): Port number, `'auto'` for random port, or nil for default (4096)
- `timeout` (number): Health check timeout in seconds (default: 5)
- `spawn_command` (function | nil): Optional function to start server: `function(port, url) ... end`
- `kill_command` (function | nil): Optional function to stop server when `auto_kill` triggers: `function(port, url) ... end`
- `auto_kill` (boolean): Kill spawned servers when last nvim instance exits (default: true)
- `path_map` (string | function | nil): Transform host paths to server paths (for outgoing requests)
- `reverse_path_map` (function | nil): Transform server paths back to host paths (for incoming responses/events)

### Multi-Instance Support

When `port = 'auto'` is used, opencode.nvim:

- Tracks which nvim instances are using each port
- Only kills the server when the last nvim instance exits (if `auto_kill = true`). Only applies to servers spawned by the plugin with `spawn_command`/`kill_command`.
- Locally spawned servers will be killed automatically regardless of the auto_kill setting if they are the last nvim instance using them

## 🎯 Skills

Skills are reusable, installable instruction packs that enhance opencode.nvim with domain-specific workflows. Each skill provides its own behavior, prompts, and tool configurations.

### Browsing Skills

- **Via command:** Run `:Opencode skills` to open the skills picker
- **Via slash command:** Type `/skills` in the input window to open the skills picker
- **Via completion:** Type `/` in the input window and select a skill from the completion menu

The skills picker displays each skill with its name, description, and full content rendered as markdown in the preview pane. Selecting a skill executes it directly — opening a session and sending the skill's content as a prompt.

### Installing Skills

See the [Opencode Skills Documentation](https://opencode.ai/docs/skills/) for how to discover and install community skills.

## User Commands and Slash Commands

You can run predefined user commands and built-in slash commands from the input window by typing `/`. This opens a command picker where you can select a command to execute. The output of the command will be included in your prompt context.

**Built-in slash commands** include:

- `/share` — Share the current session and get a link
- `/unshare` — Unshare the current session
- `/compact` — Compact (summarize) the current session
- `/undo` — Undo the last opencode action
- `/redo` — Redo the last undone action
- `/agents_init` — Initialize/update AGENTS.md
- `/help` — Show help
- `/mcp` — Show MCP servers
- `/skills` — Browse and select available skills
- `/models` — Switch provider/model
- `/variant` — Switch model variant
- `/sessions` — Switch session
- `/child-sessions` — Switch to a child session
- `/agent` — Switch agent/mode
- ...and more

**User commands** are custom scripts you define. They are loaded from:

- `.opencode/command/` (project-specific)
- `command/` (global, in config directory)

You can also run user commands by name with `:Opencode command <name>`.

See [User Commands Documentation](https://opencode.ai/docs/commands/) for more details.

## 📸 Contextual Actions for Snapshots

> [!WARNING] > _Snapshots are an experimental feature_
> in opencode and sometimes the dev team may disable them or change their behavior.
> This repository will be updated to match the latest opencode changes as soon as possible.

Opencode.nvim automatically creates **snapshots** of your workspace at key moments (such as after running prompts or making changes). These snapshots are like lightweight git commits, allowing you to review, compare, and restore your project state at any time.

**Contextual actions** for snapshots are available directly in the output window. When a snapshot is referenced in the conversation, you can trigger actions on it via keymaps displayed by the UI.

### Available Snapshot Actions

- **Diff:** View the differences between the current state and the snapshot.
- **Revert file:** Revert the selected file to the state it was in at the snapshot.
- **Revert all files:** Revert all files in the workspace to the state they were

### How to Use

- When a message in the output references a snapshot (look for 📸 **Created Snapshot** or similar), move your cursor to that line and a little menu will be displayed above.

### Example

When you see a snapshot in the output:

> **Tip:** Reverting a snapshot will restore all files to the state they were in at that snapshot, so use it with caution!

## 🕛 Contextual Restore points

Opencode.nvim automatically creates restore points before a revet operation. This allows you to undo a revert if needed.

You will see restore points under the Snapshot line like so:
<img src="https://i.imgur.com/DKCOdt0.png" alt="Opencode.nvim restore points" width="90%" />

### Available Restore Actions

- **Restore file:** Restore the selected file to the state it was in before the last revert operation.
- **Restore all :** Restore all files in the workspace to the state they were in before the revert action

## Highlight Groups

The plugin defines several highlight groups that can be customized to match your colorscheme:

- `OpencodeBorder`: Border color for Opencode windows (default: #616161)
- `OpencodeBackground`: Background color for Opencode windows (linked to `Normal`)
- `OpencodeSessionDescription`: Session description text color (linked to `Comment`)
- `OpencodeMention`: Highlight for @file mentions (linked to `Special`)
- `OpencodeToolBorder`: Border color for tool execution blocks (default: #3b4261)
- `OpencodeMessageRoleAssistant`: Assistant message highlight (linked to `Added`)
- `OpencodeMessageRoleUser`: User message highlight (linked to `Question`)
- `OpencodeDiffAdd`: Highlight for added line in diffs (default: #2B3328)
- `OpencodeDiffDelete`: Highlight for deleted line in diffs (default: #43242B)
- `OpencodeAgentPlan`: Agent indicator in winbar for Plan mode (default: #61AFEF background)
- `OpencodeAgentBuild`: Agent indicator in winbar for Build mode (default: #616161 background)
- `OpencodeAgentCustom`: Agent indicator in winbar for custom modes (default: #3b4261 background)
- `OpencodeContestualAction`: Highlight for contextual actions in the output window (default: #3b4261 background)
- `OpencodeInputLegend`: Highlight for input window legend (default: #CCCCCC background)
- `OpencodeHint`: Highlight for hinting messages in input window and token info in output window footer (linked to `Comment`)

## 🛡️ Prompt Guard

The `prompt_guard` configuration option allows you to control when prompts can be sent to Opencode. This is useful for preventing accidental or unauthorized AI interactions in certain contexts.

### Configuration

Set `prompt_guard` to a function that returns a boolean:

```lua
require('opencode').setup({
  prompt_guard = function()
    -- Your custom logic here
    -- Return true to allow, false to deny
    return true
  end,
})

```

## 🪝 Custom user hooks

You can define custom functions to be called at specific events in Opencode:

- `on_file_edited`: Called after a file is edited by Opencode.
- `on_session_loaded`: Called after a session is loaded.
- `on_done_thinking`: Called when Opencode finishes thinking (all user jobs complete).
- `on_permission_requested`: Called when a permission request is issued.

```lua
require('opencode').setup({
  hooks = {
    on_file_edited = function(file_path, edit_type)
      -- Custom logic after a file is edited
      print("File edited: " .. file_path .. " Type: " .. edit_type)
    end,
    on_session_loaded = function(session_name)
      -- Custom logic after a session is loaded
      print("Session loaded: " .. session_name)
    end,
    on_done_thinking = function()
      -- Custom logic when thinking is done
      print("Done thinking!")
    end,
    on_permission_requested = function()
      -- Custom logic when a permission is requested
      print("Permission requested!")
    end,
  },
})
```

### Behavior

- **Before sending prompts**: The guard is checked before any prompt is sent to the AI. If denied, an ERROR notification is shown and the prompt is not sent.
- **Before opening UI**: The guard is checked when opening the Opencode buffer for the first time. If denied, a WARN notification is shown and the UI is not opened.
- **No parameters**: The guard function receives no parameters. Access vim state directly (e.g., `vim.fn.getcwd()`, `vim.bo.filetype`).
- **Error handling**: If the guard function throws an error or returns a non-boolean value, the prompt is denied with an appropriate error message.

## 📡 Server-Sent Events (SSE) autocmds

Opencode.nvim forwards all server-sent events as Neovim User autocmds, allowing you to react to events and automate workflows. All events are fired with the pattern `OpencodeEvent:<event.type>`.

### Event Data Structure

The autocmd receives event data in `args.data.event`:

```lua
{
  type = "event.name",  -- Opencode event type
  properties = { ... }  -- Event-specific properties
}
```

### Wildcard Patterns

You can use wildcards to match multiple event types:

- `OpencodeEvent:*` - All events
- `OpencodeEvent:session.*` - All session events
- `OpencodeEvent:permission.*` - All permission events

### Example

```lua
vim.api.nvim_create_autocmd('User', {
  pattern = 'OpencodeEvent:permission.asked',
  callback = function(args)
    local event = args.data.event
    vim.notify(vim.inspect(event))
    -- trigger custom logic
  end,
})
```

## Quick chat

Quick chat allows you to start a temporary opencode session with context from the current line or selection.
This is optimized for narrow code edits or insertion. When the request is complex it will and require more context, it is recommended to use the full opencode UI.

Due to the narrow context the resulting may be less accurate and edits may sometime fails. For best results, try to keep the request focused and simple.

### Starting a quick chat

Press `<leader>o/` in normal mode to open a quick chat input window.

### Example chat prompts

- Transform to a lua array
- Add lua annotations
- Write a conventional commit message for my changes #diff
- Fix these warnings #warn
- complete this function

## 🔧 Setting up Opencode

If you're new to opencode:

1. **What is Opencode?**
   - Opencode is an AI coding agent built for the terminal
   - It offers powerful AI assistance with extensible configurations such as LLMs and MCP servers

2. **Installation:**
   - Visit [Install Opencode](https://opencode.ai/docs/#install) for installation and configuration instructions
   - Ensure the `opencode` command is available after installation

3. **Configuration:**
   - Run `opencode auth login` to set up your LLM provider
   - Configure your preferred LLM provider and model in the `~/.config/opencode/config.json` or `~/.config/opencode/opencode.json` file

## 🙏 Acknowledgements

This plugin is a fork of the original [goose.nvim](https://github.com/azorng/goose.nvim) plugin by [azorng](https://github.com/azorng/)
For git history purposes the original code is copied instead of just forked.

opencode.nvim

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README