parrot.nvim: LLM text editing inside Neovim without background requests

What parrot.nvim solves, and who it is aimed at

The plugin targets text generation inside Neovim buffers: rewriting a selection, appending generated code with the selection as context, prepending comments to a function, and holding a chat in an ordinary markdown buffer. The README frames the audience narrowly. It says the plugin "is intended for people who actually know what they are doing and people who care for privacy and transparency," and that the user stays in control of what is sent to the API endpoint.

That framing is the design constraint, not marketing. The README states the plugin "fully excludes" the notion of agents found in codex, claude-code and gemini-cli. It also states there is no autocompletion and no hidden requests in the background to analyze your files. So the scope is a manual, buffer-local editing tool. If you want a tool that decides on its own which files to read, this is not it, and the README says so explicitly rather than leaving it to inference.

How the provider layer and chat buffers actually work

Chats are markdown buffers. The README describes the loop: open one with :PrtChatNew, or toggle the last one with :PrtChatToggle, type your prompt after the user prefix given in the README, then press the trigger keymap, which the README gives as <C-g><C-g> in insert mode. Conversations are persisted as markdown files under Neovim's standard path or a location you choose, which means the transcript is a file you can read, diff or delete with ordinary tools.

Provider configuration is a single unified system. The README lists OpenAI, Anthropic, Google Gemini, xAI, ollama for local serving, and any custom OpenAI-compatible endpoint. It names Perplexity, Mistral, Groq, DeepSeek, GitHub Models, NVIDIA and EveryAPI as endpoints reachable through that same custom path. Credentials can come from environment variables, from bash commands, or from password manager CLIs with lazy evaluation, so a secret does not have to sit in your init.lua as a literal string. On top of that, a .parrot.md file supplies repository-specific instructions through the PrtContext command.

One consequence of the unified provider model is worth stating plainly: the quality of your setup depends on the endpoint you point at. The plugin is a client. It does not normalize model behaviour, and the README's provider block carries per-provider params such as temperature and top_p, which means tuning is your job.

Installing parrot.nvim and running a first rewrite

The README requires Neovim 0.10 or newer and plenary. ripgrep, fzf and telescope are listed as optional. With lazy.nvim, the README's snippet is short: the plugin plus two dependencies, with empty opts.

{
  "frankroeder/parrot.nvim",
  dependencies = { "ibhagwan/fzf-lua", "nvim-lua/plenary.nvim" },
  opts = {}
}

Empty opts will not give you a working provider. The README states that providers "must be explicitly set up to make them available," so the next step is a config function with at least one provider entry. The README's OpenAI example reads the key from the environment and sets the endpoint, per-mode params and a model list.

require("parrot").setup {
  providers = {
    openai = {
      name = "openai",
      api_key = os.getenv "OPENAI_API_KEY",
      endpoint = "https://api.openai.com/v1/chat/completions",
      params = {
        chat = { temperature = 1.1, top_p = 1 },
        command = { temperature = 1.1, top_p = 1 },
      },
      models = { "gpt-4o", "o4-mini", "gpt-4.1-nano" },
    },
  },
}

If you prefer not to use a plugin manager, the README also gives a native package install that clones into Neovim's pack directory.

git clone --depth=1 https://github.com/frankroeder/parrot.nvim.git \
  "${XDG_DATA_HOME:-$HOME/.local/share}"/nvim/site/pack/parrot/start/parrot.nvim

After restarting Neovim, the first real use is a chat: run :PrtChatNew, type a prompt after the user prefix shown in the README, and press <C-g><C-g> in insert mode. What you should see is the response arriving in the same markdown buffer. If nothing happens, the usual cause is a provider that was never configured, since the plugin does not ship a default one.

Where parrot.nvim stops, and when that is a problem

The absence of autocompletion is the clearest limitation. If your workflow depends on ghost-text suggestions appearing as you type, parrot.nvim will not provide them, and the README presents this as intentional: no autocompletion, no background analysis of your files. Every generation is something you ask for.

There is a second boundary. Because the plugin excludes agent behaviour, it will not read a file you did not put in front of it, will not run a command, and will not decide which part of a repository is relevant. The .parrot.md file via PrtContext adds repository-specific instructions to a request, but that is context you wrote, not context the plugin discovered.

The practical failure mode follows from the same design. A misconfigured provider produces no output rather than a helpful error path you can guess at, and the README does not document a fallback provider or an automatic retry. If you are choosing a tool for a team that wants low-friction completions, this one asks for more configuration up front than a completion plugin does.

How parrot.nvim differs from gp.nvim and from agent CLIs

The README states that a substantial part of the code is based on an early fork of Tibor Schmidt's gp.nvim. That shared lineage matters when you compare them: both put LLM interaction in Neovim buffers, and both are configured through Lua rather than a separate daemon. The fork point means parrot.nvim's identity is its provider layer and its stated exclusions, not the basic idea of chatting with a model from a buffer.

The sharper contrast is with agent CLIs such as codex, claude-code and gemini-cli, which the README names directly. Those tools take initiative: they explore a repository, choose files and apply edits. parrot.nvim sends what you selected, to the endpoint you configured, when you trigger it. You trade autonomy for a request you can predict. Whether that trade is good depends on whether you want the model to have repository-wide reach. For a one-off rewrite of a function, the manual model is cheaper to reason about. For a multi-file refactor, it is the wrong tool.

Maintenance, licence and the cost of keeping it current

The repository is not archived, and the last push was on 2026-08-24. The most recent release listed is v2.6.0 on 2026-07-21, following v2.5.1 on 2025-11-17 and v2.5.0 on 2025-10-05. A CHANGELOG.md sits at the repository root, so upgrade notes have a place to live; the README itself does not document a rollback procedure if a new release breaks your config.

The licence is reported as NOASSERTION, which means the repository's licence metadata could not be matched to a standard identifier. The LICENSE file is present at the root, so the terms are readable, but anyone embedding this in a larger distribution should read that file rather than rely on the identifier. This is a description of the repository state, not legal advice.

The ongoing cost is configuration drift. Model names appear literally in your provider block, and the README's examples name gpt-4o, o4-mini and gpt-4.1-nano. When an endpoint retires a model, your block is what needs editing. The Makefile shows the project's own checks: make test runs PlenaryBustedDirectory through tests/minimal_init.lua, make lint runs luacheck on lua/, and make format runs stylua with .stylua.toml. Those targets tell you what a contributor is expected to run before a change lands.

Editorial conclusion

Adopt parrot.nvim if you want LLM text generation inside Neovim buffers and you are willing to write a provider block yourself, because the plugin does nothing until at least one provider is configured. Do not adopt it if you expect inline autocompletion or an agent that reads and edits files on its own; the README states those are out of scope. Before committing, verify that your Neovim is 0.10 or newer, that plenary is installed, and that the model names in your provider block still exist at the endpoint you point at, since the README's examples name specific models such as gpt-4o and o4-mini.

Frequently asked questions

Official sources

1. frankroeder/parrot.nvim on GitHub
2. Issues
3. README
4. Releases