parrot.nvim 🦜

This is parrot.nvim, the ultimate stochastic parrot to support your text editing inside Neovim.

Features • Demo • Getting Started • Commands • Configuration • Roadmap • FAQ

Features

parrot.nvim offers a seamless out-of-the-box experience, providing tight integration of current LLM APIs into your Neovim workflows, with a focus solely on text generation. The selected core features include on-demand text completion and editing, as well as chat-like sessions within native Neovim buffers.

This plugin is intended for people who actually know what they are doing and people who care for privacy and transparency. The user is always under full control of what will be sent to the LLM API endpoint, hence this plugin fully excludes the whole notion of agents provided by tools such as codex, claude-code, and the gemini-cli.

A substantial part of the code is based on an early fork of the brilliant work by Tibor Schmidt's gp.nvim.

Persistent conversations stored as markdown files within Neovim's standard path or a user-defined location
Custom hooks for inline text editing based on user instructions and chats with predefined system prompts
Unified provider system supporting any OpenAI-compatible API:
- OpenAI API
- Anthropic API
- Google Gemini API
- xAI API
- Local and offline serving via ollama
- Any custom OpenAI-compatible endpoint with configurable functions; also supports Perplexity.ai API, Mistral API, Groq API, DeepSeek API, GitHub Models, and NVIDIA API
Flexible API credential management from various sources:
- Environment variables
- Bash commands
- Password manager CLIs (lazy evaluation)
Repository-specific instructions via .parrot.md file using the PrtContext command
No autocompletion and no hidden requests in the background to analyze your files

Demo

Seamlessly switch between providers and models.

<div align="left"> <p>https://github.com/user-attachments/assets/0df0348f-85c0-4a2d-ba1f-ede2738c6d02</p> </div>

Trigger code completions based on comments.

<div align="left"> <p>https://github.com/user-attachments/assets/197f99ac-9854-4fe9-bddb-394c1b64f6b6</p> </div>

Let the parrot fix your bugs.

<div align="left"> <p>https://github.com/user-attachments/assets/d3a0b261-a9dd-45e6-b508-dc5280594b06</p> </div>

<details> <summary>Rewrite a visual selection with `PrtRewrite`.</summary> <div align="left"> <p>https://github.com/user-attachments/assets/c3d38702-7558-4e9e-96a3-c43312a543d0</p> </div> </details>

<details> <summary>Append code with the visual selection as context with `PrtAppend`.</summary> <div align="left"> <p>https://github.com/user-attachments/assets/80af02fa-cd88-4023-8a55-f2d3c0a2f28e</p> </div> </details>

<details> <summary>Add comments to a function with `PrtPrepend`.</summary> <div align="left"> <p>https://github.com/user-attachments/assets/9a6bfe66-4bc7-4b63-8694-67bf9c23c064</p> </div> </details>

<details> <summary>Retry your latest rewrite, append or prepend with `PrtRetry`.</summary> <div align="left"> <p>https://github.com/user-attachments/assets/03442f34-687b-482e-b7f1-7812f70739cc</p> </div> </details>

Getting Started

Dependencies

This plugin requires the latest version of Neovim and relies on a carefully selected set of established plugins.

neovim 0.10+
plenary
ripgrep (optional)
fzf (optional, requires ripgrep)
telescope (optional)

Installation

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

</details> <details> <summary>Packer</summary>

require("packer").startup(function()
  use({
    "frankroeder/parrot.nvim",
    requires = { 'ibhagwan/fzf-lua', 'nvim-lua/plenary.nvim'},
    config = function()
      require("parrot").setup()
    end,
  })
end)

</details> <details> <summary>Neovim native package</summary>

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

</details>

Setup

The minimal requirement is to at least set up one provider, such as the one provided below or one from the provider configuration examples.

{
  "frankroeder/parrot.nvim",
  dependencies = { 'ibhagwan/fzf-lua', 'nvim-lua/plenary.nvim' },
  -- optionally include "folke/noice.nvim" or "rcarriga/nvim-notify" for beautiful notifications
  config = function()
    require("parrot").setup {
      -- Providers must be explicitly set up to make them available.
      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 },
          },
          topic = {
            model = "gpt-4.1-nano",
            params = { max_completion_tokens = 64 },
          },
          models ={
            "gpt-4o",
            "o4-mini",
            "gpt-4.1-nano",
          }
        },
      },
    }
  end,
}

Usage

Chat Basics

Chats in parrot.nvim are essentially standard Markdown buffers.

How it works:

Open a Chat: Use :PrtChatNew to open a fresh chat buffer (or :PrtChatToggle to toggle the last one).
Type your prompt: Just write your question or instruction in the buffer after the user prefix 🗨:.
Trigger the LLM: Press the trigger keymap (default <C-g><C-g> in insert mode) or use the :PrtChatRespond command.
Receive Response: The LLM streams its response directly into the buffer at your cursor position.
Stop Generation: Press <C-g>s to stop the generation at any time.

Key Concepts:

Context: The entire buffer content is sent as context (unless hidden comments are used).
System Prompts: You can set unique system prompts per chat or globally.
Persistence: Chats are saved as .md files in your configured directory.

Command Mode (Interactive Commands)

Command mode allows you to interact with LLMs directly on your code without leaving your current buffer.

Available Commands:

:PrtRewrite – Rewrite the visual selection based on your prompt.
:PrtAppend – Append generated text after the selection.
:PrtPrepend – Prepend generated text before the selection.
:PrtRetry – Retry the last rewrite/append/prepend operation.
:PrtEdit – Edit and re-run the last command with a modified prompt.

Workflow:

Select the code you want to modify (visual mode).
Run one of the commands above (e.g., :PrtRewrite fix the bug).
The LLM processes your selection and streams the result or presents you with a diff view.

Separate Model Selection: parrot.nvim maintains two independent model selections:

Chat Model: Used for chat buffers. Change it from within a chat buffer using :PrtModel.
Command Model: Used for interactive commands (PrtRewrite, etc.). Change it from any non-chat buffer using :PrtModel.

This allows you to use a fast/cheap model for quick inline edits while keeping a more capable model for in-depth chat conversations.

Commands

Below are the available commands that can be configured as keybindings. These commands are included in the default setup. Additional useful commands are implemented through hooks (see below).

General

| Command | Description | | ------------------------- | ----------------------------------------------| | PrtChatNew <target> | Open a new chat | | PrtChatToggle <target> | Toggle chat (open last chat or new one) | | PrtChatPaste <target> | Paste visual selection into the latest chat | | PrtInfo | Print plugin config | | PrtContext <target> | Edits the local context file | | PrtChatFinder | Fuzzy search chat files using fzf | | PrtChatDelete | Delete the current chat file | | PrtChatRespond | Trigger chat respond (in chat file) | | PrtStop | Interrupt any ongoing Parrot generation (works everywhere) | | PrtProvider <provider> | Switch the provider (empty arg triggers fzf) | | PrtModel <model> | Switch the interactive command model (empty arg triggers fzf). Note: Chat model must be changed from within the chat buffer. | | PrtStatus | Prints current provider and model selection | | `PrtR

Parrot.nvim

Install / Use

README