localpi 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dutifuldev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,253 @@
+# localpi
+
+Localpi is a local Pi launcher for open-weight models.
+
+By default, Localpi discovers available local providers, lets you choose when more than one model is loaded, points Pi at the selected model, and writes Pi config for the other discovered models so `/model` can switch among them during the session.
+
+Localpi supports LM Studio, vLLM, custom OpenAI-compatible servers, and a managed `llama-server` fallback.
+
+Localpi is intentionally generic. It does not contain classifier prompts, dataset workflows, GitHub routing logic, or final-schema output machinery. Structured classifier runs belong in caller tools such as `localpager-agent`.
+
+See:
+
+- [Runtime Specification](docs/runtime-specification.md)
+
+## Install
+
+```bash
+npm install -g localpi
+```
+
+During development:
+
+```bash
+npm run localpi -- --status
+```
+
+After build:
+
+```bash
+node dist/src/cli/main.js --status
+```
+
+## Runtime Model
+
+Target default:
+
+```bash
+localpi --model gemma-12b
+```
+
+This uses the default `auto` runtime. If exactly one model is loaded locally, Localpi selects it. If multiple models are loaded in an interactive terminal, Localpi boots Pi with a temporary default and opens Pi's native model selector. If no external model is loaded, Localpi can fall back to the managed `llama-server` default. Thinking starts as `off` unless `--thinking` or `LOCALPI_THINKING` sets another startup level.
+
+LM Studio is explicit:
+
+```bash
+localpi --runtime lmstudio --model gemma-4-e4b-it
+```
+
+vLLM is explicit:
+
+```bash
+localpi --runtime vllm --model qwen
+```
+
+Custom OpenAI-compatible endpoints are also supported:
+
+```bash
+localpi --runtime openai-compatible --base-url http://127.0.0.1:8000/v1 --model my-model
+```
+
+Use `--provider <id>` with `--model <id>` to select a catalog entry without opening the picker. `--provider <id>` by itself only scopes the available choices. Localpi avoids loading multiple heavyweight local runtimes at the same time. When using the managed `llama-server` runtime, it either stops its previous managed server or clearly reports what is already running before starting another model.
+
+## Default Pi Behavior
+
+Localpi launches Pi with:
+
+- default tools: `read,bash,edit,write,grep,find,ls`
+- a system prompt that explains local tool approval and local-model limits
+- an approval gate before every tool call
+- token speed and token count status while responses stream
+- bounded Gemma/llama-server reasoning controlled by `--thinking`
+- an in-session `/thinking` command for changing Pi's active thinking level
+- local state under `~/.local/state/localpi`
+
+The approval gate makes failed or denied tool calls explicit to the model so the model does not claim that a blocked command ran.
+
+## LM Studio Alternative
+
+LM Studio exposes an OpenAI-compatible endpoint, usually:
+
+```text
+http://127.0.0.1:1234/v1
+```
+
+Load Gemma in LM Studio:
+
+```bash
+~/.lmstudio/bin/lms server start
+~/.lmstudio/bin/lms load gemma-4-e4b-it -y
+```
+
+Then run localpi against LM Studio explicitly:
+
+```bash
+localpi --runtime lmstudio --model gemma-4-e4b-it
+```
+
+## Usage
+
+Run Pi interactively on the default local model:
+
+```bash
+localpi
+```
+
+Run a non-interactive Pi prompt:
+
+```bash
+localpi -p "summarize this repo"
+```
+
+Pin a model alias:
+
+```bash
+localpi --model gemma-e4b -p "write a detailed implementation plan"
+```
+
+Use a bounded reasoning budget with managed `llama-server`:
+
+```bash
+localpi --model gemma-12b --thinking low -p "classify this item"
+```
+
+In an interactive session, use `/thinking` to pick a level or `/thinking high` to set one directly. This changes Pi's active thinking level for later turns. For managed `llama-server`, the server-side reasoning budget is still chosen at startup because changing it requires restarting the local server process.
+
+For managed `llama-server`, thinking levels map to server-side reasoning:
+
+| Level     | llama-server reasoning                   |
+| --------- | ---------------------------------------- |
+| `off`     | `--reasoning off`                        |
+| `minimal` | `--reasoning on --reasoning-budget 32`   |
+| `low`     | `--reasoning on --reasoning-budget 128`  |
+| `medium`  | `--reasoning on --reasoning-budget 512`  |
+| `high`    | `--reasoning on --reasoning-budget 2048` |
+| `xhigh`   | `--reasoning on --reasoning-budget 8192` |
+
+The default is `off`.
+
+Point at vLLM:
+
+```bash
+localpi --runtime vllm --model qwen -p "review the src directory"
+```
+
+Point at a different OpenAI-compatible local server:
+
+```bash
+localpi --runtime openai-compatible --base-url http://127.0.0.1:8000/v1 -p "review the src directory"
+```
+
+Pass a Pi flag that localpi also owns after `--`:
+
+```bash
+localpi --model gemma-e4b -- --model some-pi-level-value
+```
+
+Stop the managed `llama-server` runtime:
+
+```bash
+localpi --stop
+```
+
+## Options
+
+- `--runtime <auto|llama-server|lmstudio|vllm|openai-compatible>`: runtime backend. Default: `auto`
+- `--provider <id>`: catalog provider id to use, for example `lmstudio` or `vllm`
+- `--model <alias|id|path|auto>`: model alias, model id, or GGUF path
+- `--ctx <n>` / `--context-window <n>`: model context window
+- `--max-tokens <n>`: generated model max output tokens
+- `--base-url <url>`: OpenAI-compatible endpoint for LM Studio or custom endpoints
+- `--server-command <path>`: `llama-server` executable path
+- `--llama-server <path>`: alias for `--server-command`
+- `--host <host>`: managed `llama-server` host. Default: `127.0.0.1`
+- `--port <n>`: managed `llama-server` port. Default: `18194`
+- `--gpu-layers <n>`: managed `llama-server` GPU layers. Default: `999`
+- `--parallel <n>`: managed `llama-server` parallel slots. Default: `1`
+- `--chat-template <path>`: optional llama.cpp chat template file
+- `--state-dir <path>`: runtime state directory. Default: `~/.local/state/localpi`
+- `--session-dir <path>`: Pi session directory. Default: `<state-dir>/sessions`
+- `--pi-command <command>`: Pi launch command
+- `--providers-file <path>`: provider registry JSON
+- `--tools <list>`: Pi tools allow list. Default: `read,bash,edit,write,grep,find,ls`
+- `--thinking <off|minimal|low|medium|high|xhigh>`: Pi thinking level and managed `llama-server` reasoning budget. Default: `off`
+- `--no-approval`: disable the tool approval gate
+- `--no-token-status`: disable the token status extension
+- `--status`: print runtime, model, and Pi config status
+- `--stop`: stop the managed `llama-server` process
+- `--list`: list configured model aliases
+
+## Environment
+
+- `LOCALPI_RUNTIME`
+- `LOCALPI_MODEL`
+- `LOCALPI_PROVIDER`
+- `LOCALPI_BASE_URL`
+- `LOCALPI_PROVIDERS_FILE`
+- `LOCALPI_STATE_DIR`
+- `LOCALPI_SESSION_DIR`
+- `LOCALPI_PI_CMD`
+- `LOCALPI_CONTEXT_WINDOW`
+- `LOCALPI_MAX_TOKENS`
+- `LOCALPI_LLAMA_SERVER`
+- `LOCALPI_HOST`
+- `LOCALPI_PORT`
+- `LOCALPI_GPU_LAYERS`
+- `LOCALPI_PARALLEL`
+- `LOCALPI_CHAT_TEMPLATE`
+- `LOCALPI_TOOLS`
+- `LOCALPI_THINKING`
+- `LOCALPI_MODELS_FILE`
+
+`LOCALPI_MODELS_FILE` may point at a JSON file with this shape:
+
+```json
+{
+  "models": {
+    "my-model": {
+      "id": "my-model-id",
+      "path": "/path/to/model.gguf",
+      "contextWindow": 32768,
+      "chatTemplate": "/path/to/template.jinja"
+    }
+  }
+}
+```
+
+Provider registries use the same file or `LOCALPI_PROVIDERS_FILE`:
+
+```json
+{
+  "providers": {
+    "vllm-qwen": {
+      "type": "openai-compatible",
+      "name": "vLLM Qwen",
+      "baseUrl": "http://127.0.0.1:8000/v1",
+      "discover": true
+    }
+  }
+}
+```
+
+Use `discover: false` for endpoints that should not be probed during startup. They can still be selected explicitly with `--provider vllm-qwen --model <id>`.
+
+## Development
+
+```bash
+npm run format
+npm run lint
+npm run typecheck
+npm test
+npm run build
+npm run check
+```

