pilot.nvim

Minimalist AI plugin for Neovim using OpenRouter.

Ask questions about your code without leaving the editor. Select a snippet, type a question inline, or ask about the entire file — get instant answers in a floating tooltip that follows your cursor. Continue the conversation with follow-ups, all without breaking your flow.

╭─────────────────────────────────────────────────────────╮
│                      PILOT.NVIM                        │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  <space>?  LOOKUP - Ask AI (tooltip)                   │
│            Mode 1: code // ? your question             │
│            Mode 2: select code + <space>?              │
│                                                         │
│  <space>a  ASK - Ask about entire file                 │
│                                                         │
├─────────────────────────────────────────────────────────┤
│  :PilotContext N  - Set context lines (default 15)     │
│  <leader>f or [f] - follow-up (continue conversation)  │
│  [q] close tooltip                                     │
╰─────────────────────────────────────────────────────────╯

Features

• Inline lookup - write // ? question in line and trigger
• Visual lookup - select code and ask
• File lookup - ask about the entire file
• Follow-up - continue conversation in same context
• Floating tooltip - follows cursor as you navigate
• Multi-language - supports // ?, # ? and -- ?

Requirements

• Neovim 0.9+
• curl
• OpenRouter API key

Installation

git clone https://github.com/CairoAC/pilot.nvim ~/.config/nvim/lua/pilot

Add to your init.lua:

vim.g.mapleader = " "  -- must come before keymaps

local pilot = require("pilot")
pilot.setup()

vim.keymap.set("n", "<leader>?", pilot.lookup)
vim.keymap.set("x", "<leader>?", ":<C-u>lua require('pilot').lookup({ visual = true })<CR>")
vim.keymap.set("n", "<leader>a", pilot.ask)

Note: If you already have mapleader set elsewhere, skip that line. The leader key must be defined before the keymaps.

API Key

The key is automatically searched in this order:

1. $PWD/.env
2. ~/.env
3. ~/.config/pilot/.env
4. Environment variable OPENROUTER_API_KEY

.env format:

OPENROUTER_API_KEY=sk-or-v1-...

Configuration

pilot.setup({
    api_key = nil,                            -- uses .env by default
    model = "google/gemini-3-flash-preview",  -- default model
    base_url = "https://openrouter.ai/api/v1",
    context_lines = 15,
})

Usage

Keymaps

Key	Mode	Action
<space>?	Normal	Inline lookup (// ? question in line)
<space>?	Visual	Lookup with selection
<space>a	Normal	Ask about entire file
<leader>f	Normal	Follow-up (from original buffer)
f	Tooltip	Follow-up
q	Tooltip	Close

Inline syntax

const x = 1 // ? what does this do?

x = 1  # ? explain this variable

local x = 1 -- ? what is this for?

Commands

Command	Description
:PilotHelp	Show help
:PilotContext N	Set context lines

Structure

pilot/
├── init.lua              # setup and public API
├── openrouter.lua        # HTTP client (async curl)
├── actions/
│   └── lookup.lua        # lookup logic
└── ui/
    └── float.lua         # floating tooltip

How it works

1. You ask a question (inline, visual or file)
2. Plugin sends the entire file as context + your question
3. Response appears in a floating tooltip
4. You can continue the conversation with follow-up (f or <leader>f)
5. Tooltip follows your cursor as you navigate

License

MIT