GitHub - sampsn/pair.nvim

Code with an AI agent while staying hands-on in Neovim.

Chat about your project, ask about selected code, or request a change exactly where you want it. Chat and editor actions share one agent session. Proposed code appears in your unsaved buffer for you to inspect, accept, or reject.

A note from the creator

I like coding with agents, but I missed being hands-on with the code. I noticed my knowledge of the codebase regressing. I built Pair to keep the conversation, research assistance, and code speed while giving me more control over what gets written and where.

Pair v0.1.0 is an alpha release. Some backends still need live testing.

Install

Requires Neovim 0.11+ and a signed-in agent CLI, or curl and a provider API key.

With lazy.nvim:

{
  "sampsn/pair.nvim",
  config = function()
    require("pair").setup()
  end,
}

Pair uses Codex by default. Install the codex CLI and sign in with codex login.

For other backends or a local checkout, see backend setup.

Use

Chat: Use normal Vim motions in the input. Enter adds a line in Insert mode and sends in Normal mode. Scroll up to read earlier output while a response streams. Use :PairCancel to stop a request.

Buffer requests: Ask, Change, and Insert open a small prompt window. Enter submits; Esc followed by q cancels. Ask answers appear beside the code. Changes appear in the unsaved buffer with Accept, Reject, and Diff controls. Saving accepts the visible code.

Context: Pair sends the current buffer, including unsaved edits, by default. In a Pair input, gC previews the attachment and gA toggles the full-buffer attachment.

Backends

Use :PairBackends to switch agents and :PairModel to choose a model. Each backend has its own conversation history.

Pair remembers your last backend and selected model for each backend across restarts and :PairNew. Set remember_selection = false to use your configured defaults at startup.

Other account and model combinations remain unverified. CLI access uses the agent's login; direct APIs use separately billed API keys. See setup instructions and tested versions and results.

OpenCode: If a free model says it only works inside OpenCode, connect a provider with opencode auth login, then choose its model with :PairModel. For example, :PairModel openrouter/openai/gpt-4.1-mini uses an OpenRouter key and its API billing.

Commands and writable folders

Antigravity can run tests and builds while source files stay read-only. To allow build output or generated code, create dedicated folders in your project:

mkdir -p build coverage generated

Then configure Pair:

require("pair").setup({
  backend = "antigravity",
  commands = { writable_paths = { "build", "coverage", "generated" } },
})

For example, ask “Run cmake -S . -B build && cmake --build build,” or “Run my client generator with output set to generated/.” Paths are relative to Neovim's working directory and must already exist. The agent can create, replace, or delete files in those folders directly; source edits elsewhere still require a proposal. Save your buffer before asking for tests. These grants currently apply to Antigravity only. See command setup for details.

Privacy and limits

Your prompt and attached code go to the selected provider. Pair keeps local history under stdpath('state')/pair; :PairNew preserves older conversations.

Agents inspect the project and return scoped proposals. Antigravity can also run commands and tests inside Pair's filesystem sandbox, with optional writable output folders. Codex uses its own read-only sandbox. See command setup and SECURITY.md.

Pair supports one active workspace and one pending proposal at a time. Editing the target buffer while a proposal is being generated invalidates it. Commands use saved files on disk; prompts use your visible buffer.

Help and contributing

Run :checkhealth pair for setup problems and :help pair for the full guide.

Report a bug · Contribute · Test a backend · Try the preview · Vision

MIT licensed.