package/dist/src/cli/cli.js

@@ -0,0 +1,57 @@
+import { errorMessage, fail, ok } from "../common/result.js";
+import { parseLocalpiArgs, usage } from "../localpi/options.js";
+import { aliasListOutput, connectionStatus, resolveRuntime, statusOutput, stopRuntime } from "../localpi/runtime.js";
+import { writeRuntimeConfig } from "../pi/config.js";
+import { writeDefaultExtensions } from "../pi/extensions.js";
+import { createLaunchPlan, execLaunchPlan } from "../pi/launch.js";
+export async function run(args) {
+    try {
+        const options = parseLocalpiArgs(args);
+        const commandResult = await immediateCommandResult(options);
+        if (commandResult !== undefined) {
+            return commandResult;
+        }
+        const connection = await resolveRuntime(options);
+        const runtimeConfig = await writeRuntimeConfig(options, connection);
+        const selectorOptions = startupModelSelectorOptions(options, connection);
+        const extensions = await writeDefaultExtensions(options, selectorOptions === undefined ? {} : { startupModelSelector: selectorOptions });
+        const plan = await createLaunchPlan(options, runtimeConfig, connection, extensions);
+        const code = await execLaunchPlan(plan);
+        if (code !== 0) {
+            return { code, stdout: "", stderr: "" };
+        }
+        return ok(connection.warnings.length === 0 ? "" : connectionStatus(connection));
+    }
+    catch (error) {
+        return fail(`localpi: ${errorMessage(error)}`);
+    }
+}
+async function immediateCommandResult(options) {
+    if (options.forwardedArgs.length === 1 && options.forwardedArgs[0] === "--help") {
+        return ok(usage());
+    }
+    if (options.list) {
+        return ok(`${await aliasListOutput()}\n`);
+    }
+    if (options.stop) {
+        return ok(`${await stopRuntime(options)}\n`);
+    }
+    return options.status ? ok(`${await statusOutput(options)}\n`) : undefined;
+}
+function startupModelSelectorOptions(options, connection) {
+    if (!process.stdin.isTTY || !process.stderr.isTTY) {
+        return undefined;
+    }
+    if (options.model !== undefined && options.model !== "auto") {
+        return undefined;
+    }
+    const scopedProviderId = options.provider === undefined ? undefined : connection.providerId;
+    const loadedModels = connection.catalogModels.filter((model) => model.availability === "loaded" &&
+        (scopedProviderId === undefined || model.providerId === scopedProviderId));
+    if (loadedModels.length <= 1) {
+        return undefined;
+    }
+    return {
+        models: loadedModels.map((model) => ({ provider: model.providerId, id: model.modelId }))
+    };
+}

