goose.nvim: a Neovim chat bridge to the goose agent, and what it does with your buffer
seamless neovim integration with goose - work with a powerful AI agent without leaving your editor
At a glance
- What is it?
- goose.nvim is a Lua plugin that runs the goose CLI inside a Neovim chat window and attaches the current file or selection to each prompt. It is a thin client over an external agent, so the plugin's value depends entirely on whether you already run goose.
- Who is it for?
- Adopt goose.nvim if you already run the goose CLI and want its sessions attached to a workspace inside Neovim, with selection capture and per-prompt diff revert as the main conveniences. Do not adopt it if you have no goose binary on PATH, because the README lists the CLI as the only requirement and the plugin is a front end, not an agent.
- Can I use it commercially?
- Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 21 days ago.
- What is it written in?
- Mainly Lua, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The gap goose.nvim fills, and the gap it leaves open
An agent that lives in a terminal has one recurring annoyance: every time you want it to look at code, you copy a file path or paste a function into the prompt. goose.nvim removes that step. The README describes it as a bridge between Neovim and the goose AI agent that creates a chat interface while capturing editor context, specifically the current file and selections, to enhance prompts. Sessions are persistent and tied to the workspace, which the README compares to what tools like Cursor AI offer.
The target user is narrow and identifiable. You need the goose CLI installed and available, since that is the sole entry under Requirements. The plugin does not bundle a model, a provider or an agent loop. It is a Lua front end that talks to a binary you install separately. If you have not already chosen goose as your agent, this plugin gives you no reason to start. If you have, it removes the copy-paste tax and gives you a chat pane that knows which file you are in.
How the plugin talks to goose and what it keeps between prompts
The architecture visible in the README is a client-server split. Neovim hosts the UI, meaning a floating or split window with an input pane and an output pane, and the goose CLI does the inference and tool execution. The plugin's job is to assemble context, send it, and render what comes back.
Two mechanisms stand out. First, workspace-scoped persistent sessions: the README states sessions are tied to your workspace so a conversation continues across restarts rather than resetting each time you open the editor. Second, context capture from the editor itself. The plugin takes the current file and any selection and folds them into the prompt. There is also a file mention key, bound to @ by default, that opens a picker and adds a file to context. Sessions can be inspected as JSON through :GooseInspectSession or the <leader>g? mapping, which is the honest way to check what the plugin actually attached to a request when a prompt behaves unexpectedly.
Because the agent runs outside Neovim, its file edits happen on disk. goose.nvim tracks changes since the last prompt and exposes a diff workflow, including <leader>gd to open a diff tab, <leader>g] and <leader>g[ to move between changed files, and <leader>gra and <leader>grt to revert everything or just the current file. That revert scoping is the most interesting design decision in the plugin: the unit of undo is the prompt, not the file or the git commit.
Modes, providers and the configuration keys that matter
Setup is a single call, require('goose').setup({}), and the README publishes the full default table. The keys worth reading before you accept the defaults are prefered_picker, ui.window_type, and the provider list.
prefered_picker accepts 'telescope', 'fzf', 'mini.pick' or 'snacks'. When it is nil the plugin picks the best available picker on its own. That automatic choice is convenient and also the first thing to check if the @ file mention behaves oddly, since the resolved picker depends on what is installed in your Neovim, not on anything goose.nvim controls. The key name itself is misspelled in the source, so copy it exactly as written; a corrected spelling will not match.
ui.window_type takes "float" or "split", with window_width at 0.35 of editor width, input_height at 0.15 of window height, and layout restricted to right, left or center for floating windows. display_model puts the model name on the winbar, and display_goose_mode is off by default.
Modes are bound to individual keys: <leader>gmc for chat, which the README says disables tool calling and drops editor context except selections, <leader>gma for auto with full agent capability, <leader>gmp for approve, which requires manual approval for every tool use, and <leader>gms for smart_approve, described as risk-based approval. The distinction between chat and auto is the one that will surprise people. In chat mode the agent cannot touch your files, so the diff and revert machinery is inert. That is a sensible safety default to reach for, but it also means a prompt that asks for an edit will do nothing in that mode.
The providers table is where you declare which models appear in the quick switch bound to <leader>gp. The README lists anthropic, azure, bedrock, databricks, google, groq, ollama, openai and openrouter as the recognized names, with example entries such as openrouter mapping to "anthropic/claude-3.5-sonnet" and ollama mapping to "cogito:14b". These are model identifiers passed through to goose, not values the plugin interprets.
Installation, dependencies and the CLI you must supply yourself
The README gives a lazy.nvim spec. The plugin is azorng/goose.nvim, config calls require("goose").setup({}), and there are two declared dependencies: nvim-lua/plenary.nvim and MeanderingProgrammer/render-markdown.nvim. The second one is not optional in the spec as written, which tells you the output pane renders markdown through that plugin rather than a built-in renderer. If you already use a different markdown renderer, you are adding a second one or reconciling them.
Before any of that, the goose CLI has to be installed and on PATH. The README points to a separate section on setting up goose and does not restate the installation steps, so the plugin's setup instructions are incomplete on their own. Budget for reading goose's own documentation first.
Every action is reachable three ways: a default keymap, an Ex command, and a Lua function. :Goose toggles the UI, :GooseOpenInput and :GooseOpenInputNewSession open the input pane against the current or a fresh session, and :GooseOpenOutput focuses the output pane. The same actions are callable as require('goose.api').toggle(), open_input(), open_input_new_session() and open_output(), which is how you would wire goose.nvim into a keymap of your own or trigger it from another plugin. Setting default_global_keymaps to false disables the whole <leader>g family if it collides with mappings you already use.
Where goose.nvim is the wrong tool
The plugin inherits every limitation of the CLI it wraps, and adds a few of its own.
The clearest failure mode is an environment problem, not a code problem. If the goose binary is missing or not on PATH, the chat window has nothing to talk to. The README lists no fallback, no bundled runtime and no diagnostic for this case, so the first symptom is a UI that opens and does not respond. Verifying the CLI from a shell before filing anything is the sensible order of operations.
Sessions are workspace-scoped, which is a benefit until it is not. A long-lived session accumulates context, and the README offers no documented compaction, pruning or token budget control. The only escape hatches visible in the material are starting a new session with <leader>gI and inspecting the current one as JSON. If you work across several repositories in one Neovim instance, the workspace binding is the thing to understand before you rely on continuity.
The revert commands are scoped to changes since the last goose prompt. That is precise, and it is also fragile: if you edit the same file by hand between prompts, <leader>grt does not distinguish your edits from the agent's. Anyone who wants git-level control over agent output is better served by committing before each prompt and using git's own revert.
Finally, the plugin is Neovim-only and Lua-only. There is no VS Code extension, no terminal multiplexer integration, and nothing for editors outside the Neovim ecosystem. The README's own comparison point, Cursor AI, is a different kind of product entirely, an editor with an agent built in rather than a bridge to one you install.
Alternatives and the actual difference in approach
The most direct alternative is running the goose CLI in a terminal split next to Neovim. The difference is not cosmetic. A terminal split gives you goose's own interface, its own session handling and its own output, with no Lua layer in between. You lose editor context capture, so you paste file paths and selections by hand, and you lose the prompt-scoped diff and revert commands. You also lose the plugin as a failure point. For someone who runs goose rarely, or who prefers goose's native terminal UI, the split is strictly less machinery for nearly the same capability.
A second alternative is a general AI-assistant plugin for Neovim that talks to a provider API directly rather than to a local agent binary. Those plugins typically ship their own request layer, their own context assembly and their own tool definitions, which means no separate CLI to install and no external process to keep alive. The trade is that the agent loop and tool execution live inside the plugin, so you get whatever tools that plugin implements instead of goose's tool set and its approval modes. goose.nvim's approve and smart_approve modes only exist because goose is doing the tool calling underneath.
A third path is to skip the chat pane and use goose headlessly, driving it from scripts or from Neovim's job control for specific tasks. That suits batch work. It does not give you a persistent conversational session tied to the buffer you are looking at, which is the specific thing goose.nvim was built for.
Maintenance, licence and what a version bump costs you
goose.nvim is licensed Apache-2.0, a permissive licence that permits commercial use and modification and includes an explicit patent grant. It also requires that modified files carry notices and that you state significant changes. That is a description of the licence text, not legal advice; if you fork and redistribute, read the terms yourself.
The release cadence visible in the material is modest: v1.0.3 in November 2025, v1.0.4 later that month, v1.0.5 in January 2026, with the most recent push to the default branch in August 2026. That pattern suggests a project that is maintained but not churning, which cuts both ways. Your keymaps are unlikely to be renamed under you. You are also unlikely to see new capabilities arrive quickly.
The real upgrade cost is not in the plugin. It is in the goose CLI. Because goose.nvim is a bridge, a change in goose's session format, provider names or mode semantics propagates straight through the plugin's configuration surface. The providers table, the four mode keymaps and the session inspection command are all coupled to goose's interface. When you bump the CLI, re-check that the model names in your providers table are still valid and that the mode keymaps still do what their comments claim. The plugin's own version number tells you very little about that.
Editorial conclusion
Adopt goose.nvim if you already run the goose CLI and want its sessions attached to a workspace inside Neovim, with selection capture and per-prompt diff revert as the main conveniences. Do not adopt it if you have no goose binary on PATH, because the README lists the CLI as the only requirement and the plugin is a front end, not an agent. Before installing, verify the goose CLI works from a shell, check that plenary.nvim and render-markdown.nvim are available as dependencies, and confirm which picker your setup resolves to when prefered_picker is left at nil.
Community notes