🤖 opencode.nvim

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

🙏 Acknowledgements

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.

✨ Description

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.

📑 Table of Contents

⚠️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.

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

🚀 Installation

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

With lazy.nvim

{
  "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',
  },
}

⚙️ Configuration

-- 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 = {
    global = {
      toggle = '<leader>og', -- Open opencode. Close if opened
      open_input = '<leader>oi', -- Opens and focuses on input window on insert mode
      open_input_new_session = '<leader>oI', -- Opens and focuses on input window on insert mode. Creates a new session
      open_output = '<leader>oo', -- Opens and focuses on output window
      toggle_focus = '<leader>ot', -- Toggle focus between opencode and last window
      close = '<leader>oq', -- Close UI windows
      select_session = '<leader>os', -- Select and load a opencode session
      configure_provider = '<leader>op', -- Quick provider and model switch from predefined list
      diff_open = '<leader>od', -- Opens a diff tab of a modified file since the last opencode prompt
      diff_next = '<leader>o]', -- Navigate to next file diff
      diff_prev = '<leader>o[', -- Navigate to previous file diff
      diff_close = '<leader>oc', -- Close diff view tab and return to normal editing
      diff_revert_all_last_prompt = '<leader>ora', -- Revert all file changes since the last opencode prompt
      diff_revert_this_last_prompt = '<leader>ort', -- Revert current file changes since the last opencode prompt
      diff_revert_all = '<leader>orA', -- Revert all file changes since the last opencode session
      diff_revert_this = '<leader>orT', -- Revert current file changes since the last opencode session
      swap_position = '<leader>ox', -- Swap Opencode pane left/right
    },
    window = {
      submit = '<cr>', -- Submit prompt (normal mode)
      submit_insert = '<cr>', -- Submit prompt (insert mode)
      close = '<esc>', -- Close UI windows
      stop = '<C-c>', -- Stop opencode while it is running
      next_message = ']]', -- Navigate to next message in the conversation
      prev_message = '[[', -- Navigate to previous message in the conversation
      mention = '@', -- Insert mention (file/agent)
      mention_file = '~', -- Pick a file and add to context. See File Mentions section
      slash_commands = '/', -- Pick a command to run in the input window
      toggle_pane = '<tab>', -- Toggle between input and output panes
      prev_prompt_history = '<up>', -- Navigate to previous prompt in history
      next_prompt_history = '<down>', -- Navigate to next prompt in history
      switch_mode = '<M-m>', -- Switch between modes (build/plan)
      focus_input = '<C-i>', -- Focus on input window and enter insert mode at the end of the input from the output window
      select_child_session = '<leader>oS', -- Select and load a child session
      debug_message = '<leader>oD', -- Open raw message in new buffer for debugging
      debug_output = '<leader>oO', -- Open raw output in new buffer for debugging
    },
  },
  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
  },
})

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:

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

🧰 Usage

Available Actions