package/dist/src/cli/main.js

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+import { run } from "./cli.js";
+try {
+    const result = await run(process.argv.slice(2));
+    process.stdout.write(result.stdout);
+    process.stderr.write(result.stderr);
+    process.exitCode = result.code;
+}
+catch (error) {
+    process.stderr.write(error instanceof Error ? `${error.message}\n` : `${String(error)}\n`);
+    process.exitCode = 2;
+}

package/dist/src/common/json.js

@@ -0,0 +1,21 @@
+export function asObject(value, context) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error(`${context} must be an object`);
+    }
+    return value;
+}
+export function optionalString(value) {
+    return typeof value === "string" ? value : undefined;
+}
+export function requiredString(value, context) {
+    if (typeof value !== "string") {
+        throw new Error(`${context} must be a string`);
+    }
+    return value;
+}
+export function asArray(value, context) {
+    if (!Array.isArray(value)) {
+        throw new Error(`${context} must be an array`);
+    }
+    return value;
+}

package/dist/src/common/result.js

@@ -0,0 +1,9 @@
+export const ok = (stdout = "") => ({ code: 0, stdout, stderr: "" });
+export const fail = (stderr, code = 2) => ({
+    code,
+    stdout: "",
+    stderr: stderr.endsWith("\n") ? stderr : `${stderr}\n`
+});
+export function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/src/llm/openai.js

