NORMAL ~/wkd/p/ai/help :set skin=modern utf-8

ai.txt

Provider-agnostic ask/stream layer for talking to an AI — ai.nvim

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 *ai-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-intro*

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 :Ai composer command, built on
lib.nvim.net.curl (SSE/NDJSON streaming, secrets kept out of curl's argv).

It pairs well with pdfport.nvim: its claude/ollama extraction backends
send their PDFs and page images through this plugin's ask() instead of
carrying a second hand-written curl/provider path of their own. That
migration is what |ai-attachments| were built for.

2. REQUIREMENTS *ai-requirements*

- Neovim >= 0.11 (lib.nvim calls the positional vim.validate; on 0.10 vim.system starts a child with clear_env without any environment).
- lib.nvim (github.com/WKDSteve/lib.nvim) -- hard dependency.
  fetch_stream/secret_headers on lib.nvim.net.curl must be present; a
  too-old checkout is flagged by |:checkhealth| ai.
- ui.nvim (github.com/WKDSteve/ui.nvim) -- also a hard dependency: ui.kit
  backs the streaming answer panel, the explain badge, the non-streaming
  viewer and the prompt popup. All lazy-loaded (no cost until an :Ai
  action 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.
- curl on PATH -- every provider shells out to it.
- At least one provider actually usable:
  - claude:  ANTHROPIC_API_KEY set in the environment.
  - openai:  OPENAI_API_KEY set in the environment. For an
             OpenAI-compatible endpoint (LM Studio, vLLM, a gateway) set
             AI_OPENAI_BASE_URL (https, or http for localhost only). The
             OpenAI key is never sent there: it gets
             AI_OPENAI_COMPAT_API_KEY, or no key. Without a key, "auto"
             does not pick it; choose openai explicitly.
  - gemini:  GEMINI_API_KEY set in the environment.
  - ollama:  the ollama binary on PATH, with the daemon running
             (default http://127.0.0.1:11434, override with
             AI_OLLAMA_HOST -- deliberately not OLLAMA_HOST, which is
             Ollama's own env var for the *server*'s bind address). Every
             request asks for a context window of ollama.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 with AI_DESKTOP_HOST; the old name LOOMAI_HOST still
             works, and so does the provider id loomai). Last in the default
             provider_order -- see |ai-scope|.
  - claude-cli: the Claude Code CLI (claude) on PATH, logged in
             (claude auth status). Opt-in: not in the default
             provider_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_URL is 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, which policy.allowed does not see.
             :Ai info and |:checkhealth| ai name the host while it is set.
             A known limit: a credential in the CLI's own settings (an
             apiKeyHelper, an API key or token in its env block, 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.json in CLAUDE_CONFIG_DIR when that is set,
             else in ~/.claude) or the managed settings file defines an
             apiKeyHelper or sets such a key or token in its env block;
             it only looks whether the keys exist. A federation profile is
             not detected.
  - copilot: the GitHub Copilot CLI (copilot) on PATH, logged in
             (copilot login; the login lives in the system credential
             store). Opt-in: not in the default provider_order, select it
             with :Ai provider copilot. Uses whatever account the CLI is
             logged in as; needs no token of its own, and COPILOT_GITHUB_TOKEN,
             GH_TOKEN and GITHUB_TOKEN (which outrank that login, and of
             which a classic ghp_ 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, and provider = "auto" (the default) picks
the first available one in provider_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 via pcall(require, ...); absent, the
matching |ai-context| flag is a silent no-op):
- data.nvim -- backs context.structured_data.
- gitsuite.nvim -- backs context.conflict.

3. SETUP *ai-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/keys are lazy-load triggers -- ai.nvim does nothing until :Ai is
run or one of the default <leader>a* keymaps is pressed.

4. CONFIGURATION *ai-config*

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.allowed lists 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 of provider_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 auto
    needs no question: it is the walk above, already limited to the list.
  - A caller that asked the user itself may set allow_unlisted = true on
    one request.

A malformed policy.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 under policy that does not exist (alowed, or a
list written straight into policy): 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
valid allowed. So does policy spelt wrong at the top level of the options
(polcy, plicy, Policy, policies: within two edits of policy or of its
plural): the real policy would 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: keys names 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) or command (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. Without keys
nothing 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 an active that 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 key and |:checkhealth| show profile, source kind and "key present" or
"KEY MISSING" only, and neither is a key pasted where the env name 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 from available(): a configured
command counts as available and ai.ask/ai.stream run it before the first
request. A .cmd/.bat is refused on Windows (libuv cannot run it, and
cmd.exe /c would re-parse the arguments): use an .exe or
{ "pwsh", "-NoProfile", "-File", "{script}.ps1" }. timeout_ms is
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 reset end the wait). stderr is discarded. Errors name the profile and a reason (exit
code, timeout, no output), never output or an argument; :Ai info shows
command {executable} and "key present", "key not fetched yet" or "KEY
MISSING: reason".