The plugin provides the following actions that can be triggered via keymaps, commands, 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`	`:OpencodeOpenInput`	`require('opencode.api').open_input()`
Open input window (new session)	`<leader>oI`	`:OpencodeOpenInputNewSession`	`require('opencode.api').open_input_new_session()`
Open output window	`<leader>oo`	`:OpencodeOpenOutput`	`require('opencode.api').open_output()`
Create and switch to a named session	-	`:OpencodeCreateNewSession`	`require('opencode.api').new_session()` Not implemented yet
Toggle focus opencode / last window	`<leader>ot`	`:OpencodeToggleFocus`	`require('opencode.api').toggle_focus()`
Close UI windows	`<leader>oq`	`:OpencodeClose`	`require('opencode.api').close()`
Select and load session	`<leader>os`	`:OpencodeSelectSession`	`require('opencode.api').select_session()`
Select and load child session	`<leader>oS`	`:OpencodeSelectChildSession`	`require('opencode.api').select_child_session()`
Configure provider and model	`<leader>op`	`:OpencodeConfigureProvider`	`require('opencode.api').configure_provider()`
Open diff view of changes	`<leader>od`	`:OpencodeDiff`	`require('opencode.api').diff_open()`
Navigate to next file diff	`<leader>o]`	`:OpencodeDiffNext`	`require('opencode.api').diff_next()`
Navigate to previous file diff	`<leader>o[`	`:OpencodeDiffPrev`	`require('opencode.api').diff_prev()`
Close diff view tab	`<leader>oc`	`:OpencodeDiffClose`	`require('opencode.api').diff_close()`
Revert all file changes since last prompt	`<leader>ora`	`:OpencodeRevertAllLastPrompt`	`require('opencode.api').diff_revert_all_last_prompt()`
Revert current file changes last prompt	`<leader>ort`	`:OpencodeRevertThisLastPrompt`	`require('opencode.api').diff_revert_this_last_prompt()`
Revert all file changes since last session	`<leader>orA`	`:OpencodeRevertAllSession`	`require('opencode.api').diff_revert_all_session()` Not implemented yet
Revert current file changes last session	`<leader>orT`	`:OpencodeRevertThisSession`	`require('opencode.api').diff_revert_this_session()` Not implemented yet
Initialize/update AGENTS.md file	-	`:OpencodeInit`	`require('opencode.api').initialize()`
Run prompt (continue session) Run opts	-	`:OpencodeRun <prompt> <opts>`	`require('opencode.api').run("prompt", opts)`
Run prompt (new session) Run opts	-	`:OpencodeRunNewSession <prompt> <opts>`	`require('opencode.api').run_new_session("prompt", opts)`
Stop opencode while it is running	`<C-c>`	`:OpencodeStop`	`require('opencode.api').stop()`
Set mode to Build	-	`:OpencodeAgentBuild`	`require('opencode.api').agent_build()`
Set mode to Plan	-	`:OpencodeAgentPlan`	`require('opencode.api').agent_plan()`
Select and switch mode/agent	-	`:OpencodeAgentSelect`	`require('opencode.api').select_agent()`
Display list of availale mcp servers	-	`:OpencodeMCP`	`require('opencode.api').mcp()`
Run user commands	-	`:OpencodeRunUserCommand`	`require('opencode.api').run_user_command()`
Insert mention (file/ agent)	`@`	-	-
Pick a file and add to context	`~`	-	-
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`	`:OpencodeSwapPosition`	`require('opencode.api').swap_position()`

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

Example

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

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

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

Agentl configuration
Custom prompt
Enabled/disabled tools
And more

See Opencode Agents Documentation for full configuration options.

User Commands

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

To configure user commands

Store command files in these locations:

.opencode/command/ - Project-specific commands command/ - Global commands in config directory

See User Commands Documentation for more details 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:

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

🔧 Setting up Opencode

If you're new to opencode:

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
Installation:
- Visit Install Opencode for installation and configuration instructions
- Ensure the opencode command is available after installation
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

Name		Name	Last commit message	Last commit date
Latest commit History 185 Commits
lua/opencode		lua/opencode
plugin		plugin
tests		tests
.gitignore		.gitignore
.luarc.json		.luarc.json
.stylua.toml		.stylua.toml
AGENTS.md		AGENTS.md
LICENSE		LICENSE
README.md		README.md
run_tests.sh		run_tests.sh
test.txt		test.txt

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Repository files navigation

🤖 opencode.nvim

🙏 Acknowledgements

✨ Description

📑 Table of Contents

⚠️Caution

📋 Requirements

🚀 Installation

With lazy.nvim

⚙️ Configuration

UI icons (disable emojis or customize)

🧰 Usage

Available Actions

Run opts

Example

📝 Context

Adding more files to context through file mentions

🔄 Agents

Built-in Agents

Switching Agent

Custom Agents

User Commands

Store command files in these locations:

📸 Contextual Actions for Snapshots

Available Snapshot Actions

How to Use

Example

🕛 Contextual Restore points

Available Restore Actions

Highlight Groups

🔧 Setting up Opencode

About

Uh oh!

Releases

Packages

Languages

License

rustybucket-cloud/opencode.nvim

Folders and files

Latest commit

History

Repository files navigation

🤖 opencode.nvim

🙏 Acknowledgements

✨ Description

📑 Table of Contents

⚠️Caution

📋 Requirements

🚀 Installation

With lazy.nvim

⚙️ Configuration

UI icons (disable emojis or customize)

🧰 Usage

Available Actions

Run opts

Example

📝 Context

Adding more files to context through file mentions

🔄 Agents

Built-in Agents

Switching Agent

Custom Agents

User Commands

Store command files in these locations:

📸 Contextual Actions for Snapshots

Available Snapshot Actions

How to Use

Example

🕛 Contextual Restore points

Available Restore Actions

Highlight Groups

🔧 Setting up Opencode

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages