A plugin for interacting with LLMs in neovim.
Select code, run :SageAsk, and get an explanation without leaving Neovim.
Suppose you have a simple question, want to understand a complier error or LSP diagnostic. Do you really want to open up a window and copy+paste into claude or chatgpt? You're using vim, of course you don't, you're allergic to the mouse. sage-llm.nvim lets you ask all these simple queries right from neovim. It is specifically intended for:
- Compiler errors
- Type errors and warnings
- Syntax issues in unfamiliar languages
- Code patterns you haven't seen before
- ANYTHING ELSE because fuck it, you're a dev.
Get concise explanations without leaving your editor.
- Ask about selected code - Highlight and ask questions
- LSP diagnostics - Automatically includes error codes and messages
- Dependency detection - Understands your project's dependencies (Rust, JS/TS, Python, Go)
- Optional RAG code search - Pulls semantically related snippets from your repo into
:SageAsk - Streaming responses - See answers as they generate
- Concise explanations - Focuses on the "why", not just the "fix"
- Multiple models - Switch between Claude, GPT, Gemini, Mercury, and more
- ChatGPT subscription - Sign in with ChatGPT and use your plan allowance without an API key
- T3 Code threads - Send context to an existing T3 thread and mirror its reply in Sage
- Neovim >= 0.10
- plenary.nvim
- Hosted models: an OpenRouter API key, or an eligible ChatGPT subscription
- ChatGPT sign-in: macOS/Linux, Neovim with LuaJIT,
opensslon your PATH (for secure sign-in verification), and a browser
Using lazy.nvim
{
"sage-llm/sage-llm.nvim",
dependencies = { "nvim-lua/plenary.nvim" },
config = function()
require("sage-llm").setup({
-- Optional: override defaults
-- model = "anthropic/claude-sonnet-4-20250514",
})
end,
}Using packer.nvim
use {
"sage-llm/sage-llm.nvim",
requires = { "nvim-lua/plenary.nvim" },
config = function()
require("sage-llm").setup()
end,
}Run :SageChatGPTLogin, continue with ChatGPT in your browser, and approve permission to use your plan. After sign-in, choose a model from your account's catalog. Sage selects the ChatGPT provider and saves your choice. Then use :SageAsk, :SageExplain, :SageFix, follow-ups, and :SageInfill as usual.
This uses OpenAI's public Sign in with ChatGPT flow and Responses API. Availability and usage are subject to your account, workspace, and plan limits; manage the app's allowance in ChatGPT Settings → Usage. Sage does not fall back to paid API requests when subscription usage fails. Model refusals show the explanation as a declined request; infill does not offer refused output as replacement code.
:SageChatGPTStatusshows your connection and selected model.:SageModel→ ChatGPT subscription... refreshes your account's available models.:SageChatGPTLogoutremoves saved tokens and attempts to revoke the renewable session.:SageChatGPTLogin!connects another account or workspace. Sage keeps one active connection; an unsuccessful sign-in preserves the previous connection.
If an authorization code is rejected, repeat the sign-in command shown in the error. Sage retains the issued client ID as pending registration metadata and starts a fresh OAuth attempt. An interrupted new-account registration resumes with :SageChatGPTLogin!; ordinary sign-in still uses the existing active account.
If plan usage was declined, repeat sign-in to approve it. Sage requests consent on that explicit retry; routine sign-in with an approved grant does not force another consent screen.
No Codex CLI or OpenAI API key is needed. ChatGPT sign-in currently supports macOS/Linux and requires openssl on your PATH. On macOS, if it is missing, install it with brew install openssl and add its bin directory to your PATH.
OS-managed advisory locks serialize credential updates and release automatically on process exit. Recovery removes abandoned OAuth request files under the lock; logout also removes abandoned credential copies. ChatGPT sign-in requires a LuaJIT build of Neovim.
Inference headers and prompt/history files also use private storage under the ChatGPT data directory. Each request holds an OS-owned lifetime lock. Startup, new requests, and logout remove dead editors' files while preserving other editors' active requests.
Credentials are stored separately from your Lua configuration in stdpath("data")/sage-llm/chatgpt, using owner-only permissions and atomic writes. Access tokens refresh automatically. Browser sign-in uses PKCE and validates the returned identity; credentials are never read from other apps. Do not commit or share this directory. Subscription requests send the prompt and conversation history with store = false; Sage supplies no tools. Repository embeddings/RAG and the OpenRouter web-search toggle are unavailable with this provider.
Optional settings in :SageConfig (config-file values take priority over setup()):
return {
provider = "chatgpt",
chatgpt = {
-- model = "...", -- Account catalog slug; :SageModel saves this for you
-- auth_dir = "/private/path/sage-chatgpt", -- Optional credential directory
login_timeout_ms = 180000,
request_timeout_ms = 30000,
},
}- Sign up at OpenRouter
- Generate an API key
- On first run, sage-llm will auto-create
~/.config/sage-llm/config.lua - Run
:SageConfigto open the config file - Set your API key:
return {
api_key = "sk-or-v1-...",
}- Restart Neovim (or re-source your config)
Alternative methods (less recommended):
- Environment variable:
export OPENROUTER_API_KEY="sk-or-v1-..." - In setup():
require("sage-llm").setup({ api_key = "..." })(don't commit this to public repos!)
The plugin doesn't set default keymaps. Add your own:
-- In your Neovim config
vim.keymap.set("v", "<leader>sa", ":SageAsk<CR>", { desc = "Ask LLM about selection" })
vim.keymap.set("n", "<leader>sa", ":SageAsk<CR>", { desc = "Ask LLM (no selection)" })
vim.keymap.set("v", "<leader>se", ":SageExplain<CR>", { desc = "Explain selection" })
vim.keymap.set("v", "<leader>sx", ":SageFix<CR>", { desc = "Fix diagnostics" })
vim.keymap.set("v", "<leader>sk", ":SageInfill<CR>", { desc = "Inline edit selection" })
vim.keymap.set("n", "<leader>sm", ":SageModel<CR>", { desc = "Select model" })- Select code in visual mode (v, V, or Ctrl-v)
- Run a command:
:SageAsk- Opens input buffer for your question:SageExplain- Explains the code immediately:SageFix- Explains how to fix diagnostics:SageInfill- Generates inline replacement for selected code
- Read the response in the floating window (if you want, I'm not here to tell you what to do)
- Press
qto hide,yto yank response,fto ask follow-up,Sto toggle web search for the next query
| Command | Description |
|---|---|
:SageAsk |
Open input buffer to ask about visual selection |
:SageT3Ask |
Ask an existing T3 Code thread about the selection |
:SageT3Thread |
Choose a different destination thread for this working directory |
:SageExplain |
Explain what the selected code does |
:SageFix |
Explain how to fix errors/warnings in selection |
:SageInfill |
Generate and preview inline replacement for selection |
:SageView |
Reopen latest hidden response window |
:SageModel |
Open model picker to switch LLMs |
:SageModelRemove |
Open model picker to remove a model |
:SageConfig |
Open config file for editing |
:SageChatGPTLogin[!] |
Sign in with ChatGPT; ! connects another account/workspace |
:SageChatGPTLogout |
Clear saved ChatGPT tokens and revoke the session |
:SageChatGPTStatus |
Show ChatGPT connection status |
:SageDepsOn |
Enable dependency detection (slower, more context) |
:SageDepsOff |
Disable dependency detection (default) |
Use this when you edit in Neovim and want to continue a conversation in T3 Code:
- Run T3 Code on the same machine as Neovim, add your project, and open a thread.
- Highlight code in Neovim and run
:SageT3Ask. - Choose the destination thread, enter your question, and submit with
<CR>. - Watch the reply in Sage's response window. Press
fto follow up in the same T3 thread,yto yank, orqto hide;:SageViewreopens the saved response.
Sage remembers your choice for the current Neovim session and working directory.
Use :SageT3Thread to change it. The picker shows open, unsettled threads in the
matching T3 project, with titles, status and IDs; it does not automatically select
the thread focused in the T3 window. A busy thread gets the message as its next turn.
Sage mirrors incremental reply snapshots as T3 publishes them, then replaces the
preview with the final answer for your submitted turn. The CLI supplies snapshots
rather than token events, so updates arrive on a short polling interval. Other
messages in the thread are excluded. The conversation also remains available in T3.
q, <Esc> and <C-c> stop Sage's local reply reader; the remote T3 turn keeps
running. Reopening with :SageView shows the saved text. Approvals and questions
from the agent must be answered in T3 Code; when the CLI reports that it needs
input, Sage stops its reader and displays that status. Changing :SageT3Thread affects new
selection questions; f continues the thread displayed in the response window.
The message includes the working directory, absolute source path and selected line
range, filetype, extracted text (including unsaved edits), and LSP diagnostics in
that range. Dependency context follows :SageDepsOn / :SageDepsOff. Context is
captured before the picker/input opens. T3 uses the destination thread's existing
model, instructions and permissions. This command does not require a Sage API key
or change the provider used by :SageAsk.
Requires T3 Code v0.1.2 or newer, with t3 thread list, send --wait, and show.
Check t3 --help for the thread subcommand; older desktop builds may include a
t3 launcher without these commands and need an update. This integration uses
T3's documented host scripting interface.
If t3 is not on your PATH, Sage also checks ~/.t3/bin/t3.
Optional configuration in setup() (also accepted in the Sage config file):
require("sage-llm").setup({
t3 = {
command = "t3", -- Executable path; no shell arguments
-- base_dir = "~/.t3", -- Custom T3 data directory; otherwise honors T3CODE_HOME
-- project = "id", -- T3 project ID or path; defaults to Neovim's cwd
timeout_ms = 15000, -- Timeout for each listing/snapshot read
response_timeout_ms = 600000, -- Maximum wait for a queued/running reply
poll_interval_ms = 500, -- Delay between reply snapshot reads
},
})
vim.keymap.set("v", "<leader>st", ":SageT3Ask<CR>", { desc = "Ask T3 about selection" })
vim.keymap.set("n", "<leader>sT", ":SageT3Thread<CR>", { desc = "Select T3 thread" })The Lua API is require("sage-llm").t3_ask() and
require("sage-llm").t3_select_thread(). Sage invokes the CLI asynchronously and
sends context through stdin. If the reply cannot be confirmed, inspect the thread
before retrying because the message may already have arrived and may still be running.
When using :SageAsk:
- Type your question - Multi-line supported
<CR>- Submit question<S-CR>(Shift+Enter) - Insert newlineS(normal mode) - Toggle web search for the next queryr(normal mode) - Toggle RAG context on/offqor<Esc>- Cancel
qor<Esc>- Hide window (conversation stays available)y- Yank response to clipboardf- Ask a follow-up questiona- Apply pending inline editA- Apply pending inline edit and hide windowr- Reject pending inline editS- Toggle web search for the next query<C-c>- Cancel streaming (if in progress)
Web search is off by default. When enabled, the plugin sends :online model variants to OpenRouter (for example, google/gemini-3.8-flash:online). The toggle resets to off after each query.
Edit ~/.config/sage-llm/config.lua (or run :SageConfig):
return {
-- Your OpenRouter API key (required)
api_key = "sk-or-v1-...",
-- Model to use (optional, selected model is auto-saved here)
model = "google/gemini-3.8-flash",
}You can override UI settings and prompts in your Neovim config:
require("sage-llm").setup({
-- API settings (config file takes precedence)
api_key = nil, -- Falls back to config file, then $OPENROUTER_API_KEY
model = "openai/gpt-oss-20b",
base_url = "https://openrouter.ai/api/v1",
-- Response window (floating window on right side)
response = {
width = 0.6, -- 60% of editor width
height = 0.4, -- 40% of editor height
border = "rounded",
},
-- Input window (centered)
input = {
width = 0.5,
height = 5, -- Lines
border = "rounded",
prompt = "Ask about this code: ",
infill_prompt = "Describe the edit:",
},
-- Dependency detection (opt-in for performance)
detect_dependencies = false,
-- RAG code search for :SageAsk (opt-in)
rag = {
enabled = false,
embedding_model = "openai/text-embedding-3-small",
top_k = 6,
chunk_lines = 80,
chunk_overlap = 20,
max_context_chars = 6000,
},
-- Default picker models (OpenRouter IDs verified 2026-09-10)
models = {
-- Budget choices for everyday questions and edits
"openai/gpt-oss-20b",
"inception/mercury-2.5",
"inception/mercury-2",
"google/gemini-3.8-flash",
"openai/gpt-5.6-luna",
"qwen/qwen3.8-flash",
"deepseek/deepseek-v4.1-flash",
-- More capable coding option at a moderate price
"anthropic/claude-sonnet-5",
-- Flagships for difficult questions
"openai/gpt-6-astra",
"anthropic/claude-fable-5.1",
},
-- System prompt (tuned for concise teaching)
system_prompt = [[You are a concise coding tutor helping a developer understand code.
Rules:
- Be brief and direct
- Use `inline code` for short references rather than full code blocks
- Only show multi-line code blocks when essential for understanding
- When explaining errors, focus on the "why" not just the fix
- Reference language concepts by name (e.g., "ownership", "borrow checker", "lifetime")]],
})By default, dependency detection is off for performance. Enable it for better context:
:SageDepsOnSupported languages :
- Rust - Parses
Cargo.toml - JavaScript/TypeScript - Parses
package.json - Python - Parses
pyproject.tomlorrequirements.txt - Go - Parses
go.mod
The detected dependencies are included in the prompt so the LLM understands your project's context (e.g., "using tokio for async" or "using React hooks").
RAG is off by default. When enabled, :SageAsk retrieves semantically similar snippets from your repository and includes them in the prompt as extra context.
Toggle it from the :SageAsk input window with r (normal mode). The current state is shown in the input title ([RAG: on/off]).
Or set the default in config:
return {
rag = {
enabled = true,
embedding_model = "openai/text-embedding-3-small",
},
}Notes:
- RAG uses OpenRouter's
/embeddingsAPI and your configuredapi_key - The index is cached under
stdpath("cache") .. "/sage-llm/rag" - Larger repositories may take longer on the first ask with RAG enabled while index chunks are embedded
- Retrieved snippets are sent to the model as additional prompt context (review for privacy-sensitive repos)
Default: openai/gpt-oss-20b (an inexpensive starting point).
The built-in picker balances everyday coding help with two flagships for harder problems. All ten IDs were checked against OpenRouter's live model catalog and their provider endpoints on 2026-09-10: each accepts text, returns text, has an active endpoint, and has no announced expiration in the catalog.
Prices below are the catalog's USD rates per 1 million tokens, before caching or additional services. They are a dated comparison, not fixed prices; provider routing, promotions, and long-context or time-of-day rates can change the bill. Context is the catalog maximum and can vary by provider.
| Model / OpenRouter ID | Why it is included | Input / output | Context |
|---|---|---|---|
GPT-OSS-20B — openai/gpt-oss-20b |
Existing low-cost default for short explanations | $0.03 / $0.13 | 131K |
Mercury 2.5 — inception/mercury-2.5 |
Newer diffusion model for responsive coding help | $0.04 / $0.15 (promotion) | 260K |
Mercury 2 — inception/mercury-2 |
Fast diffusion alternative for interactive questions | $0.25 / $0.75 | 128K |
Gemini 3.8 Flash — google/gemini-3.8-flash |
Latest Gemini Flash, with improved coding and reasoning | $0.75 / $3.75 (promotion) | 1.05M |
GPT-5.6 Luna — openai/gpt-5.6-luna |
Fast, inexpensive GPT option | $0.20 / $1.20 | 1.05M |
Qwen3.8 Flash — qwen/qwen3.8-flash |
Low-cost coding and codebase analysis | $0.15 / $0.47 | 1M |
DeepSeek V4.1 Flash — deepseek/deepseek-v4.1-flash |
Latest DeepSeek Flash with inexpensive reasoning | $0.15 / $0.60 (off-peak) | 1.05M |
Claude Sonnet 5 — anthropic/claude-sonnet-5 |
Strong coding option below flagship pricing | $2 / $10 | 1M |
GPT-6 Astra — openai/gpt-6-astra |
OpenAI flagship for demanding software engineering | $10 / $50 | 1.05M |
Claude Fable 5.1 — anthropic/claude-fable-5.1 |
Anthropic flagship for complex coding and reasoning | $10 / $50 | 1M |
Mercury 2.5's listed price includes an 80% discount (undiscounted: $0.20 / $0.75); Gemini 3.8 Flash includes 50% off (undiscounted: $1.50 / $7.50). DeepSeek's direct endpoint also has peak rates of $0.30 / $1.20. GPT-5.6 Luna and GPT-6 Astra have higher rates above 272K input tokens. Check the linked provider listings for current terms.
For interactive use, start with Mercury 2/2.5 or Gemini 3.8 Flash; choose Qwen or DeepSeek when output cost matters most, or a flagship for a difficult explanation. These are selection guidelines based on the model descriptions, pricing, and OpenRouter's reported latency/throughput, not plugin-specific benchmarks. Actual speed depends on the provider, load, and reasoning effort. The list uses regular text-generation IDs rather than batch, image-generation, or free variants.
Switch models with :SageModel or configure in setup():
:SageModelincludesAdd custom model...andRemove model...options so you can manage your picker list and persist changes to config.:SageModelRemovejumps directly to the remove-model picker.
A models list saved by the picker in :SageConfig takes precedence over these defaults, as does a list supplied to setup(). To adopt the new defaults, remove those models overrides and restart Neovim, or copy the desired new IDs into your existing list to retain custom entries. Your saved model selection still takes precedence over the startup default.
See OpenRouter pricing for cost comparison.
MIT
Built with:
- plenary.nvim - HTTP client
- OpenRouter - LLM API gateway