5. COMMANDS *ai-commands*

                                                                       *:Ai*
:Ai [prompt?]                    Same as :Ai ask [prompt?].

:Ai ask [prompt?]                                                 *:Ai-ask*
  Ask once, non-streaming. Prompts for text if prompt is omitted.

:Ai stream [prompt?]                                            *:Ai-stream*
  Like ask, but the answer panel opens and fills in live as it streams.

:[range]Ai capture [source?]                                   *:Ai-capture*
  Take context into a prompt. source is selection, messages (the
  last line of |:messages|), notify (the last notification) or buffer
  (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, q cancels. 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 single u undoes 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 :Ai subcommand is ignored with a warning.

:Ai provider {name}                                           *:Ai-provider*
  Switch the active provider, or back to auto. <Tab>-completes registered
  ids and auto. A provider outside policy.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 from config.agents. <Tab>-completes the names
  and none; no argument shows the active agent. Nothing is written, the
  next start begins with config.agent again. Per field, a request's own
  value wins over the agent's, which wins over the configuration's; the
  agent's model is 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 with repo_prompt = true adds the repository's own prompt file
  after its system, see |:Ai-trust|.

:Ai trust [allow|forget]                                        *:Ai-trust*
  The repository's own system-prompt file (repo_prompt.file, default
  .ai.md at the project root: the directory with .git above the current
  buffer's file; the file, links resolved, must lie inside it). Only an agent
  with repo_prompt = true sends it, after the agent's system; 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.
  - allow trusts exactly the content :Ai trust showed this session (a
    file changed in between is refused: review it again). The record is the
    SHA-256 of the content, kept in
    stdpath("state")/ai.nvim/repo_prompt_trust.json; a changed file is
    untrusted again.
  - forget drops the record.
  A request of such an agent with the file missing, larger than
  repo_prompt.max_bytes or 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}. reset returns to the configured
  active profile / 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/prepend and
  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).
  With provider = "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.
  While ANTHROPIC_BASE_URL is set, a line under claude-cli names 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 via config.context.

6. BINDINGS *ai-bindings*

All keymaps sit under one configurable prefix (config.keymaps.prefix,
default <leader>a) and are individually overridable/disableable via
config.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 *ai-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-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 active Ai.Config table.

                                                               *ai.policy()*
