Skip to content

About

No description, website, or topics provided.

Resources

Stars

1 star

Watchers

1 watching

Forks

Latest commit

 

History

38 Commits

Folders and files

Repository files navigation

sage-llm.nvim

A plugin for interacting with LLMs in neovim.

Quick demo

Select code, run :SageAsk, and get an explanation without leaving Neovim.

SageAsk demo: select code and ask for an explanation in Neovim

Why?

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.

Features

  • 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

Requirements

  • Neovim >= 0.10
  • plenary.nvim
  • Hosted models: an OpenRouter API key, or an eligible ChatGPT subscription
  • ChatGPT sign-in: macOS/Linux, Neovim with LuaJIT, openssl on your PATH (for secure sign-in verification), and a browser

Installation

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,
}
use {
  "sage-llm/sage-llm.nvim",
  requires = { "nvim-lua/plenary.nvim" },
  config = function()
    require("sage-llm").setup()
  end,
}

Setup

1. Connect a Provider

Use your ChatGPT subscription

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.

  • :SageChatGPTStatus shows your connection and selected model.
  • :SageModel → ChatGPT subscription... refreshes your account's available models.
  • :SageChatGPTLogout removes 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,
  },
}

Use OpenRouter

  1. Sign up at OpenRouter
  2. Generate an API key
  3. On first run, sage-llm will auto-create ~/.config/sage-llm/config.lua
  4. Run :SageConfig to open the config file
  5. Set your API key:
return {
  api_key = "sk-or-v1-...",
}
  1. 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!)

2. Configure Keymaps (Optional)

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" })

Usage

Basic Workflow

  1. Select code in visual mode (v, V, or Ctrl-v)
  2. 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
  3. Read the response in the floating window (if you want, I'm not here to tell you what to do)
  4. Press q to hide, y to yank response, f to ask follow-up, S to toggle web search for the next query

Commands

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)

Ask a T3 Code thread

Use this when you edit in Neovim and want to continue a conversation in T3 Code:

  1. Run T3 Code on the same machine as Neovim, add your project, and open a thread.
  2. Highlight code in Neovim and run :SageT3Ask.
  3. Choose the destination thread, enter your question, and submit with <CR>.
  4. Watch the reply in Sage's response window. Press f to follow up in the same T3 thread, y to yank, or q to hide; :SageView reopens 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.

Input Window

When using :SageAsk:

  • Type your question - Multi-line supported
  • <CR> - Submit question
  • <S-CR> (Shift+Enter) - Insert newline
  • S (normal mode) - Toggle web search for the next query
  • r (normal mode) - Toggle RAG context on/off
  • q or <Esc> - Cancel

Response Window

  • q or <Esc> - Hide window (conversation stays available)
  • y - Yank response to clipboard
  • f - Ask a follow-up question
  • a - Apply pending inline edit
  • A - Apply pending inline edit and hide window
  • r - Reject pending inline edit
  • S - 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.

Configuration

Config File (Recommended)

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",
}

Setup Configuration (Optional)

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")]],
})

Dependency Detection

By default, dependency detection is off for performance. Enable it for better context:

:SageDepsOn

Supported languages :

  • Rust - Parses Cargo.toml
  • JavaScript/TypeScript - Parses package.json
  • Python - Parses pyproject.toml or requirements.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 Code Search

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 /embeddings API and your configured api_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)

Available Models

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():

  • :SageModel includes Add custom model... and Remove model... options so you can manage your picker list and persist changes to config.
  • :SageModelRemove jumps 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.

License

MIT

Credits

Built with:

About

No description, website, or topics provided.

Resources

Stars

1 star

Watchers

1 watching

Forks

Releases

Packages

Contributors

Languages