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

This plugin is a fork of the original goose.nvim plugin by azorng For git history purposes the original code is copied instead of just forked.

This plugin provides a bridge between neovim and the 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.

• ⚠️Caution
• Requirements
• Installation
• Configuration
• Usage
• Context
• Agents
• User Commands
• Contextual Actions for Snapshots
• Setting up opencode

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.

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.

• Opencode (v0.6.3+ or more) CLI installed and available (see Setting up opencode below)

Install the plugin with your favorite package manager. See the Configuration section below for customization options.

{
  "sudo-tee/opencode.nvim",
  config = function()
    require("opencode").setup({})
  end,
  dependencies = {
    "nvim-lua/plenary.nvim",
    {
      "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',
  },
}

Note: The keymap configuration structure has been updated. Old keymaps (keymap.global and keymap.window) will be mapped to the new format (keymap.editor, keymap.input_window, keymap.output_window) but you should update your config to the new format. See Keymap Configuration below for details.

-- Default configuration with all available options
require('opencode').setup({
  preferred_picker = nil, -- 'telescope', 'fzf', 'mini.pick', 'snacks', 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/)
  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
  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>oq'] = { 'close' }, -- Close UI windows
      ['<leader>os'] = { 'select_session' }, -- Select and load a opencode session
      ['<leader>op'] = { 'configure_provider' }, -- Quick provider and model switch from predefined list
      ['<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>opa'] = { 'permission_accept' }, -- Accept permission request once
      ['<leader>opA'] = { 'permission_accept_all' }, -- Accept all (for current tool)
      ['<leader>opd'] = { 'permission_deny' }, -- Deny permission request once
    },
    input_window = {
      ['<cr>'] = { 'submit_input_prompt', mode = { 'n', 'i' } }, -- Submit prompt (normal mode and insert mode)
      ['<esc>'] = { 'close' }, -- Close UI windows
      ['<C-c>'] = { 'stop' }, -- Stop opencode 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
      ['<tab>'] = { 'toggle_pane', mode = { 'n', 'i' } }, -- Toggle between input and output panes
      ['<up>'] = { 'prev_prompt_history', mode = { 'n', 'i' } }, -- Navigate to previous prompt in history
      ['<down>'] = { 'next_prompt_history', mode = { 'n', 'i' } }, -- Navigate to next prompt in history
      ['<M-m>'] = { 'switch_mode' }, -- Switch between modes (build/plan)
    },
    output_window = {
      ['<esc>'] = { 'close' }, -- Close UI windows
      ['<C-c>'] = { 'stop' }, -- Stop opencode 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
      ['<C-i>'] = { 'focus_input' }, -- Focus on input window and enter insert mode at the end of the input from the output window
      ['<leader>oS'] = { 'select_child_session' }, -- Select and load a child session
      ['<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
    },
    permission = {
      accept = 'a', -- Accept permission request once (only available when there is a pending permission request)
      accept_all = 'A', -- Accept all (for current tool) permission request once (only available when there is a pending permission request)
      deny = 'd', -- Deny permission request once (only available when there is a pending permission request)
    },
  },
  ui = {
    position = 'right', -- 'right' (default) or 'left'. Position of the UI split
    input_position = 'bottom', -- 'bottom' (default) or 'top'. Position of the input window
    window_width = 0.40, -- Width as percentage of editor width
    input_height = 0.15, -- Input height as percentage of window height
    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
    icons = {
      preset = 'emoji', -- 'emoji' | 'text'. Choose UI icon style (default: 'emoji')
      overrides = {}, -- Optional per-key overrides, see section below
    },
    output = {
      tools = {
        show_output = true, -- Show tools output [diffs, cmd output, etc.] (default: true)
      },
    },
    input = {
      text = {
        wrap = false, -- Wraps text inside input window
      },
    },
    completion = {
      file_sources = {
        enabled = true,
        preferred_cli_tool = 'fd', -- 'fd','fdfind','rg','git' if nil, it will use the best available tool
        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
    },
    diagnostics = {
      info = false, -- Include diagnostics info in the context (default to false
      warn = true, -- Include diagnostics warnings in the context
      error = true, -- Include diagnostics errors in the context
    },
    current_file = {
      enabled = true, -- Include current file path and content in the context
    },
    selection = {
      enabled = true, -- Include selected text in the context
    },
  },
  debug = {
    enabled = false, -- Enable debug messages in the output window
  },
})

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)

Backward Compatibility: The plugin automatically maps configurations that use keymap.global and keymap.window to the new structure. A deprecation warning will be shown during migration. Update your configuration to use the new structure to remove the warning.

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' }

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:

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

Override specific icons while keeping the preset:

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

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

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.warn
  • diagnostics.error
  • cursor_data

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

:OpencodeRunNewSession "Please help me plan a new feature" agent=plan context.current_file.enabled=false
:OpencodeRun "Fix the bug in the current file" model=github-copilot/claude-sonned-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 for more details.

• Respond via keys: In the input window press a to accept once, A to accept and remember (accept all), or d to deny. These window keys are configurable in ui.keymap.window.permission_*.
• Global keymaps: There are also global keymaps to respond outside the input window: <leader>opa (accept once), <leader>opA (accept all), <leader>opd (deny). These are configurable in keymap.global.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.

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

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, telescope, mini.pick, snacks

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

• 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

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

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

• Agentl configuration
• Custom prompt
• Enabled/disabled tools
• And more

See Opencode Agents Documentation for full configuration options.

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
• /init — Initialize/update AGENTS.md
• /help — Show help
• /mcp — Show MCP servers
• /models — Switch provider/model
• /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 :OpencodeRunUserCommand <name> or /run_user_command <name>.

See User Commands Documentation for more details.

[!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.

• 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

• 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.

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!

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:

• 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

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)
• OpencodeInpuutLegend: 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)

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 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