doc/ai.txt — rendered from the plugin's own vimdoc
*ai.txt* Provider-agnostic ask/stream layer for talking to an AI *ai.nvim*
CONTENTS
1. Introduction ........................ |ai-intro| 2. Requirements ........................ |ai-requirements| 3. Setup ............................... |ai-setup| 4. Configuration ....................... |ai-config| 5. Commands ............................ |ai-commands| 6. Bindings ............................ |ai-bindings| 7. Completion ........................... |ai-completion| 8. Lua API ............................. |ai-api| 9. Providers ............................ |ai-providers| 10. Attachments .......................... |ai-attachments| 11. Context .............................. |ai-context| 12. Scope ................................ |ai-scope| 13. Usage reporting ...................... |ai-usage| 14. Health check ........................ |ai-health|
1. INTRODUCTION
ai.nvim is a provider-agnostic ask/stream layer for talking to an AI from inside Neovim -- context assembly (buffer/selection/diagnostics), a streaming answer panel, and an:Aicomposer command, built onlib.nvim.net.curl(SSE/NDJSON streaming, secrets kept out of curl's argv). It pairs well with pdfport.nvim: itsclaude/ollamaextraction backends send their PDFs and page images through this plugin'sask()instead of carrying a second hand-written curl/provider path of their own. That migration is what |ai-attachments| were built for.
2. REQUIREMENTS
- Neovim >= 0.11 (lib.nvimcalls the positionalvim.validate; on 0.10vim.systemstarts a child withclear_envwithout any environment). - lib.nvim (github.com/WKDSteve/lib.nvim) -- hard dependency.fetch_stream/secret_headersonlib.nvim.net.curlmust be present; a too-old checkout is flagged by|:checkhealth|ai. - ui.nvim (github.com/WKDSteve/ui.nvim) -- also a hard dependency:ui.kitbacks the streaming answer panel, the explain badge, the non-streaming viewer and the prompt popup. All lazy-loaded (no cost until an:Aiaction actually runs), but none of them has another rendering path. Inline completion (|ai-completion|) is the one exception: it renders through raw extmarks, so it still works without ui.nvim. -curlonPATH-- every provider shells out to it. - At least one provider actually usable: - claude:ANTHROPIC_API_KEYset in the environment. - openai:OPENAI_API_KEYset in the environment. For an OpenAI-compatible endpoint (LM Studio, vLLM, a gateway) setAI_OPENAI_BASE_URL(https, or http for localhost only). The OpenAI key is never sent there: it getsAI_OPENAI_COMPAT_API_KEY, or no key. Without a key, "auto" does not pick it; chooseopenaiexplicitly. - gemini:GEMINI_API_KEYset in the environment. - ollama: theollamabinary onPATH, with the daemon running (default http://127.0.0.1:11434, override withAI_OLLAMA_HOST-- deliberately notOLLAMA_HOST, which is Ollama's own env var for the *server*'s bind address). Every request asks for a context window ofollama.num_ctx(32768): Ollama's own default can be as low as 4096 and then silently drops the beginning of a longer prompt. A prompt that likely does not fit is warned about before it is sent. - ai_desktop: an ai-desktop server reachable at http://127.0.0.1:8080 (default, override withAI_DESKTOP_HOST; the old nameLOOMAI_HOSTstill works, and so does the provider idloomai). Last in the defaultprovider_order-- see |ai-scope|. - claude-cli: the Claude Code CLI (claude) onPATH, logged in (claude auth status). Opt-in: not in the defaultprovider_order, select it with:Ai provider claude-cli. Uses whatever account the CLI is logged in as; needs no API key of its own, and the variables that would override that login are not passed on to it (see |ai-providers|).ANTHROPIC_BASE_URLis passed on (a company gateway may be the only way to reach the API): the CLI then sends its login and your prompts to that host, whichpolicy.alloweddoes not see.:Ai infoand|:checkhealth|ai name the host while it is set. A known limit: a credential in the CLI's own settings (anapiKeyHelper, an API key or token in itsenvblock, an active federation profile) ranks above its login and is not environment of the child, so it is not removed -- see |ai-scope|.|:checkhealth|ai warns when the user's settings file (settings.jsoninCLAUDE_CONFIG_DIRwhen that is set, else in~/.claude) or the managed settings file defines anapiKeyHelperor sets such a key or token in itsenvblock; it only looks whether the keys exist. A federation profile is not detected. - copilot: the GitHub Copilot CLI (copilot) onPATH, logged in (copilot login; the login lives in the system credential store). Opt-in: not in the defaultprovider_order, select it with:Ai provider copilot. Uses whatever account the CLI is logged in as; needs no token of its own, andCOPILOT_GITHUB_TOKEN,GH_TOKENandGITHUB_TOKEN(which outrank that login, and of which a classicghp_one is refused by the CLI) are not passed on to it, nor is anything that would send the request to another endpoint or export its text (a bring-your-own-model setting, the offline switch, extra instruction directories, OpenTelemetry); the list is in docs/requirements.md.|:checkhealth|ai names the token variables that are set. The login cannot be checked without a model call (which uses credit), so a missing login or used-up credit is reported by the first request. No provider is required at install time --|:checkhealth|ai reports which ones are usable on this machine, andprovider = "auto"(the default) picks the first available one inprovider_order. On a machine where none of them is available (for example a managed work machine without the local ai-desktop server), ai.nvim stays loaded and reports that no provider is available (|:Ai-info| shows `auto (-> none available)`); nothing is sent anywhere. Optional soft dependencies (loaded viapcall(require, ...); absent, the matching |ai-context| flag is a silent no-op): - data.nvim -- backscontext.structured_data. - gitsuite.nvim -- backscontext.conflict.
3. SETUP
With lazy.nvim:
{
"WKDSteve/ai.nvim",
dependencies = { "WKDSteve/lib.nvim", "WKDSteve/ui.nvim" },
cmd = "Ai",
keys = { { "<leader>a", mode = { "n", "v" } } },
config = function()
require("ai").setup()
end,
}
Manual:
require("ai").setup()
cmd/keysare lazy-load triggers -- ai.nvim does nothing until:Aiis run or one of the default<leader>a*keymaps is pressed.
4. CONFIGURATION
Pass a table to |ai.setup()|. All keys are optional; `lua/ai/config/ DEFAULTS.lua` is the source of truth.
require("ai").setup({
provider = "auto", -- "auto"|"claude"|"ollama"|"openai"|"gemini"|"ai_desktop"|"claude-cli"|"copilot"|custom id
provider_order = { "claude", "ollama", "openai", "gemini", "ai_desktop" }, -- "auto" resolution order
policy = {
allowed = {}, -- provider ids this machine may use; empty = no restriction
},
keys = {}, -- named API-key profiles per provider; empty = each provider's own variable
model = {}, -- e.g. { claude = "claude-opus-4-5" }
agents = {}, -- named presets { name = { provider, model, system } }, see |:Ai-agent|
agent = false, -- the agent active at startup, a name from agents; false = none
repo_prompt = {
file = ".ai.md", -- the repository's prompt file, relative to the project root, see |:Ai-trust|
max_bytes = 16384, -- a larger file is refused, not cut
},
timeout_ms = 60000,
bulk = {
max_session_chars = false, -- cap on the characters of all bulk requests of a session; false = none
},
usage = {
report = false, -- report request metadata to ai-desktop, see |ai-usage|; opt-in
host = false, -- ai-desktop base URL; false = the ai_desktop provider's own
},
ollama = {
num_ctx = 32768, -- context window every Ollama request asks for; false = Ollama's own default
},
ui = {
enable = true,
progress_style = "auto", -- "auto"|"notify"|"statusline"|"echo"|"fidget"|"float"|"kit"
panel_theme = "rounded",
badge_timeout_ms = 6000,
},
keymaps = {
enable = true,
prefix = "<leader>a",
-- Per-action overrides, keyed by action id (ask/quick/explain):
-- keymaps = { quick = "<leader>xs" } -- move just one
-- keymaps = { explain = false } -- disable just one
},
which_key = { enable = true },
usercmds = { enable = true },
-- Default context for the quick-action keymaps (<leader>as/<leader>ae).
-- :Ai ask/stream build no context of their own -- only what a caller
-- passes to require("ai").ask()/stream() directly.
context = {
buffer = false,
selection = true,
diagnostics = false,
cwd = false, -- expensive (a full cwd sweep); off by default
structured_data = false, -- json/yaml/xml block under the cursor, via data.nvim (optional)
conflict = false, -- both sides of unresolved merge conflicts, via gitsuite.nvim (optional)
mcp = false, -- one read-only MCP tool call the caller names (see |ai-context|)
mcp_allowed = {}, -- "<server>/<tool>" entries it may name; empty = no restriction
},
-- Inline completion (ghost text at the cursor), see |ai-completion|.
completion = {
enable = true,
trigger = "manual", -- "manual"|"auto"
idle_ms = 500, -- auto-mode idle debounce
max_context_lines = 60,
max_tokens = 512, -- claude, ollama (num_predict); cut-off answers are discarded
effort = "low", -- claude; ollama: "low" = no thinking; false = none
provider = false, -- overrides `provider`, completion only; false = unset
model = false,
keymap = {
trigger = "<C-\\><C-a>", -- insert mode; manual mode only
accept = "<Tab>",
dismiss = "<C-]>",
},
},
log_level = vim.log.levels.WARN,
})
"ai_desktop" is a registered built-in provider (a local ai-desktop server, see
|ai-providers|) and is in provider_order's default, listed last since it
needs a local server the user must run themselves -- see |ai-scope|.
Provider policy
*ai-policy* Some machines may only use some providers.policy.allowedlists them, once, for everything that goes through ai.nvim; empty (the default) means no restriction and nothing changes. With a list: -provider = "auto"walks only the listed entries ofprovider_order(a session grant, below, does not widen it). - A request naming another provider fails before anything is sent (provider_resolution,err.data.reason == "policy"), for every caller. -:Ai provider {name}for an unlisted provider asks first; a yes allows it for this Neovim session only, nothing is written.:Ai provider autoneeds no question: it is the walk above, already limited to the list. - A caller that asked the user itself may setallow_unlisted = trueon one request. A malformedpolicy.allowed(not a list of strings) is not read as empty: every provider is refused until it is fixed,setup()warns,|:checkhealth|reports it. The same holds for a key underpolicythat does not exist (alowed, or a list written straight intopolicy): it is a rule that was meant and is not in force, so nothing is allowed until the key is fixed -- even next to a validallowed. So doespolicyspelt wrong at the top level of the options (polcy,plicy,Policy,policies: within two edits ofpolicyor of its plural): the realpolicywould stay at its default, no restriction. Any other unknown key is only a warning. The list is not checked against the registry, so an id may be listed before its provider exists. Plugins on top of ai.nvim read it with |ai.policy()| and may restrict further, never widen it.
Key profiles
*ai-keys* More than one credential for the same provider -- a private key now, a company account later:keysnames them per provider and says where each comes from,:Ai key {profile}picks one for the session.
keys = {
claude = {
active = "private", -- in force at startup (optional)
profiles = {
private = { env = "PRIVATEKEY" }, -- a variable name
company = { file = "~/.config/ai/company.key" },
},
},
}
A profile has exactly one source:env(a variable name),file(a path; the first non-empty line, re-read when the file changes) orcommand(see |ai-keys-command|). A key file that does not exist, cannot be read or (on POSIX) can be read by group or others is a|:checkhealth|warning. Withoutkeysnothing changes. A chosen profile never falls back to the provider's default variable: with an empty source the request fails (missing_api_key, naming the profile;provider = "auto"does not move on to another provider), and the same goes for anactivethat names no defined profile. A key file may be UTF-8 (BOM allowed) or UTF-16 with a BOM. Keys are never printed --:Ai info,:Ai keyand|:checkhealth|show profile, source kind and "key present" or "KEY MISSING" only, and neither is a key pasted where theenvname belongs (anything that is not a variable name, or the shape of a vendor key:AIza...,gsk_...,hf_..., a bare mixed-case token of 32+ characters). The switch is for the session; nothing is written. *ai-keys-command* A profile can take its key from a command (password manager, secret store):
firma = {
command = { "pass", "show", "anthropic/firma" }, -- argument list, no shell
timeout_ms = 10000, -- optional
cache_ms = 3600000, -- optional, default session
}
The command is started directly from the argument list -- a string is refused -- asynchronously and with a timeout, never fromavailable(): a configured command counts as available andai.ask/ai.streamrun it before the first request. A.cmd/.batis refused on Windows (libuv cannot run it, andcmd.exe /cwould re-parse the arguments): use an.exeor{ "pwsh", "-NoProfile", "-File", "{script}.ps1" }.timeout_msis a whole number of milliseconds, 1 to 3600000 (default 10000). The first non-empty line of stdout is the key, kept in memory only (cache_ms, at least one second, default the whole session; a failed run is not cached and not started again for 4 s;:Ai key {profile}and:Ai key resetend the wait). stderr is discarded. Errors name the profile and a reason (exit code, timeout, no output), never output or an argument;:Ai infoshowscommand {executable}and "key present", "key not fetched yet" or "KEY MISSING: reason".
5. COMMANDS
*:Ai* :Ai [prompt?] Same as:Ai ask [prompt?]. :Ai ask [prompt?] *:Ai-ask* Ask once, non-streaming. Prompts for text ifpromptis omitted. :Ai stream [prompt?] *:Ai-stream* Likeask, but the answer panel opens and fills in live as it streams. :[range]Ai capture [source?] *:Ai-capture* Take context into a prompt.sourceisselection,messages(the last line of|:messages|),notify(the last notification) orbuffer(the lines around the cursor); default: the selection with a range, else the last message. The text is redacted (the home folder becomes~, the user name<user>) and shown in an editable float: delete what must not go out, <CR> asks for the question and streams the answer,qcancels. Other plugins:require("ai.capture").get(source). :[range]Ai rewrite [prompt?] *:Ai-rewrite* Replace the range (default: the current line) with AI-generated code. :[range]Ai append [prompt?] *:Ai-append* Insert AI-generated code after the range (default: the current line). :[range]Ai prepend [prompt?] *:Ai-prepend* Insert AI-generated code before the range (default: the current line). These three send the task text alongside a fenced copy of the range; the model is told to answer with only code, and the response is written back in one buffer edit (a singleuundoes it). Non-streaming, and with NO preview or confirmation step: the selected code goes to the active provider and its answer lands in the buffer as soon as it arrives -- read it before moving on. An empty or truncated response, or one arriving after the buffer changed underneath it, is discarded with a warning. A range on any other:Aisubcommand is ignored with a warning. :Ai provider {name} *:Ai-provider* Switch the active provider, or back toauto.<Tab>-completes registered ids andauto. A provider outsidepolicy.allowed(|ai-policy|) asks first; a yes allows it for this session only. :Ai agent [{name}|none] *:Ai-agent* Switch the active agent for this session: a named preset of provider, model and system prompt fromconfig.agents.<Tab>-completes the names andnone; no argument shows the active agent. Nothing is written, the next start begins withconfig.agentagain. Per field, a request's own value wins over the agent's, which wins over the configuration's; the agent'smodelis used only with the agent's own provider. The agent's provider is subject to |ai-policy| like any request for it. Configure:
agents = {
review = { provider = "claude", model = "claude-opus-4-5", system = "You review code." },
terse = { system = "Answer in one sentence." },
},
agent = "review",
An agent withrepo_prompt = trueadds the repository's own prompt file after itssystem, see |:Ai-trust|. :Ai trust [allow|forget] *:Ai-trust* The repository's own system-prompt file (repo_prompt.file, default.ai.mdat the project root: the directory with.gitabove the current buffer's file; the file, links resolved, must lie inside it). Only an agent withrepo_prompt = truesends it, after the agent'ssystem; no agent does by default. A file in a repository that instructs a model is prompt injection from every clone that carries one, so its content must be trusted first: - no argument shows the file for review: path, size, whether this content is trusted, the text. Nothing is sent. -allowtrusts exactly the content:Ai trustshowed this session (a file changed in between is refused: review it again). The record is the SHA-256 of the content, kept instdpath("state")/ai.nvim/repo_prompt_trust.json; a changed file is untrusted again. -forgetdrops the record. A request of such an agent with the file missing, larger thanrepo_prompt.max_bytesor untrusted is refused with a message that says what to do, not sent without it. A request with its own system prompt (the in-place edits, the completion) reads no file. The text goes out as it stands: no placeholders,{{...}}included. There are no hooks and no commands from the file. :Ai key [{profile}|reset] [{provider}] *:Ai-key* Choose the API-key profile (|ai-keys|) for this session on every provider that defines it, or only on {provider}.resetreturns to the configuredactiveprofile / the provider's own variable; no argument shows the setup. :Ai stop *:Ai-stop* Stop every running stream (the requests behind the panels) and say how many were stopped. A one-shot:Ai ask,rewrite/append/prependand completion hold no handle yet and run to their end; the message says so when nothing was stopped. :Ai info *:Ai-info* Show the active provider and agent, resolution order, the provider policy, and per-provider availability (providers outside the allow-list are marked). Withprovider = "auto"the first line names the provider it resolves to right now,auto (-> claude), or why none does (none available,key missing,blocked by policy); an active agent's own provider wins, as it does for a request. WhileANTHROPIC_BASE_URLis set, a line underclaude-clinames the host the CLI will talk to (the host only; it can be a company gateway). None of these build any context automatically -- they only send the literal prompt text. The quick-action keymaps (|ai-bindings|) are what wire in the current buffer/selection/diagnostics viaconfig.context.
6. BINDINGS
All keymaps sit under one configurable prefix (config.keymaps.prefix, default<leader>a) and are individually overridable/disableable viaconfig.keymaps[id](see |ai-config|).
Mode Default Action id Does
n, v <leader>aa ask Ask once, non-streaming (prompts for
text; v: about the selection)
n, v <leader>as quick Send context + a typed task, stream
the answer
n, v <leader>ac capture Ask about the last message (v: the
selection), shown redacted first
n, v <leader>ar rewrite Replace current line/selection with
AI-generated code
n, v <leader>ao append Insert AI-generated code after current
line/selection
n, v <leader>aO prepend Insert AI-generated code before current
line/selection
n, v <leader>ae explain Explain the current context in a small
badge, no panel
n <leader>an agent Switch to the next agent (config.agents)
n <leader>ax stop Stop every running stream
rewrite/append/prepend act on whole lines (see |:Ai-rewrite|): a charwise
Visual selection still affects the full line(s) it touches, with a warning.
Autocmds: a VimLeavePre handler in the ai_nvim augroup kills every
still-running stream, so quitting Neovim never leaves an orphaned curl
process behind. With completion.enable, the AiCompletion augroup also
dismisses a shown suggestion once the buffer/cursor moves past it
(TextChangedI, CursorMovedI), clears completion state on InsertLeave,
and -- only for completion.trigger = "auto" -- schedules the idle-pause
trigger on TextChangedI.
7. COMPLETION
Inline "ghost text" suggestions at the cursor, insert mode only. A suggestion is exactly one |ai.ask()| call framed as a fill-in-the-middle prompt (the buffer text before/after the cursor) -- not a true FIM API, so quality/latency vary by provider/model. See |ai-scope| for why this counts as the same single-turn interaction the rest of the plugin covers, just with a different trigger and renderer.
Mode Default Action id Does
i <C-\><C-a> trigger Request a suggestion at the cursor
(manual mode only)
i <Tab> accept Insert the shown suggestion; falls
through to normal <Tab> when nothing
is shown or a completion-menu popup is
open (pumvisible())
i <C-]> dismiss Clear the shown suggestion without
inserting it
config.completion.trigger:
"manual" (default) Only the trigger keymap fires a suggestion.
"auto" Also fires one after completion.idle_ms (default
500) of no typing. An explicit opt-in: this means an
API call -- possibly against a paid cloud provider
-- on every idle pause, not just on deliberate
action. |:checkhealth| ai warns if trigger = "auto"
is combined with a cloud provider.
config.completion.provider/.model override config.provider/.model
for completion requests only, e.g. to always complete against a local
Ollama model regardless of what :Ai ask uses.
Typing or moving the cursor dismisses a shown, unaccepted suggestion (its
context no longer matches reality). A response that arrives after the
buffer or cursor has since changed is discarded rather than rendered, for
the same reason.
Set completion.keymap.<name> = false to drop just that one key, or
completion.enable = false to disable the feature entirely.
8. LUA API
*ai.setup()* require("ai").setup({opts}) Set up ai.nvim: merges {opts} over the defaults, registers the built-in providers, and (unless disabled) installs the default keymaps/usercmds. Calling it a second time is a no-op (warns and returns false). *ai.config()* require("ai").config() Returns the activeAi.Configtable. *ai.policy()* require("ai").policy() Returns a copy of the provider policy (|ai-policy|):allowed(the allow-list, nil when unrestricted),restricted(boolean) andgranted(ids confirmed for this session outside the list). *ai.ask()* require("ai").ask({req}, {cb}) Ask once, non-streaming. {req} fields: prompt string (required) the question/instruction provider string? explicit provider id; default: config.provider model string? overrides the resolved provider's default model context table?Ai.ContextDefaults, see |ai-context| timeout_ms integer? overrides config.timeout_ms system string? system prompt, provider-dependent max_tokens integer? response-length cap; read byclaudeandollamaattachments table?Ai.Attachment[], see |ai-attachments| api_key string? overrides the provider's env-var lookup, this request only -- setproviderexplicitly with it, a key belongs to one API host string? overrides the base URL ofollama,ai_desktoporopenai(an OpenAI-compatible endpoint; only whenprovider = "openai"), this request only allow_unlisted boolean? this request may use a provider outsidepolicy.allowed; set it only after asking the user, see |ai-policy| temperature number? sampling temperature; sent by claude, openai, gemini and ollama, ignored by the others num_ctx integer? context window in tokens; onlyollamasends it, defaultconfig.ollama.num_ctxeffort string? low, medium, high, xhigh or max; claude sends it to a model that takes it, ollama turns low into think = false bulk table? run under the guard rails for unattended bulk use, see |ai-bulk|;askthen returns a handle {cb} is called ascb(ok, res_or_err):res_or_erris anAi.Responsetable (text,usage,stop_reason,provider) on success, or aLibErrorValueon failure, whosekindis one ofmissing_api_key,invalid_request,timeout,network_error,api_error,invalid_response,blockedorprovider_resolution(a bulk request, |ai-bulk|, can also fail withbulk_limitorcancelled; a request of an agent with the repo_prompt field, |:Ai-trust|, withrepo_prompt_invalid_path,repo_prompt_no_root,repo_prompt_missing,repo_prompt_too_largeorrepo_prompt_untrusted;:Ai trustitself reportsrepo_prompt_unreviewedandrepo_prompt_store). *ai-bulk*
Bulk requests
A plugin that sends a whole document in many small requests (a translation,
say) nobody watches request by request. bulk is the leash for that case, in
one place; ai.nvim adds no task logic -- prompt, splitting and checking the
answer stay with the caller.
local handle = require("ai").ask({
prompt = chunk,
system = "Translate to German. Keep Markdown.",
provider = "claude",
bulk = {
label = "mdview:README.md", -- names the run (required)
max_chars = 4000, -- largest request accepted (required)
concurrency = 2, -- in flight per label, the rest queue (default 1)
max_total_chars = 200000, -- cumulative cap of this label, this session
},
}, function(ok, res)
-- ok: res.text, res.provider and res.bulk = { provider, model, label,
-- temperature, deterministic, chars } -- a cache key for the caller
-- not ok: res.kind is bulk_limit, cancelled, provider_resolution,
-- invalid_request, timeout, ...
end)
handle:kill() -- callback once with kind "cancelled"; queued ones cost nothing
- Limits: a request overmax_chars, or pastmax_total_charsorbulk.max_session_chars(config, all bulk requests of the session), fails withbulk_limit(err.data.reasonsays which) before anything is sent.max_session_chars = 0refuses every bulk request, and a value that is notfalseor a number >= 0 (or a misspelt key underbulk) is reported bysetup()and refuses every bulk request too: it never means "no cap".require("ai.bulk").reset(label)starts a fresh budget;.cancel(label)kills every request of a label;.usage(label)reads the counters. - Policy: a provider outsidepolicy.allowedis refused with a message that says what to do. Document text needs its own confirmation: ask the user once, thenrequire("ai.policy").grant_bulk(id)for the session, or setbulk.allow_unlisted = trueon one request.allow_unlistedand:Ai providerdo not count for bulk, nothing is silent. - The callback runs exactly once and always asynchronously, also for input that is not what it should be (a field of the wrong type is aninvalid_request, a NUL byte in the text is one character). Only a call that is no request at all (reqnot a table,promptnot a string) raises fromai.askitself, bulk or not. A provider that never answers is failed after itstimeout_msplus 5 s.kill()cannot abort an HTTP request already sent, it drops the answer (the cost is spent); a request still waiting for a command-sourced key is not sent at all once it was cancelled. - Amissing_api_keyfailure ends the requests of the label that wait for the same provider at once, so the key command does not run for each chunk. The request that hit it gets its callback first; the others get a copy of the error. -temperature = 0is sent where the provider takes one (bulk.temperaturechanges it and wins over the request's own,falsesends none);res.bulk.temperatureandres.bulk.deterministicsay what was sent. Models that take only their default temperature (e.g. OpenAI o-series) reject0: usebulk.temperature = falsefor them. The same holds for the claude models whose API rejects sampling parameters (Fable, Mythos, Opus 4.7 and later, Sonnet and Haiku 5 and later): bulk then does not send its default0andres.bulk.deterministicis false; a temperature you set yourself still goes out. A provider error that mentions the temperature gets this hint appended. - Not combinable withallow_unlisted,attachmentsorcontext; not available for |ai.stream()|. *ai.stream()* require("ai").stream({req}, {handlers}) Like |ai.ask()|, but streams the response. {handlers} fields: on_chunk function? function(delta: string) on_done function? function(res: Ai.Response) on_error function? function(err: string) Returns the runningvim.SystemObj(or nil if no provider could be resolved) so a caller can:kill()it to cancel --ai.ui.panelalready does this for the built-in quick-actions (|ai-bindings|). *ai.providers.register()* require("ai.providers").register({provider}) Register a custom (or replacement) provider. Registering under an id that already exists -- built-in or previously custom -- replaces it. {provider} is anAi.Provider:
require("ai.providers").register({
id = "myproxy",
available = function() return true end,
ask = function(req, cb) ... end,
stream = function(req, handlers) return process_handle_or_nil end,
})
Add the id toconfig.provider_orderto make it reachable throughprovider = "auto". *ai.context.assemble()* require("ai.context").assemble({opts}) Build the context block for {opts} (Ai.ContextDefaults:buffer,selection,diagnostics,cwd,structured_data,conflict,mcp,mcp_allowed, all boolean flags butmcp(a call) andmcp_allowed(a list)). Every section is best-effort -- a scope that resolves to nothing (no visual selection active, no diagnostics present, no unresolved conflict) is silently omitted.structured_dataneeds data.nvim andconflictneeds gitsuite.nvim, both optional soft dependencies -- absent, those two flags are silent no-ops too. Returns an empty string if nothing was requested or resolved. See |ai-context|.
9. PROVIDERS
claude Anthropic Messages API. Streaming via SSE. Requires
ANTHROPIC_API_KEY.
ollama Local Ollama daemon. Streaming via NDJSON. Requires the ollama
binary and a running daemon.
openai OpenAI Chat Completions API. Streaming via SSE. Requires
OPENAI_API_KEY.
gemini Google Gemini API. Streaming via SSE. Requires GEMINI_API_KEY.
ai_desktop Local ai-desktop server (POST /ask, POST /ask/stream). Streaming
via SSE. Requires a running ai-desktop instance (default
http://127.0.0.1:8080, override with AI_DESKTOP_HOST, or the old
LOOMAI_HOST; the old provider id loomai still works). Last in
the default provider_order -- see |ai-scope|.
claude-cli Claude Code CLI (claude -p), text only, streaming via its
stream-json output. Uses the account the CLI is logged in as, so
no API key is configured in ai.nvim -- every variable the CLI
ranks above its own login (an API key or token, a long-lived OAuth
token, the Bedrock/Vertex/Foundry/AWS/Mantle switches, a named
Anthropic profile, the federation pair) is removed from the child
process so a stray variable cannot override it; the gateway URL
(ANTHROPIC_BASE_URL) is passed on, and shown by :Ai info and
|:checkhealth| ai, host only, while it is set. A credential the
CLI reads from its own settings (an apiKeyHelper, or a key or
token in its env block) is not environment of the child and
is not removed; |:checkhealth| ai says when one is defined.
Runs without tools, hooks or session state in a neutral
directory; the prompt goes to its stdin, never to argv.
@path mentions in the text are denied and the CLI's own
expansion of them is switched off (it would otherwise read the
file and send it along), and a prompt starting with / is
labelled so the CLI does not answer it as one of its own
commands. Opt-in (not in provider_order). A billing or login
problem comes back as an api_error carrying the CLI's message;
a process that dies before its answer is complete is a
network_error, never a shortened answer, and one that exits
cleanly with neither a result nor any text is an
invalid_response, never an empty answer.
copilot GitHub Copilot CLI (copilot), text only, streaming via its
--output-format json events. Uses the account the CLI is logged
in as; the token variables and the routing variables of the CLI
are removed from the child process. Runs with every tool off
(--available-tools naming no tool, every built-in excluded,
shell/write/url denied, no built-in MCP server, no questions,
no custom instructions, no permission ever granted) in a throw-away
working directory and a throw-away home directory, both deleted when
the process ends: the CLI would otherwise keep the prompt and the
answer under ~/.copilot/session-state. The prompt goes to its
stdin, never to argv, and is not interpreted there (@file,
!cmd and /cmd stay text). The answer is the final message; the
commentary the model streams before it is not. If the CLI ever
reports a tool request or tool event, the answer is discarded
(api_error). A start-up failure (login, token, model) comes back
as an api_error that names auth, token, credit or model
and carries the CLI's message; a process that dies before its
answer is complete is a network_error. Unverified: the shape of
an error event during a run (used-up credit). Opt-in (not in
provider_order).
provider = "auto" (the default) walks provider_order and uses the first
provider whose available() is true -- a cheap, synchronous check (an
executable on PATH and/or an env var set), never a network round trip. Set
provider to an explicit id to always use one provider; `:Ai provider
{name}` switches it at runtime.
API keys are read from the environment (vim.env.*) unless a caller passes
req.api_key for one request (see |ai-attachments|), never stored by
this plugin, and never appear in curl's argv -- they go through
lib.nvim.net.curl's secret_headers, which is the reason ai.nvim exists
at all (see |ai-intro|). |:checkhealth| ai and :Ai info show only whether
a key is set, never its value.
10. ATTACHMENTS
A request can carry binary payloads alongside its prompt -- a rasterized page, a whole PDF -- throughreq.attachments, a list ofAi.Attachment:
local attachments = require("ai.attachments")
local page, err = attachments.from_file("/tmp/invoice-page-1.png")
if not page then error(err) end
require("ai").ask({
prompt = "Extract every table on this page as Markdown.",
provider = "claude",
attachments = { page },
}, function(ok, res) ... end)
Ai.Attachmentis three fields --kind("image"or"document"),media_type(an IANA type) anddata(base64, unwrapped) -- plus an optionalname(used in error messages; OpenAI sends it as the file part filename). That is the intersection of what every provider's wire format actually carries; each backend spells it its own way. *ai.attachments.from_file()* require("ai.attachments").from_file({path}, {opts}) Read, size-check and base64 {path}. Returnsattachment, nilornil, err_message-- never raises. {opts}:media_type(overrides the extension guess),kind(overrides the media-type guess),name. Recognized extensions: .png .jpg .jpeg .gif .webp .pdf *ai.attachments.from_bytes()* require("ai.attachments").from_bytes({data}, {media_type}, {opts}) Same, for bytes already in memory (a rasterizer's stdout, say). What each provider can carry: claude image, document content blocks with a base64sourcegemini image, documentinline_dataparts with amime_typeopenai imageimage_urlpart whose url is adata:URI ollama image bareimagesarray on the message ai_desktop -- text only claude-cli -- text only (the CLI is run without tools) copilot -- text only (the CLI is run without tools) A provider that cannot carry an attachment FAILS the request (err.kind == "invalid_request") before sending anything -- it is never dropped silently, because a prompt asking about a page, sent without the page, does not fail: it answers confidently about nothing. Onlyclaudeandgeminitake a PDF whole; for the others the caller rasterizes pages first and sends images. A capability describes the API, not the model: Ollama's chat endpoint has animagesfield for every model,llavareads it andllama3.2ignores it.capabilities.websays whether a provider's request can use web search in one single-turn round-trip. It isfalseon every built-in, because none wires a web-search parameter into its request yet; a caller must treat web access as unavailable.:Ai infolists each provider's capabilities. Large requests need no configuration. A body over 8 KB is written to a0600temp file and read back by curl with--data-binary @fileinstead of being passed in argv, where Windows caps a command line at 32 767 characters; the file is removed once the request ends.
11. CONTEXT
Ai.ContextDefaultsfields, all boolean, independent (not mutually exclusive): buffer The current buffer, fenced and line-numbered. selection The last visual selection's range, same format. diagnosticsvim.diagnostic.get()for the current buffer, formatted asfile:line:[severity]:message, sorted by line. cwd A full working-directory sweep vialib.nvim.harvest.scope. Expensive; off by default. structured_data The json/yaml/xml block under the cursor, flattened topath: valuelines via data.nvim (optional soft dependency; a silent no-op without it or outside such a block). conflict Both sides of every unresolved merge conflict in the buffer, labeled "ours"/"theirs", via gitsuite.nvim (optional soft dependency; a silent no-op without it or outside a conflict). mcp One read-only MCP tool call the caller names, as `{ server = "<lib.nvim.mcp client id>", tool = "...", args = {...} }`, made before the request; its result is added as text. The model never sees a tool and cannot ask for one. Off by default. mcp_allowed "<server>/<tool>" entries amcpcall may name; empty (the default) = no restriction, it only narrows; a malformed value refuses every call.require("ai").ask()/.stream()prefix the request'spromptwith the assembled context block, if any. The quick-action keymaps (|ai-bindings|) useconfig.contextas their default;:Ai ask/`:Ai stream` build no context of their own.
12. SCOPE
ai.nvim covers single-turn question/answer and streaming: ask a question, get an answer; stream a longer one into a panel; send the current context along with a typed task. This includes more than one *trigger* for that same single-turn call -- an explicit:Ai/keymap action is one; an editor-triggered inline completion suggestion (|ai-completion|) is another. Both are exactly one |ai.ask()| round-trip under the hood, just with a different trigger source and renderer, not a new kind of interaction. It does not cover anything that looks like an autonomous multi-step agent, a sandboxed execution environment, or tool-use/function-calling loops. That is a separate, deliberate boundary with a native, independent project (not a Neovim plugin, not a dependency of ai.nvim) -- see docs/scope.md in the repo for the full reasoning. TheAi.Providerinterface (id,available(),ask(),stream(),capabilities) is deliberately narrow so that an HTTP-backed provider pointing at such a system can be added as one registry entry, with no redesign.ai_desktopis exactly that (a thin client for ai-desktop's own/ask//ask/stream, nothing more -- see |ai-providers|) and is, unlike a hypothetical deeper integration, in the defaultprovider_order(default{"claude", "ollama", "openai", "gemini", "ai_desktop"},ai_desktoplast). Any *other* provider -- a custom one registered under its own id, or a future built-in not yet added toprovider_order-- stays reachable only by naming it explicitly (provider = "<name>"), never through"auto"by accident.
13. USAGE REPORTING
ai-desktop keeps a usage log (usage.jsonlnext to itsconfig.json) and shows it on its dashboard. Withusage.report = trueai.nvim adds its own requests to it: after every |ai.ask()| and |ai.stream()| call that reached a provider -- the quick actions,:Ai, inline completion and bulk requests (|ai-bulk|) all go through the same path -- one event goes toPOST {host}/usage/events:
{ "provider": "claude", "model": "claude-opus-4-5", "stream": false,
"ok": true, "prompt_tokens": 37, "completion_tokens": 3,
"duration_ms": 812 }
and on failure"ok": falsewith"error_kind", the error's kind (|ai-api|), never its message. The body is built from this allow-list and nothing else: no prompt, no system prompt, no answer text (ai-desktop refuses a body that carries such a field). The token counts are read where each provider's API puts them (claude/claude-cli: input_tokens/output_tokens,openai: prompt_tokens/completion_tokens,gemini: promptTokenCount/candidatesTokenCount); another provider reports 0 (copilotamong them: its CLI counts premium requests, not tokens). Off by default: on, it is one extra network request per AI request, to a server the user runs themselves. Sending is asynchronous and fire-and-forget (curl throughai.providers.transport, a timeout of a few seconds); a server that is not running costs nothing but one DEBUG notification per session. Requests to theai_desktopprovider are never reported -- that server records its own/asktraffic, a second event would count them twice.usage.hostnames the ai-desktop base URL;false(the default) is the one theai_desktopprovider uses:AI_DESKTOP_HOST, elseLOOMAI_HOST, else http://127.0.0.1:8080. Areportthat is not a boolean or ahostthat is not a string is dropped to its default and reported by|:checkhealth|.
14. HEALTH CHECK
:checkhealth ai
Reports:
- core -- Neovim version (>= 0.11), curl on PATH.
- lib.nvim -- each required submodule (net.curl, harvest.scope, progress,
ui.kit, usercmd.composer, bindings.keymap), plus a specific check that
lib.nvim.net.curl.fetch_stream exists -- a too-old lib.nvim checkout
has every other module present but not this one.
- providers -- every registered provider id and whether available() is
currently true (missing binary and/or API key otherwise). Never shows a
key's value, only whether one is set. While ANTHROPIC_BASE_URL is set,
an entry under claude-cli says the CLI will talk to that host (host
only, it can be a company gateway): a warning when the CLI can be run
(claude is on PATH, or claude-cli is the provider, in
provider_order or the completion.provider), an info line otherwise.
A second entry under claude-cli, at the same levels, says when the
claude CLI's user or managed settings file defines an apiKeyHelper:
that credential ranks above the CLI's login, so claude-cli may use
another account than the one logged in. A third entry, at the same
levels, says when the env block of those settings sets an API key or
token and names the variable: the CLI applies the block after it has
started, so it is not removed from the child, and it may override the
login in the same way. Only whether the keys exist is looked up; no
value and nothing else of the files is ever read out or shown.
- configuration -- the active provider and provider_order, whether
usage reporting (|ai-usage|) is on and where it reports to, and a
warning for every value that was dropped to its default, for a malformed
policy.allowed, for an unknown key under policy and for a misspelt
policy.
- provider policy -- whether there is an allow-list, an error for a
malformed policy.allowed, an unknown key under policy or a misspelt
policy (every provider is refused until it is fixed), and a warning
for a provider,
completion.provider or provider_order that falls outside the list
and for a provider allowed only for this session.
- completion -- enabled?, trigger mode, the resolved
completion.provider. Warns if trigger = "auto" resolves to a paid
cloud provider, since that means an API call on every idle pause.
- composer route pre-flight -- :Ai's own route table, validated by
lib.nvim.usercmd.composer.