pi-local-models
Pi extension for any local model harness - model discovery, per-project config
Package details
Install pi-local-models from npm and Pi will load the resources declared by the package manifest.
$ pi install npm:pi-local-models- Package
pi-local-models- Version
0.2.0- Published
- Nov 20, 2026
- Downloads
- 414/mo · 84/wk
- Author
- merken
- License
- MIT
- Types
- extension
- Size
- 86.1 KB
- Dependencies
- 0 dependencies · 1 peer
Pi manifest JSON
{
"extensions": [
"./extensions/local-models.ts"
]
}Security note
Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.
README
pi-local-models
Local model discovery for PI Coding Agent
This supports any openai-api spec provider
- llama.cpp
- Ollama
- oMLX
- llama-swap
- MTPLX
Installation:
pi install npm:pi-local-models
Configuration
Create a minimal config for your local LLM harness:
{
"url": "http://127.0.0.1:8080"
}
If the engine needs a key, you must also say how the key is sent:
{
"url": "http://127.0.0.1:8080",
"apiKey": "1234",
"apiKeyHeader": "bearer"
}
See a full example here
Store the file at user level: ~/.pi/agent/local-models.json Or at project level: ./.pi/agent/local-models.json
Run pi and use the /model command to select any discovered [local-model].
Model discovery mapping
Each engine reports models slightly differently. The extension reads both data[] and
models[], then maps the fields to the pi ProviderModelConfig:
| Field | splash | oMLX | llama.cpp |
|---|---|---|---|
id |
data[].id |
data[].id |
data[].id (GGUF path) |
name |
data[].id |
data[].id |
models[].name, path trimmed |
contextWindow |
context_length / max_model_len |
max_model_len |
meta.n_ctx |
input |
input_modalities, vision |
model_type (vlm = image) |
architecture.input_modalities |
reasoning |
reasoning.thinks |
config value | config value |
inputLimits |
limits.request_bytes, limits.images, limits.image_bytes |
- | - |
Ollama and llama-swap report no context length in /v1/models. The extension then
reads context_length from POST /api/show. llama-swap entries with
capabilities.embeddings, reranker, or decisions are dropped: they cannot answer a
chat request.
Fields the engine does not report fall back to local-models.json (contextWindow,
maxTokens, reasoning, input).
Optional config keys
| Key | Default | Meaning |
|---|---|---|
apiKeyHeader |
required with apiKey |
"bearer" sends Authorization: Bearer, "x-api-key" sends x-api-key, "both" sends both. Ignored when there is no apiKey. |
timeoutMs |
10000 |
How long the engine may take to answer. The timer stops as soon as a response arrives, so a slow body does not count. |
retry |
{ "attempts": 3, "delayMs": 1500 } |
Retry count for a refused connection or a 5xx. Timeouts and 4xx are not retried. |
contextProbe |
true |
Call POST /api/show for models that report no context length (Ollama). Set false to skip it. |
maxTokensField |
unset | Set "max_completion_tokens" if your engine rejects max_tokens. |
url and apiKey support $VAR and ${VAR} from the environment:
{
"url": "$LOCAL_LLM_URL",
"apiKey": "$LOCAL_LLM_KEY",
"retry": { "attempts": 4, "delayMs": 2000 }
}
llama.cpp reports the GGUF file path as the model id. When the server also lists a
clean alias (no /, not ending in .gguf), the extension uses that alias as the id.
When splash reports reasoning.efforts, those efforts become pi thinking levels.
Config validation
readConfig checks the file before any request. It stops with a message that names the
file when:
- the file has no
url, or theurldoes not start withhttp://orhttps://; - the file has
apiKeybut noapiKeyHeader; apiKeyHeaderis notbearer,x-api-key, orboth;- the file is not valid JSON.
An unset environment variable is not expanded, so "url": "$LOCAL_LLM_URL" fails with
an invalid url instead of calling a nonsense endpoint.
Show the current catalog
/local-models
This prints the engine url, the config file in use, and for each model: id, context window, max tokens, input modalities, thinking support, and quantization.
Refresh the model list
The engine often starts after Pi. Run this command in the TUI:
/local-models-refresh
The command re-reads local-models.json, fetches /v1/models again, and replaces the
[local-model] entries. Then run /model to select one. Pi also calls the provider's
refreshModels during its normal model refresh, so /model picks up newly loaded
models without a restart.
Tests
npm test # node --test tests/
npm run typecheck # tsc --noEmit on the extension and the tests
tests/fixtures/ holds one captured /v1/models response per engine: splash, oMLX,
llama.cpp, ollama, llama-swap, and mtp-lx. Each provider is tested twice: once on the
mapping functions, and once end to end with a stubbed fetch and a temp config file.