Use NaN Builders models in VS Code Chat and Agent mode through the native LanguageModelChatProvider API.
Status: early MVP and community-maintained. This extension is not an official NaN Builders product unless NaN Builders explicitly adopts or publishes it.
- Native
languageModelChatProvidersintegration for VS Code Chat and Agent mode. - API key stored in VS Code
SecretStorage. - API-key validation and model discovery through
GET https://api.nan.builders/v1/models. - The model picker follows the API-key-filtered list returned by NaN, so premium-only models appear only when the key can actually call them.
- Streaming chat through
POST https://api.nan.builders/v1/chat/completions. - VS Code tool definitions mapped to OpenAI-compatible function tools.
- Streamed tool calls mapped back to VS Code so supported models can run in Agent mode.
- Image inputs for catalogued vision-capable models.
- Opt-in inline ghost-text completions through the legacy
POST /v1/completionsendpoint whennanBuilders.completionModelis set (issue #8). - Local status-bar usage when the API returns OpenAI-compatible streaming usage metadata.
- Account-wide credit usage in the status bar via
GET /v1/usagewhen an API key is configured, with local-session usage as fallback. - Conservative handling of newly discovered model IDs that are not yet in the local metadata catalog.
- Per-model reasoning effort: choose a level with NaN Builders: Set Model Reasoning Effort, send per-request levels through
modelOptions, or leave everything onauto, which uses a documented default per model. - Opt-in
nanBuilders.discoveryMode: autofor Copilot-style auto-discovery from trusted OpenAI-compatible endpoints: every non-chat-filtered ID returned byGET /modelsappears in the picker with endpoint-declared capabilities (issue #100). - Remote-workspace support: the provider prefers the workspace extension host and falls back to the local UI host.
Search for NaN Builders for VS Code in the Extensions view, or run:
code --install-extension svg153.nan-builders-vscodeThe listing is community-maintained under the svg153 publisher and is not an official NaN Builders product.
- Download the latest
.vsixfrom GitHub Releases. - In VS Code run Extensions: Install from VSIX....
- Reload the window if VS Code asks.
npm ci
npm run check
npm run packageInstall the generated nan-builders-vscode-*.vsix with Extensions: Install from VSIX.... For interactive development, open the repository in VS Code and press F5 to launch an Extension Development Host.
- Open the Command Palette.
- Run NaN Builders: Manage Provider.
- Choose Set or replace API key and paste a NaN API key.
- Choose Validate API key and refresh models.
- In Chat or Agent mode, select a model under the NaN Builders provider.
On recent VS Code builds the provider also shows its logo in the chat model picker and exposes native configuration: open Manage Models, expand NaN Builders, and set API Key (stored securely by VS Code) and API Base URL directly there. Values entered in Manage Models take precedence for chat and model discovery and the key is adopted into the extension's own SecretStorage; NaN Builders: Manage Provider keeps working on older VS Code versions and for the remaining commands.
The model picker is intentionally limited to IDs returned by the key's /v1/models response. Run NaN Builders: Refresh Models after access changes. Provider extensions can also be found with the VS Code Marketplace filter:
@tag:language-models
Available settings:
| Setting | Default | Purpose |
|---|---|---|
nanBuilders.apiBaseUrl |
https://api.nan.builders/v1 |
OpenAI-compatible API base URL. Change only for development or trusted compatible servers. |
nanBuilders.modelCacheSeconds |
300 |
Model discovery cache duration. |
nanBuilders.showStatusBar |
true |
Show usage in the status bar: plan-credit usage % when an API key is configured, otherwise local session usage. |
nanBuilders.includeUnknownModels |
false |
Expose unknown IDs without tool or vision metadata. |
nanBuilders.defaultReasoningEffort |
auto |
Fallback reasoning level for models that expose adjustable effort. auto uses each model's documented default (medium when supported, otherwise the central documented level); explicit levels act as the global fallback. |
nanBuilders.reasoningEffortByModel |
{} |
Per-model reasoning overrides set by NaN Builders: Set Model Reasoning Effort (for example "glm-5.3-flash": "high"). Overrides win over the global setting; removing an entry resets that model to auto. |
nanBuilders.discoveryMode |
"curated" |
auto lists every chat ID returned by GET /models from a trusted custom endpoint, except obvious non-chat names (embeddings, rerank, speech, transcription, moderation/guard, image/video generation, minimax-only endpoints). Endpoint-declared capability fields take precedence; models without metadata get conservative defaults. In curated mode, if GET /models fails or returns no chat IDs, the picker falls back to the static catalog marked "not live-verified". |
nanBuilders.completionModel |
"" |
Model ID for opt-in inline ghost-text completions; empty disables the feature and no completion request is sent. |
Models differ in which reasoning levels the API documents for them. Resolution happens per request, in this order:
modelOptions.reasoning_effortsupplied with the request.nanBuilders.reasoningEffortByModel[model](set through the picker command).nanBuilders.defaultReasoningEffort, unless it isauto.- The model's documented default:
mediumwhen the model supports it, otherwise the central documented level.
Whatever level is chosen is remapped to the closest documented level for that model (ties move upward), so selecting an unsupported deep-thinking level on a shallow model never sends a value the API rejects. The ladders are curated from the "Controlling reasoning" table at https://nan.builders/docs/models (checked 2026-11-16): /v1/models does not publish per-model effort levels, so the table must be re-checked when the docs change. Model-specific quirks are stated in each model description: GLM always reasons (none is applied as minimal); Gemma 4 and Qwen 3.6 treat both none and minimal as off, with levels capping the reasoning phase between 2,048 and 32,768 tokens; MiMo documents only low–max and counts reasoning tokens inside max_tokens; deepseek-v4-flash and qwen3.8-flash treat effort values as hints rather than caps.
Run NaN Builders: Set Model Reasoning Effort from the Command Palette, pick a model, then pick a level (or reset it to auto). The current level is shown in the model tooltip and in the selection UI description.
When nanBuilders.apiBaseUrl uses non-loopback http:, the extension asks before sending the stored API key. The decision is remembered for that endpoint until the extension session ends and covers model discovery, chat, account usage, and inline completions. A declined endpoint stays blocked without repeating the prompt; changing the endpoint clears declined decisions. Canceling prevents the request; HTTPS and loopback HTTP endpoints do not prompt.
To point the extension at a trusted OpenAI-compatible server (LM Studio, vLLM, Ollama's OpenAI endpoint, a corporate gateway) and pick its models directly, like the Copilot custom-endpoint experience:
-
Set the endpoint and restart-free refresh:
"nanBuilders.apiBaseUrl": "https://my-server.example.com/v1/", "nanBuilders.discoveryMode": "auto"
-
Run NaN Builders: Manage Provider to store the server's API key (any bearer token the server expects) and validate it; the picker then lists every chat ID returned by
GET /models, minus obvious non-chat endpoints. -
Trigger NaN Builders: Refresh Models after adding or removing models on the server; results are cached for
nanBuilders.modelCacheSeconds.
Notes: in auto mode the picker reflects the live endpoint only (no NaN catalog fallback), capability fields declared by the server (is_chat, model_type, context/output limits) take precedence over conservative defaults, and http: (non-loopback) endpoints require the one-time consent prompt before the key is sent. Set discoveryMode back to curated to restore the NaN Builders Marketplace experience.
The provider prefers the workspace extension host when using WSL, SSH, or a Dev Container. This keeps the model provider on the same host as the Chat/Agent session and avoids a known VS Code routing problem where Auto can replace an explicitly selected remote-provider model. In a remote workspace, install the extension and enter the API key in that remote host's SecretStorage.
For a local workspace, it continues to run locally. To force a published installation to the remote host while testing, use:
"remote.extensionKind": {
"svg153.nan-builders-vscode": ["workspace"]
}NaN chat models with compatible function tool calling are marked as supporting tools and appear in Agent model selection. The extension maps VS Code tools to OpenAI-compatible function tools, handles streamed tool calls, and maps tool names back to the original VS Code tool names.
Only model IDs returned by /v1/models are exposed. Known non-chat endpoints are removed. Unknown IDs are hidden by default so an embedding, image, or audio endpoint is not accidentally advertised as a chat model. Set nanBuilders.includeUnknownModels to true to expose unknown IDs conservatively while local metadata catches up.
VS Code needs context-window, output-budget, image, and tool-calling metadata, while /v1/models is the authorization and discovery source. The extension therefore keeps a small local capability catalog and never exposes a catalogued model unless the API key can access it. Refresh the catalog when NaN changes model capabilities. NaN's larger models (kimi-k3.1-pro, qwen3.8-max, deepseek-v4-pro, hy4, glm5.3) are appended with a (larger model) suffix in the picker because they bill more credits per token; their picker tooltip also states that they cost more per token than the flash models, while every other entry states that it draws from the account-wide credit pool. clef is a decision endpoint on POST /v1/systemone and is never offered as a chat model.
With an API key configured, the status bar shows how much of the plan's credit allowance you have used this period ($(graph) NaN NN%), read from GET /v1/usage. While credits.frozen is true it reads $(warning) NaN frozen instead, because credit-billed requests are being refused and the percentage is no longer the actionable information. NaN Builders: Show Usage shows the credit allowance, per-model credit usage for the current month, the local session history, provider management, and the NaN dashboard. Without an API key, the status bar and command fall back to local session usage.
Account-wide usage details:
- Requests are authenticated with the stored API key, never browser cookies or
nan-clisessions. - The window is the current calendar month (UTC), clamped client-side to the API's maximum of 90 days, with at most 500 rows per page and up to 3 pages merged.
- NaN bills metered models from one credits pool (7,000 credits on Inference, 20,000 on Premium, then optional credit packs), so per-model percentages are each model's share of that single allowance. Unmetered models (qwen3.6, gemma4, embeddings, rerank, audio, image) show Does not draw credits; a model with no billed credits in the window shows a note instead of a fabricated percentage.
- The headline percentage is the plan-credit usage for the current billing period, never a sum across models.
- Cached input tokens reported by NaN are shown for the window and for each model; they are already part of the prompt count, so they are never added to the token total.
- While
credits.frozenis true the subscription is inactive and credit-billed requests are refused, so the status bar switches to$(warning) NaN frozenand the tooltip and QuickPick flag the plan credits as frozen instead of implying the allowance is spendable. credits.pack_expires_atis rendered as a readable date with the distance in days ("expires 2026-06-01 (in 12 days)", "expires today", "expired on …") instead of a raw timestamp.- The QuickPick shows a Window credits (calendar month) row: the sum of the per-model credits rows, rounded to one decimal. NaN rounds each row and each model independently, so this figure can differ from the billing-period
usedtotal by tenths; it is labelled as an approximation and never replaces the headline percentage. - Show Usage ends with an Open section that deep-links to the NaN Cloud pages this feature depends on:
#settings-api-keysfor key management,#settings-billingfor the plan allowance, credit packs and invoices,/tokensfor the credits-per-1M-token price of each model, and the model catalogue atnan.builders/docs/models. Both#settings-*routes were checked against the console bundle's route table before being shipped. - A
402 insufficient_balancefrom any endpoint appends which credit reason applies (allowance exhausted, frozen credits, or no active pack) and points at NaN Builders: Show Usage, instead of surfacing a bare status code. - Credits are billed and reported from 2026-11-10 onward, cached input tokens from 2026-11-11, and
api_requestscounts from 2026-09-02; earlier dates report 0. - Usage refreshes are throttled client-side (60s between automatic refreshes, plus a 30 requests/minute limiter). A 429 response surfaces its
Retry-Afterhint. - Errors never clear the last good snapshot; they are reported in the tooltip and command output.
- The shipped account-usage decision and its remaining deferrals are recorded in Implementation decisions; the manual checks live in the Validation checklist.
Local usage remains available regardless of the API: NaN Builders: Show Usage also shows per-model daily aggregates (UTC days) retained locally for 30 days (up to 1,000 model/day records); use Clear local history in that dialog to remove them. Only counts and model IDs are stored in VS Code extension storage—never prompts, completions, API keys, or request payloads.
VS Code does not expose a documented usage-reporting callback for third-party chat providers, so local counts only cover turns where the API returned OpenAI-compatible streaming usage metadata; see issue #7.
Inline ghost-text completions are opt-in and off by default. Set nanBuilders.completionModel to a model ID returned by /v1/models and the extension registers an InlineCompletionItemProvider for file-scheme documents. Each suggestion is one POST {apiBaseUrl}/completions request carrying only the last 4,000 characters before the cursor, capped at 64 completion tokens and 1,000 suggestion characters. The provider waits for a fixed 150 ms quiet period after the latest trigger, cancels pending or in-flight work when another trigger arrives, and never returns stale text; HTTP errors, network failures, and empty or malformed responses are dropped. Quality depends on the chosen model, and while enabled each pause while typing can send an extra billed request that local usage history does not count yet (see issue #7).
VS Code Chat / Agent
|
v
LanguageModelChatProvider
|
+--> GET /v1/models
|
+--> GET /v1/usage
|
+--> POST /v1/chat/completions
| SSE text
| tool calls
+ usage
No alternate chat webview is created; the provider uses the built-in VS Code Chat and Agent UX.
- No models appear: validate the key, then refresh models. Check that the key can call
/v1/models. - A model is missing: the API key does not currently return that model, or it is a known non-chat endpoint.
- A request stops without text: NaN may have hit a reasoning-only truncation; try a shorter prompt or a model with adjustable reasoning.
- Remote or WSL window: the provider prefers the workspace extension host; install the extension and configure the key in that remote host's SecretStorage.
- Key safety: use Clear API key from the management command to remove it from SecretStorage.
- API keys are stored with VS Code
SecretStorage, not in settings JSON or the repository. - The extension does not log API keys.
nanBuilders.apiBaseUrlis machine-scoped so a workspace cannot redirect the stored API key to another endpoint.- Changing
nanBuilders.apiBaseUrlsends the configured key to that endpoint, so only change it to a server you trust.
This repository also ships an installable plugin for the GitHub Copilot app: the root plugin.json plus the Copilot CLI extension under com.github.copilot/extensions/nan-builders/. It does not replace the VS Code provider and cannot register NaN models inside Copilot — it adds agent-facing surfaces to the app:
nan-builderscanvas — a quota dashboard, the model catalog, and API key settings served from a local loopback-only server. The officialhttps://api.nan.builders/v1endpoint is built in (the same URL used by every official NaN Builders client), so users only ever paste their key; an endpoint override stays available under Advanced for development.nan_asktool — one-shot prompts to any NaN chat model (cheap second-opinion or verification passes). No streaming, no tool calls.nan_usagetool — account usage for the current UTC month as plain text for the agent.- Session context hook — every new Copilot session learns these surfaces exist and how to handle the key safely.
Install from this repository's marketplace:
/plugin marketplace add svg153/nan-vscode
/plugin install nan-builders@nan-vscode
Then run /reload (or restart the app) and ask Copilot to open the NaN Builders canvas.
The plugin keeps its API key outside the repository, in $COPILOT_HOME/extensions/nan-builders/artifacts/config.json (defaults under ~/.copilot), written with file mode 0600 (on Windows the file inherits NTFS permissions from your user profile, so it stays readable only by your account and system administrators; the Settings tab shows the exact path). The key is never returned to the canvas UI or written to logs, is overridable with the NAN_BUILDERS_API_KEY environment variable, and is only ever sent as Authorization: Bearer to the built-in https://api.nan.builders/v1 endpoint unless you deliberately set an override under Advanced (non-loopback plain HTTP then requires explicit confirmation in the canvas settings, same policy as the VS Code extension). Plugin logic reuses the identical API contract and quota rules as the provider and is covered by npm run test:extension (dependency-free node --test). The VSIX build excludes com.github.copilot/ and plugin.json, so the VS Code extension is unaffected.
npm ci
npm run check # compile, unit tests, isolated VS Code Insiders test
npm run package # create a VSIXCommits and pull-request titles use Conventional Commits. See CONTRIBUTING.md for the GSD issue workflow, skills, validation checklist, pull-request expectations, and release process.
Project policy and research live in docs/:
- Repository policy
- Validation checklist
- Provider research
- Implementation decisions
- Contribution guide
- Release history
The provider architecture was checked against existing open-source integrations rather than copied wholesale:
helmcode/nan-cli is useful as an endpoint and behavior reference. Its code is not copied because no license file was found in its repository root during the initial review.
- Evaluate native NaN MCP registration after the core provider is stable.
- Move capability metadata to server-provided metadata when NaN exposes it.
- Publish to the VS Code Marketplace only after naming, branding, publisher ownership, and support expectations are agreed with NaN Builders.
MIT. See LICENSE.
