pair-programmer.nvim

An opinionated, agent-agnostic pair-programming interface for Neovim. Launch any AI coding CLI (opencode, Claude Code, aider, Codex, etc.) in a floating terminal with a read-only system prompt.

Philosophy

pair-programmer.nvim is deliberately simple. It does one thing: pipe your editor context (file path, selection, diagnostics) into an AI terminal. It doesn't manage API keys, choose models, or implement agent protocols. That's the agent's job.

The plugin ships with a read-only pair-programming system prompt that keeps the agent in "explain, don't implement" mode. You bring your own agent CLI — the plugin just launches it with that prompt and gets out of the way.

Requirements

• An AI coding CLI — opencode, Claude Code, aider, Codex, or any CLI agent that accepts prompts via arguments or stdin
• snacks.nvim — for the floating terminal

Installation

lazy.nvim

{
  "kapilratnani/pair-programmer.nvim",
  lazy = false,
  config = function()
    require("pair_programmer").setup()
  end,
  keys = {
    { "<leader>aa", function() require("pair_programmer.terminal").toggle() end, desc = "Toggle AI" },
    { "<leader>af", function() require("pair_programmer.terminal").focus()  end, desc = "Focus AI" },
    { "<leader>ac", function() require("pair_programmer.context").current_file()  end, desc = "Review current file" },
    { "<leader>av", function() require("pair_programmer.context").selection()     end, desc = "Send selection" },
    { "<leader>ad", function() require("pair_programmer.context").diagnostics()   end, desc = "Send diagnostics" },
    { "<leader>aq", function() require("pair_programmer.context").ask_question()  end, desc = "Ask ad-hoc question" },
  },
}

Keymaps

Key	Action
<leader>aa	Toggle AI terminal
<leader>af	Focus AI terminal
<leader>ac	Send current file path to AI
<leader>av	Send visually-selected text to AI
<leader>ad	Send buffer diagnostics to AI
<leader>aq	Prompt for an ad-hoc question

System Prompt

The plugin ships with a read-only pair-programming system prompt embedded in its default config. This prompt tells the agent to explain, review, and debug — never to write files or generate code unless explicitly asked.

You can override it in setup():

require("pair_programmer").setup({
  initial_prompt = "Your custom system prompt here",
})

For opencode users who prefer the skill-file approach, a skill file is also included:

ln -s ~/projects/pair-programmer.nvim/skill ~/.agents/skills/pair-programmer

Configuration

Option	Default	Description
command	"opencode"	CLI agent binary
args	{"--prompt", "{initial_prompt}"}	CLI arguments; {initial_prompt} is replaced with the prompt text
initial_prompt	(pair-programmer persona)	System prompt sent to the agent
sidebar.width	45	Terminal window width in columns

Agent examples

opencode (default):

require("pair_programmer").setup({
  command = "opencode",
  args = { "--prompt", "{initial_prompt}" },
})

Claude Code:

require("pair_programmer").setup({
  command = "claude",
  args = { "{initial_prompt}" },
})

aider:

require("pair_programmer").setup({
  command = "aider",
  args = { "--message", "{initial_prompt}" },
})

Codex:

require("pair_programmer").setup({
  command = "codex",
  args = { "{initial_prompt}" },
})

The {initial_prompt} placeholder is replaced with the value of initial_prompt at launch time. This lets any CLI agent receive the pair-programming system prompt.

License

MIT