@@ -0,0 +1,78 @@
+import { asArray, asObject, optionalString } from "../common/json.js";
+export function normalizeBaseUrl(value) {
+    return value.replace(/\/+$/u, "");
+}
+export async function listModels(baseUrl, timeoutMs = 3000, fetcher = fetch) {
+    const response = await fetcher(`${normalizeBaseUrl(baseUrl)}/models`, {
+        signal: AbortSignal.timeout(timeoutMs)
+    });
+    if (!response.ok) {
+        throw new Error(`model list failed with HTTP ${String(response.status)}`);
+    }
+    const payload = await response.json();
+    const root = asObject(payload, "models response");
+    const data = asArray(root["data"], "models response data");
+    return data
+        .map((entry) => modelInfo(asObject(entry, "model entry")))
+        .filter((model) => model !== undefined);
+}
+export async function resolveLocalModel(baseUrl, requestedModel, timeoutMs = 3000, fetcher = fetch) {
+    const modelInfos = await listModels(baseUrl, timeoutMs, fetcher);
+    const availableModels = modelInfos.map((model) => model.id);
+    if (requestedModel === "auto") {
+        const first = modelInfos[0];
+        if (first === undefined) {
+            throw new Error(`no models returned by ${normalizeBaseUrl(baseUrl)}/models`);
+        }
+        return withOptionalContextWindow({ model: first.id, availableModels }, first.contextWindow);
+    }
+    if (availableModels.length > 0 && !availableModels.includes(requestedModel)) {
+        throw new Error(`model ${requestedModel} is not reported by ${normalizeBaseUrl(baseUrl)}/models; available: ${availableModels.join(", ")}`);
+    }
+    return withOptionalContextWindow({ model: requestedModel, availableModels }, modelInfos.find((model) => model.id === requestedModel)?.contextWindow);
+}
+function modelInfo(entry) {
+    const id = optionalString(entry["id"]);
+    if (id === undefined) {
+        return undefined;
+    }
+    return withOptionalContextWindow({ id }, findContextWindow(entry));
+}
+function withOptionalContextWindow(value, contextWindow) {
+    if (contextWindow === undefined) {
+        return value;
+    }
+    return { ...value, contextWindow };
+}
+function findContextWindow(entry) {
+    for (const key of [
+        "context_window",
+        "contextWindow",
+        "context_length",
+        "contextLength",
+        "max_context_length",
+        "maxContextLength",
+        "n_ctx",
+        "max_input_tokens",
+        "maxInputTokens"
+    ]) {
+        const value = positiveInteger(entry[key]);
+        if (value !== undefined) {
+            return value;
+        }
+    }
+    const metadata = entry["metadata"];
+    if (metadata !== null && typeof metadata === "object" && !Array.isArray(metadata)) {
+        return findContextWindow(metadata);
+    }
+    return undefined;
+}
+function positiveInteger(value) {
+    if (typeof value === "number" && Number.isInteger(value) && value > 0) {
+        return value;
+    }
+    if (typeof value === "string" && /^[1-9]\d*$/u.test(value)) {
+        return Number.parseInt(value, 10);
+    }
+    return undefined;
+}