require("ai").policy()
  Returns a copy of the provider policy (|ai-policy|): allowed (the
  allow-list, nil when unrestricted), restricted (boolean) and granted
  (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 by claude and ollama
    attachments  table?     Ai.Attachment[], see |ai-attachments|
    api_key      string?    overrides the provider's env-var lookup, this
                            request only -- set provider explicitly with
                            it, a key belongs to one API
    host         string?    overrides the base URL of ollama, ai_desktop or
                            openai (an OpenAI-compatible endpoint; only
                            when provider = "openai"), this request only
    allow_unlisted  boolean?  this request may use a provider outside
                            policy.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; only ollama sends it,
                            default config.ollama.num_ctx
    effort       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|; ask then returns a handle

  {cb} is called as cb(ok, res_or_err): res_or_err is an Ai.Response
  table (text, usage, stop_reason, provider) on success, or a
  LibErrorValue on failure, whose kind is one of missing_api_key,
  invalid_request, timeout, network_error, api_error,
  invalid_response, blocked or provider_resolution (a bulk request,
  |ai-bulk|, can also fail with bulk_limit or cancelled; a request of an
  agent with the repo_prompt field, |:Ai-trust|, with repo_prompt_invalid_path,
  repo_prompt_no_root, repo_prompt_missing, repo_prompt_too_large or
  repo_prompt_untrusted; :Ai trust itself reports repo_prompt_unreviewed
  and repo_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 over max_chars, or past max_total_chars or
    bulk.max_session_chars (config, all bulk requests of the session), fails
    with bulk_limit (err.data.reason says which) before anything is sent.
    max_session_chars = 0 refuses every bulk request, and a value that is not
    false or a number >= 0 (or a misspelt key under bulk) is reported by
    setup() 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 outside policy.allowed is refused with a message
    that says what to do. Document text needs its own confirmation: ask the
    user once, then require("ai.policy").grant_bulk(id) for the session, or
    set bulk.allow_unlisted = true on one request. allow_unlisted and
    :Ai provider do 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 an
    invalid_request, a NUL byte in the text is one character). Only a call
    that is no request at all (req not a table, prompt not a string)
    raises from ai.ask itself, bulk or not. A provider that never answers
    is failed after its timeout_ms plus 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.
  - A missing_api_key failure 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 = 0 is sent where the provider takes one (bulk.temperature
    changes it and wins over the request's own, false sends none);
    res.bulk.temperature and res.bulk.deterministic say what was sent.
    Models that take only their default temperature (e.g. OpenAI o-series)
    reject 0: use bulk.temperature = false for 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 default 0 and res.bulk.deterministic is false; a temperature you
    set yourself still goes out. A provider error that mentions the
    temperature gets this hint appended.
  - Not combinable with allow_unlisted, attachments or context; 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 running vim.SystemObj (or nil if no provider could be
  resolved) so a caller can :kill() it to cancel -- ai.ui.panel already
  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 an Ai.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 to config.provider_order to make it reachable through
  provider = "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 but mcp (a call) and mcp_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_data needs
  data.nvim and conflict needs 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 *ai-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 *ai-attachments*

A request can carry binary payloads alongside its prompt -- a rasterized
page, a whole PDF -- through req.attachments, a list of Ai.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.Attachment is three fields -- kind ("image" or "document"),
media_type (an IANA type) and data (base64, unwrapped) -- plus an
optional name (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}. Returns attachment, nil or
  nil, 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 base64 source
  gemini   image, document    inline_data parts with a mime_type
  openai   image              image_url part whose url is a data: URI
  ollama   image              bare images array 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.

Only claude and gemini take 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 an images field for every model,
llava reads it and llama3.2 ignores it.

capabilities.web says whether a provider's request can use web search in
one single-turn round-trip. It is false on every built-in, because none
wires a web-search parameter into its request yet; a caller must treat web
access as unavailable. :Ai info lists each provider's capabilities.

Large requests need no configuration. A body over 8 KB is written to a
0600 temp file and read back by curl with --data-binary @file instead 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-context*

Ai.ContextDefaults fields, all boolean, independent (not mutually
exclusive):

  buffer        The current buffer, fenced and line-numbered.
  selection     The last visual selection's range, same format.
  diagnostics   vim.diagnostic.get() for the current buffer, formatted as
                file:line:[severity]:message, sorted by line.
  cwd           A full working-directory sweep via
                lib.nvim.harvest.scope. Expensive; off by default.
  structured_data
                The json/yaml/xml block under the cursor, flattened to
                path: value lines 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 a mcp call may name; empty (the
                default) = no restriction, it only narrows; a malformed
                value refuses every call.

require("ai").ask()/.stream() prefix the request's prompt with the
assembled context block, if any. The quick-action keymaps
(|ai-bindings|) use config.context as their default; :Ai ask/`:Ai
stream` build no context of their own.

12. SCOPE *ai-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.

The Ai.Provider interface (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_desktop is 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 default provider_order (default
{"claude", "ollama", "openai", "gemini", "ai_desktop"}, ai_desktop last). Any *other*
provider -- a custom one registered under its own id, or a future built-in
not yet added to provider_order -- stays reachable only by naming it
explicitly (provider = "<name>"), never through "auto" by accident.

13. USAGE REPORTING *ai-usage*

ai-desktop keeps a usage log (usage.jsonl next to its config.json) and
shows it on its dashboard. With usage.report = true ai.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 to
POST {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": false with "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 (copilot
among 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 through ai.providers.transport, a timeout of a few seconds); a server
that is not running costs nothing but one DEBUG notification per session.
Requests to the ai_desktop provider are never reported -- that server
records its own /ask traffic, a second event would count them twice.

usage.host names the ai-desktop base URL; false (the default) is the one
the ai_desktop provider uses: AI_DESKTOP_HOST, else LOOMAI_HOST, else
http://127.0.0.1:8080. A report that is not a boolean or a host that is
not a string is dropped to its default and reported by |:checkhealth|.

14. HEALTH CHECK *ai-health*

: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.

keys

j / k
next / previous line
gg / G
first / last line
⏎
open the line under the cursor
/
search plugins and apps (app: x or plugin: x narrows)
:
command line — Tab completes
:help x
vimdoc of a plugin (:e x = plugin page)
:ls · :apps · :play · :log · :stack
plugin list · app list · play area · activity stream · dependency graph
:log apps
the stream of one area (plugins or apps)
:colo x
colorscheme
:set skin=
modern | tui
?
this help
esc
close