package/dist/src/llm/types.js

@@ -0,0 +1 @@
+export {};

package/dist/src/localpi/catalog.js

@@ -0,0 +1,191 @@
+import { listModels } from "../llm/openai.js";
+import { getManagedLlamaServerMetadata, getLlamaServerModels, llamaBaseUrl } from "./llama-server.js";
+import { listModelAliases, resolveLlamaModel } from "./models.js";
+import { providerConfigs } from "./provider-registry.js";
+export async function discoverModelCatalog(options) {
+    const configs = await providerConfigs(options);
+    const discovered = await Promise.all(configs.map((config) => discoverProvider(config, options)));
+    return {
+        models: discovered.flatMap((entry) => entry.models),
+        warnings: discovered.flatMap((entry) => entry.warnings)
+    };
+}
+async function discoverProvider(config, options) {
+    switch (config.type) {
+        case "openai-compatible":
+            return discoverOpenAiCompatibleProvider(config, options);
+        case "managed-llama-server":
+            return discoverManagedLlamaProvider(config, options);
+    }
+}
+async function discoverOpenAiCompatibleProvider(config, options) {
+    if (config.baseUrl === undefined) {
+        return { models: [], warnings: [] };
+    }
+    if (!config.discover) {
+        const explicitModel = explicitOpenAiCatalogModel(config, [], options);
+        return { models: explicitModel === undefined ? [] : [explicitModel], warnings: [] };
+    }
+    try {
+        const models = await listModels(config.baseUrl, options.timeoutMs);
+        const explicitModel = explicitOpenAiCatalogModel(config, models, options);
+        return {
+            models: explicitModel === undefined
+                ? models.map((model) => openAiCatalogModel(config, model, options))
+                : [explicitModel],
+            warnings: []
+        };
+    }
+    catch (error) {
+        if (explicitOpenAiProviderSelected(options, config.id)) {
+            throw error;
+        }
+        return { models: [], warnings: [`${config.name} is not responding at ${config.baseUrl}`] };
+    }
+}
+function openAiCatalogModel(config, model, options) {
+    const baseUrl = config.baseUrl ?? "";
+    return {
+        providerId: config.id,
+        providerName: config.name,
+        runtime: "openai-compatible",
+        baseUrl,
+        modelId: model.id,
+        aliases: [],
+        displayName: `${config.name} / ${model.id}`,
+        maxTokens: options.maxTokens,
+        ...externalReasoningConfig(model.id),
+        capabilities: ["text"],
+        availability: "loaded",
+        ...(model.contextWindow === undefined ? {} : { contextWindow: model.contextWindow })
+    };
+}
+function explicitOpenAiCatalogModel(config, models, options) {
+    const requested = options.model;
+    if (models.length !== 0 || requested === undefined || requested === "auto") {
+        return undefined;
+    }
+    if (!explicitOpenAiProviderSelected(options, config.id)) {
+        return undefined;
+    }
+    return openAiCatalogModel(config, { id: requested }, options);
+}
+function explicitOpenAiProviderSelected(options, providerId) {
+    return (options.provider === providerId ||
+        (options.provider === undefined &&
+            (options.runtime === "lmstudio" ||
+                options.runtime === "vllm" ||
+                options.runtime === "openai-compatible")));
+}
+async function discoverManagedLlamaProvider(config, options) {
+    const baseUrl = llamaBaseUrl(options);
+    const aliases = await listModelAliases();
+    const loaded = await loadedLlamaModels(config, options, baseUrl, aliases);
+    const startable = await startableLlamaModels(config, options, baseUrl, loaded.models, aliases);
+    return {
+        models: [...loaded.models, ...startable],
+        warnings: loaded.warnings
+    };
+}
+async function loadedLlamaModels(config, options, baseUrl, aliases) {
+    const models = await getLlamaServerModels(options);
+    if (models === undefined) {
+        return { models: [], warnings: [] };
+    }
+    const managed = await getManagedLlamaServerMetadata(options);
+    return {
+        models: models.map((model) => {
+            const contextWindow = model.contextWindow ?? (managed?.modelId === model.id ? managed.contextWindow : undefined);
+            return {
+                providerId: config.id,
+                providerName: config.name,
+                runtime: "managed-llama-server",
+                baseUrl,
+                modelId: model.id,
+                aliases: aliases.filter((alias) => alias.id === model.id).map((alias) => alias.name),
+                displayName: `${config.name} / ${model.id}`,
+                maxTokens: options.maxTokens,
+                reasoning: managedModelSupportsReasoning(model.id),
+                capabilities: ["text"],
+                availability: "loaded",
+                ...(contextWindow === undefined ? {} : { contextWindow })
+            };
+        }),
+        warnings: []
+    };
+}
+async function startableLlamaModels(config, options, baseUrl, loaded, aliases) {
+    const loadedIds = new Set(loaded.map((model) => model.modelId));
+    const startable = await Promise.all(aliases.map(async (alias) => {
+        if (loadedIds.has(alias.id)) {
+            return undefined;
+        }
+        try {
+            const resolved = await resolveLlamaModel(alias.name, options.chatTemplate);
+            return {
+                providerId: config.id,
+                providerName: config.name,
+                runtime: "managed-llama-server",
+                baseUrl,
+                modelId: resolved.id,
+                aliases: [alias.name],
+                displayName: `${config.name} / ${alias.name}`,
+                maxTokens: options.maxTokens,
+                reasoning: managedModelSupportsReasoning(resolved.id),
+                capabilities: ["text"],
+                availability: "startable",
+                ...(resolved.contextWindow === undefined ? {} : { contextWindow: resolved.contextWindow })
+            };
+        }
+        catch {
+            return undefined;
+        }
+    }));
+    return startable.filter((model) => model !== undefined);
+}
+function externalReasoningConfig(modelId) {
+    const normalized = modelId.toLowerCase();
+    if (isDeepSeekThinkingModel(normalized)) {
+        return { reasoning: true, thinkingFormat: "deepseek" };
+    }
+    if (isQwenThinkingModel(normalized)) {
+        return { reasoning: true, thinkingFormat: "qwen-chat-template" };
+    }
+    return {};
+}
+export function managedModelSupportsReasoning(modelId) {
+    const normalized = modelId.toLowerCase();
+    return (normalized.includes("reason") ||
+        normalized.includes("thinking") ||
+        isDeepSeekThinkingModel(normalized) ||
+        isQwenThinkingModel(normalized) ||
+        normalized.includes("gpt-oss") ||
+        normalized.includes("gemma-4"));
+}
+function isDeepSeekThinkingModel(normalizedModelId) {
+    return (normalizedModelId.includes("deepseek") &&
+        (hasModelToken(normalizedModelId, "r1") ||
+            hasModelToken(normalizedModelId, "v4") ||
+            hasModelToken(normalizedModelId, "4") ||
+            normalizedModelId.includes("reason") ||
+            normalizedModelId.includes("thinking")));
+}
+function isQwenThinkingModel(normalizedModelId) {
+    const qwenThinkingMarkers = [
+        "qwq",
+        "qwen3",
+        "qwen-3",
+        "qwen_3",
+        "qwen 3",
+        "qwen4",
+        "qwen-4",
+        "qwen_4",
+        "qwen 4"
+    ];
+    return (qwenThinkingMarkers.some((marker) => normalizedModelId.includes(marker)) ||
+        (normalizedModelId.includes("qwen") &&
+            (normalizedModelId.includes("reason") || normalizedModelId.includes("thinking"))));
+}
+function hasModelToken(normalizedModelId, token) {
+    return normalizedModelId.split(/[^a-z0-9]+/u).includes(token);
+}