localpi 0.5.0 → 0.6.0

package/README.md

@@ -1,16 +1,29 @@
 # localpi
 
-Localpi is a Swiss army knife for running Pi with local inference engines.
+<p align="center">
+  <img src="assets/cover.svg" alt="localpi: an unopinionated Pi distribution that makes it easy to test and work with small local models on constrained systems" width="880">
+</p>
+
+Localpi is an unopinionated Pi distribution that makes it easy to test and work with small local models on constrained systems.
 
 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 is meant to be the practical bridge from Pi to local inference stacks such as llama.cpp/`llama-server`, vLLM, SGLang, LM Studio, Ollama, and custom provider endpoints.
+Localpi is meant to be the practical bridge from Pi to local inference stacks such as llama.cpp/`llama-server`, vLLM, SGLang, LM Studio, Ollama, and custom provider endpoints. llama.cpp is the default engine: Localpi probes a running llama.cpp server first and prefers its loaded models.
 
 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`.
 
+A Localpi session keeps its context light. Localpi appends three sentences to Pi's own system prompt, adds no datasets, prompt packs, or memory files, and loads only its own skills directory, so a session starts with about 2.9k tokens of baseline context on the default tool set and a small context window still has room for real work.
+
 See:
 
 - [Runtime Specification](docs/runtime-specification.md)
+- [Design Principles](docs/design-principles.md)
+
+## Requirements
+
+- Node.js 22.19.0 or newer, which Pi requires.
+- A running inference server: llama.cpp/`llama-server`, LM Studio, vLLM, SGLang, or any OpenAI-compatible endpoint. Localpi never starts, stops, or unloads a server it did not start itself.
+- A terminal that Pi supports.
 
 ## Install
 
@@ -18,6 +31,12 @@ See:
 npm install -g localpi
 ```
 
+Or the latest GitHub release directly:
+
+```bash
+npm install -g https://github.com/osolmaz/localpi/releases/latest/download/localpi.tgz
+```
+
 During development:
 
 ```bash
@@ -30,6 +49,22 @@ After build:
 node dist/src/cli/main.js --status
 ```
 
+## Pi and pi-factory Versions
+
+Localpi launches Pi through `npx -y @earendil-works/pi-coding-agent@latest`, so a normal launch
+runs the newest Pi release. Point it somewhere else with `--pi-command`, or `LOCALPI_PI_CMD`, as a
+program plus arguments:
+
+```bash
+localpi --pi-command "node /opt/pi/bin/pi"
+```
+
+Localpi builds its Pi launch on [pi-factory](https://github.com/osolmaz/pi-factory) and keeps that
+dependency current. The `@earendil-works/pi-coding-agent` devDependency pins the Pi release that
+localpi is written against, and `tests/generated-extension-types.test.ts` typechecks every
+generated extension against those types, so Pi extension API drift fails `npm test` instead of
+failing at launch.
+
 ## Runtime Model
 
 Target default:
@@ -66,14 +101,305 @@ 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
+- an approval gate before every tool call, which you can turn off for the session with `/approval`
+- token speed, prefill progress, and context usage while responses stream
+- a Catppuccin Mocha theme for the Pi session, written into `<state-dir>/pi-themes/`
+- skills from `<state-dir>/pi-skills/` only, so shared skill directories stay out of the session
 - bounded Gemma/llama-server reasoning controlled by `--thinking`
-- an in-session `/thinking` command for changing Pi's active thinking level
+- in-session `/thinking` (Pi's own command) and `/approval` (localpi's) for changing session settings
 - 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.
 
+## Skills
+
+Pi discovers skills from shared directories such as `~/.agents/skills` and `~/.pi/agent/skills`. A
+localpi session does not use those. It launches Pi with `--no-skills` and loads only
+`<state-dir>/pi-skills/`, so a small local model does not carry skill lists it cannot use.
+
+Put your own localpi skills there, one directory with a `SKILL.md` per skill:
+
+```bash
+mkdir -p ~/.local/state/localpi/pi-skills/my-skill
+$EDITOR ~/.local/state/localpi/pi-skills/my-skill/SKILL.md
+```
+
+Pick the source with `--skills` or `LOCALPI_SKILLS`:
+
+- `own` (default): `--no-skills` plus `<state-dir>/pi-skills/`
+- `ambient`: Pi's normal discovery, including `~/.agents/skills` and project `.agents/skills`
+- `off`: `--no-skills` and nothing else
+
+An explicit `--skill <path>` still works in every mode, because Pi loads explicit paths even with
+`--no-skills`.
+
+## Diffusion Canvas Visualizer
+
+The live diffusion canvas visualizer (watching DiffusionGemma denoise its
+answer in the TUI) lives in its own project now:
+[diffusionpi](https://github.com/osolmaz/diffusionpi). It is a pi-factory app
+bundle plus a standalone Pi widget package; the widget also installs into any
+Pi session via `pi install`.
+
+## Tool Approval
+
+Approval is on by default. Every tool call opens a dialog that shows the tool name and its input,
+with three choices:
+
+```text
+Allow once                        # run this call and keep asking for the next one
+Allow all tools for this session  # run every tool call in this session without asking
+Deny and stop                     # block the call and end the turn
+```
+
+A denied call does not run, the model is told that the call was blocked, and the turn stops instead
+of letting the model try another way. Pressing escape in the dialog counts as a deny, so one key
+ends the turn. Pi stops the turn when every blocked result in the current tool batch asks for it,
+so a batch that also contains an allowed read-only call finishes that call first.
+
+Read-only tools (`read`, `grep`, `find`, `ls`) run without a dialog, because they cannot change the
+workspace. `bash` still asks, because a bash command can write. An unknown tool also asks, because
+localpi cannot know what it does. Use `--approve-read-tools`, or `LOCALPI_APPROVE_READ_TOOLS=1`, to
+put read-only tools behind the gate too.
+
+The dialog choice lasts for this session only. Use the permission setting to change what new
+sessions do:
+
+```text
+/approval allow   # do not ask in new sessions either
+/approval ask     # ask before each tool call (the default)
+/approval off     # alias for /approval allow
+/approval on      # alias for /approval ask
+/approval         # pick ask or allow from a list, with the current value marked
+```
+
+The permission setting lives in `<state-dir>/settings.json` as `"permission": "ask" | "allow"`.
+Startup reads, in order: `--no-approval` or `LOCALPI_APPROVAL=0`, the saved setting, then the
+default `ask`. Use `--no-approval` to start one session without changing the setting.
+
+While approval is off, Pi shows `permission: allow` in the status area, so the state stays visible.
+
+In a non-interactive launch, approval stays on and no dialog is possible, so every tool call is
+blocked. That keeps scripted runs from executing tools without a person watching.
+
+## ACP Mode
+
+`--acp` and `LOCALPI_ACP=1` serve the Agent Client Protocol on stdio, so an ACP client such as an
+editor can drive the same Pi session that a normal launch runs.
+
+```bash
+localpi --acp --model gemma-e4b
+LOCALPI_ACP=1 localpi --model gemma-e4b
+```
+
+ACP mode:
+
+- resolves the runtime and writes the same Pi configuration a normal launch writes, including
+  `<state-dir>/pi-config-runtime/models.json` and `settings.json`
+- starts the pinned `pi-acp` adapter from `node_modules` as a child process with inherited stdio
+- writes a launcher script to `<state-dir>/acp/pi-launcher.sh` and points `PI_ACP_PI_COMMAND` at it,
+  because the adapter starts Pi itself and passes only its own arguments. The script quotes the Pi
+  program and every argument, so a path with a space survives, and execs Pi with the full launch line
+  a normal launch uses, so the extensions, the system prompt, the theme, and the tool flags stay the
+  same
+- passes the environment a normal launch uses, and sets `LOCALPI_ACP=0` for the child
+- requires an explicit `--model` or `LOCALPI_MODEL`, because there is no terminal for the startup
+  model picker
+- keeps stdout for protocol bytes only, and writes diagnostics and warnings to stderr
+- refuses `--demo`, a forwarded Pi `--mode`, Pi session flags, and forwarded prompts, because the
+  adapter owns the session
+- refuses `--status`, `--stop`, and `--list` together with `--acp` on the command line, and lets a
+  command-line immediate command win over an environment-set `LOCALPI_ACP=1`, as `LOCALPI_DEMO` does
+- refuses to start localpi as the adapter's Pi command, so a child cannot re-enter ACP mode
+
+Approval still works: the adapter forwards Pi's extension dialogs to the ACP client, so the client
+asks before a tool call runs. The adapter does not pass `--no-extensions`, so Pi extension discovery
+stays on.
+
+Pi has no ACP mode of its own. ACP support comes from `pi-acp` (MIT), which `package.json` pins to
+an exact version, and localpi never vendors its source. Set `LOCALPI_ACP_ADAPTER` to a path to run a
+different adapter build.
+
+## Continue On Truncation
+
+`--continue-on-truncation <n>` and `LOCALPI_CONTINUE_ON_TRUNCATION=<n>` continue a reply that the
+model cut off at the declared output limit, so a run finishes its answer instead of ending with a
+half-written one.
+
+```bash
+localpi --model gemma-e4b --max-tokens 4096 --continue-on-truncation 2
+LOCALPI_CONTINUE_ON_TRUNCATION=2 localpi --model gemma-e4b
+```
+
+`n` is the maximum number of extra continuations. Pi reports a turn that reached the output cap as a
+length stop, and localpi sends one follow-up message that asks the model to continue where it
+stopped without repeating earlier text. The guard:
+
+- is off by default. With no flag and no environment variable, a normal launch, an ACP launch, and
+  demo mode behave exactly as they do today
+- takes the flag first, then `LOCALPI_CONTINUE_ON_TRUNCATION`, then off
+- treats `LOCALPI_CONTINUE_ON_TRUNCATION=0` as off, so an inherited value can be disabled without
+  dropping the variable, and rejects any other value that is not a positive integer with exit code 2
+- reacts only to the length stop, never to a normal stop, an error, an abort, or a tool call
+- leaves a truncated turn that already asked for a tool alone, because Pi runs the tool and keeps
+  going on its own
+- counts continuations per session, stops at the limit, and prints one line to stderr when the reply
+  was still cut off
+- writes its notes to stderr only, so stdout stays free for a batch run
+- changes no served limit. `--max-tokens` and `--context-window` keep their meaning, and the guard
+  only reacts to the stop reason Pi reports
+
+The guard installs as the `continue-on-truncation.ts` Pi extension. It is not a default extension,
+so a normal session writes it only when you ask for it. It works in ACP mode too, because both
+launch paths share the same Pi configuration and extension bundle.
+
+## llama.cpp (Default Engine)
+
+llama.cpp is Localpi's default local engine.
+
+```bash
+localpi
+```
+
+With the default `auto` runtime, Localpi probes a running llama.cpp server at `http://127.0.0.1:8080/v1` first. A loaded llama.cpp model wins automatic selection ahead of LM Studio, vLLM, and the managed `llama-server` fallback. Localpi reads llama.cpp `/v1/models` status: a model is usable when it is loaded or the server does not report status, and an unloaded model is offered only when `/props` reports `models_autoload`. Localpi never starts, stops, or unloads an external llama.cpp server.
+
+Run explicitly against llama.cpp:
+
+```bash
+localpi --runtime llama-cpp
+localpi --runtime llama-cpp --base-url http://127.0.0.1:8080/v1 --model ternary-bonsai-2-27b-pq2_0
+```
+
+Point at a llama.cpp server on another port with a provider registry entry:
+
+```json
+{
+  "providers": {
+    "llama-cpp": {
+      "type": "llama-cpp",
+      "baseUrl": "http://127.0.0.1:9931/v1",
+      "discover": true
+    }
+  }
+}
+```
+
+### Image input
+
+When a llama.cpp model takes images, Localpi says so in the Pi model config, so the `read` tool and `@file` attachments can send a picture to that model. Localpi reads the fact from the server: an entry in `/v1/models` that lists `image` in `architecture.input_modalities` gets `input: ["text", "image"]`. Every other model stays text-only. No model name is used to guess this.
+
+An engine that reports nothing can be described with a model profile:
+
+```json
+{
+  "id": "qwen3-vl-8b",
+  "model": "qwen3-vl-8b",
+  "capabilities": { "image": true }
+}
+```
+
+The profile wins over the server in both directions, so `"image": false` also turns image input off for a model that reports it.
+
+The server must load a multimodal projector for the model, which a llama.cpp router does on its own from the model directory. Check it with one real image request before you rely on it.
+
+## Status Display
+
+The status display answers one question: is this machine keeping up? It shows elapsed time, output
+tokens, token rate, and context use. Pick a mode with `--stats`:
+
+| Mode             | Status line | Live line | Transcript entry |
+| ---------------- | ----------- | --------- | ---------------- |
+| `off`            | Pi's own    | no        | no               |
+| `line`           | localpi     | yes       | no               |
+| `full` (default) | localpi     | yes       | yes              |
+
+The status line is one row. Localpi replaces Pi's two-row footer with one line that carries the same
+facts plus the engine label next to the model:
+
+```text
+~/repos/localpi (main) · ↑3.2k ↓100 R3.2k CH99.5% · 43.8 tok/s · 9.8%/33k      (llama.cpp) ternary-bonsai-2-27b-pq2_0
+```
+
+The line holds, from left to right:
+
+- the working directory and the git branch,
+- the token totals, the cache read, and the cache hit rate of the session,
+- the token rate of the last finished turn,
+- the context use as a percentage of the window,
+- the engine that serves the model, then the model itself.
+
+The engine label comes from the provider localpi built the catalog with, so it is read, not guessed. A
+model from a provider with no known engine shows no label. When the model reports reasoning, the line
+also shows the thinking level, the same way Pi does.
+
+One number never appears twice at the same time. While the model runs, the live line owns the token
+rate and the context use, and the status line shows the rest. When the session is idle, the rate of
+the last finished turn and the context return to the status line, so the speed stays visible after
+the answer ends. The status line drops the rate first when the row is too narrow.
+
+The live line replaces Pi's plain `Working` text while the model runs:
+
+```text
+Working (1.8s · 100 out · 55.6 tok/s · ctx 34k/131k (26%))
+```
+
+During prefill, the same line reports progress through the prompt:
+
+```text
+Working (prefill 25% · 5k/20k tok · 3.2s · ctx 20k/33k (61%))
+```
+
+Prefill progress needs a llama.cpp server, because it reads the server's `/slots` endpoint. Localpi
+polls that endpoint only for llama.cpp runtimes. When the endpoint is missing or slow, localpi stops
+polling and shows elapsed prefill time instead.
+
+In `full` mode, each finished turn also adds one dim transcript line:
+
+```text
+10s · 438 out · 43.8 tok/s · 8.4k in · prefill 0.4s · ctx 34k/131k (26%)
+```
+
+Context colors use the active theme: normal below 80 percent, warning from 80 percent, error from
+95 percent. When Pi reports no token counts, the live line falls back to the context percentage
+alone.
+
+Localpi shows the engine label in `line` and `full` mode. In `off` mode localpi leaves the footer and
+the working line to Pi.
+
+Change the mode during a session with `/stats`:
+
+```text
+/stats          # pick a mode from a list
+/stats line     # or pass the mode directly
+```
+
+`/stats` saves the choice to `<state-dir>/settings.json`, so the next launch keeps it. Pass
+`--stats <mode>` or set `LOCALPI_STATS` to override the saved value for one launch.
+
+## Catppuccin Theme
+
+Localpi gives each Pi session the Catppuccin Mocha palette. It writes its own copy of the theme to
+`<state-dir>/pi-themes/catppuccin-mocha.json`, loads it into Pi, and selects it for the session. The
+theme covers the full Pi TUI: messages, tool cards, diffs, syntax highlighting, and the localpi
+status display.
+
+Localpi writes its own copy for a good reason. A localpi session uses a Pi config directory inside
+the localpi state directory, so Pi does not load the themes from your global Pi setup.
+
+The theme belongs to the session only. Localpi never edits your global Pi themes or settings.
+
+Localpi's own output uses the same palette: labels are `overlay1`, warnings are `peach`, and errors
+are `red`. Colors are truecolor and appear only on a terminal. Piped output stays plain, and
+`NO_COLOR` turns color off.
+
+Escape hatches:
+
+- `localpi --no-themes` starts the session with no theme at all.
+- `localpi --use-theme onur-dark` selects your own theme instead. The Catppuccin file is still
+  loaded, so `/settings` can offer it.
+- `localpi --theme <path>` adds another theme file, as Pi does in a normal session.
+- `FORCE_COLOR=1` forces color in localpi's own output; `NO_COLOR=1` removes it.
+
 ## LM Studio Alternative
 
 LM Studio exposes an OpenAI-compatible endpoint, usually:
@@ -115,7 +441,7 @@ Run an endless TUI demo:
 localpi --demo --model gemma-e4b
 ```
 
-Demo mode requires an explicit model, opens the normal Pi TUI, and keeps one live Pi session so followup prompts continue from the first prompt while Pi owns streaming, tok/s status, slash commands, and exit behavior.
+Demo mode requires an explicit model, opens the normal Pi TUI, and keeps one live Pi session so followup prompts continue from the first prompt while Pi owns streaming, tok/s status, slash commands, and exit behavior. Under the hood it loads the shared [pi-demo-mode](https://github.com/osolmaz/pi-demo-mode) extension, configured through the `--demo-*` flags below.
 
 Override the demo prompts:
 
@@ -135,7 +461,9 @@ Use a bounded reasoning budget with managed `llama-server`:
 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 and saves it for the next localpi launch. For managed `llama-server`, the server-side reasoning budget is still chosen at startup because changing it requires restarting the local server process.
+In an interactive session, use Pi's own `/thinking` command to pick a level or to set one directly. This changes Pi's active thinking level for later turns. Localpi remembers the level Pi selected and starts the next localpi launch from it. For managed `llama-server`, the server-side reasoning budget is still chosen at startup because changing it requires restarting the local server process.
+
+Localpi does not register its own `/thinking` command, because Pi already owns that name.
 
 For managed `llama-server`, thinking levels map to server-side reasoning:
 
@@ -174,13 +502,26 @@ Stop the managed `llama-server` runtime:
 localpi --stop
 ```
 
+## Demo Grid and Recording
+
+The `localpi grid` and `localpi record` subcommands moved to
+[demowall](https://github.com/osolmaz/demowall), a standalone tool that runs
+N copies of any command in a tiled tmux wall and records tmux sessions to
+video. A wall of localpi demo sessions is:
+
+```bash
+demowall grid --concurrency 4 --start -- localpi --demo --model gemma-e4b
+demowall record --session demowall-<timestamp> --out demo.mp4 --seconds 60
+```
+
 ## Options
 
-- `--runtime <auto|llama-server|lmstudio|vllm|openai-compatible>`: runtime backend. Default: `auto`
+- `--runtime <auto|llama-server|llama-cpp|lmstudio|vllm|openai-compatible>`: runtime backend. Default: `auto`, which prefers llama.cpp
 - `--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
+- `--continue-on-truncation <n>`: continue a reply cut off by the output limit, up to `n` times. Off by default, and `LOCALPI_CONTINUE_ON_TRUNCATION=<n>` sets the same limit
 - `--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`
@@ -191,24 +532,50 @@ localpi --stop
 - `--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
+- `--pi-command <command>`: Pi launch command as a program and its arguments. Quotes group words, and the command runs without a shell. Default: `npx -y @earendil-works/pi-coding-agent@latest`, so a normal launch runs the newest Pi release
 - `--providers-file <path>`: provider registry JSON
 - `--model-profile <path>`: local model capability profile JSON
 - `--model-reasoning <bool>`: override generated Pi reasoning capability
 - `--model-thinking-format <deepseek|qwen-chat-template>`: override generated Pi thinking format
 - `--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: last saved level, then `medium`
+- `--thinking-budget <n>`: managed `llama-server` thinking cap in tokens. `-1` leaves thinking unrestricted, and a positive value replaces the budget of the thinking level
+- `--thinking-budget-message <text>`: text the server injects before the end-of-thinking tag when the budget runs out. An empty value passes no message. Default: `Reasoning budget reached. Stop thinking and answer now.`
 - `--demo`: endlessly run Pi prompts inside the normal Pi TUI until interrupted or Pi exits; requires an explicit non-`auto` model
 - `--demo-initial-prompt <text>`: first demo prompt
 - `--demo-followup-prompt <text>`: repeated demo prompt after the first run
 - `--demo-initial-prompt-file <path>`: UTF-8 file for the first demo prompt
 - `--demo-followup-prompt-file <path>`: UTF-8 file for repeated demo prompts
-- `--no-approval`: disable the tool approval gate
-- `--no-token-status`: disable the token status extension
+- `--acp`: serve the Agent Client Protocol on stdio through the pinned `pi-acp` adapter; requires an explicit non-`auto` model
+- `--no-approval`: start with the tool approval gate off for the session
+- `--approve-read-tools`: also ask before read-only tools (`read`, `grep`, `find`, `ls`)
+- `--stats <off|line|full>`: status detail level. Default: `full`, or the last saved `/stats` choice
+- `--skills <own|ambient|off>`: skill sources. Default: `own`, which loads only `<state-dir>/pi-skills/` and turns off shared discovery such as `~/.agents/skills`. `ambient` keeps Pi's own discovery, and `off` loads no skills
+- `--no-skills`: load no skills. Alias for `--skills off`
+- `--no-token-status`: disable the token status extension. Alias for `--stats off`
 - `--status`: print runtime, model, and Pi config status
 - `--stop`: stop the managed `llama-server` process
 - `--list`: list configured model aliases
 
+## Pi Helper Tools
+
+Pi manages two helper binaries, `fd` and `rg`, and downloads them into its own bin directory when
+they are missing from `PATH`. Localpi starts Pi in offline mode, so Pi skips that download. A start
+that shows
+
+```
+Warning: fd not found. Offline mode enabled, skipping download.
+```
+
+means `fd` is not installed, and Pi falls back to a slower file search. Fix it in either way:
+
+- Install `fd`, for example with `brew install fd`. Pi uses the `fd` that is in `PATH`.
+- Run `PI_OFFLINE=0 localpi` once, and let Pi download `fd` into its own bin directory.
+
+Localpi keeps offline mode on by default, because a local-model session should not make network
+calls without a reason. `PI_OFFLINE` is pi-factory's default and passes straight through, so an
+explicit `PI_OFFLINE=0` or `PI_OFFLINE=1` always wins.
+
 ## Environment
 
 - `LOCALPI_RUNTIME`
@@ -224,6 +591,7 @@ localpi --stop
 - `LOCALPI_PI_CMD`
 - `LOCALPI_CONTEXT_WINDOW`
 - `LOCALPI_MAX_TOKENS`
+- `LOCALPI_CONTINUE_ON_TRUNCATION`
 - `LOCALPI_LLAMA_SERVER`
 - `LOCALPI_HOST`
 - `LOCALPI_PORT`
@@ -232,6 +600,13 @@ localpi --stop
 - `LOCALPI_CHAT_TEMPLATE`
 - `LOCALPI_TOOLS`
 - `LOCALPI_THINKING`
+- `LOCALPI_THINKING_BUDGET`
+- `LOCALPI_THINKING_BUDGET_MESSAGE`
+- `LOCALPI_STATS`
+- `LOCALPI_SKILLS`
+- `LOCALPI_APPROVE_READ_TOOLS`
+- `LOCALPI_ACP`
+- `LOCALPI_ACP_ADAPTER`
 - `LOCALPI_DEMO`
 - `LOCALPI_DEMO_INITIAL_PROMPT`
 - `LOCALPI_DEMO_FOLLOWUP_PROMPT`
@@ -304,3 +679,6 @@ npm test
 npm run build
 npm run check
 ```
+
+`npm run check` is the default gate. It does not run mutation testing, because the mutation run takes
+minutes. Run `npm run mutate` by hand once in a while; the `mutation` workflow runs it weekly.

package/dist/src/cli/cli.js

@@ -1,10 +1,15 @@
-import { runPiApp } from "@dutifuldev/pi-factory";
+import { runPiApp } from "@osolmaz/pi-factory";
+import { paint } from "../localpi/catppuccin.js";
 import { errorMessage, fail, ok } from "../common/result.js";
+import { runAcpApp } from "../localpi/acp.js";
 import { parseLocalpiArgs, usage } from "../localpi/options.js";
+import { engineEntries, providerConfigs } from "../localpi/provider-registry.js";
 import { aliasListOutput, connectionStatus, resolveRuntime, statusOutput, stopRuntime } from "../localpi/runtime.js";
 import { applyRememberedSettings } from "../localpi/settings-state.js";
 import { createLocalpiAppDefinition } from "../pi/app.js";
+import { writeLocalpiTheme } from "../pi/theme.js";
 import { writeDefaultExtensions } from "../pi/extensions.js";
+import { ensureLocalpiSkillsDir } from "../pi/skills.js";
 export async function run(args) {
     try {
         let options = parseLocalpiArgs(args);
@@ -12,22 +17,36 @@ export async function run(args) {
         if (helpResult !== undefined) {
             return helpResult;
         }
+        validateAcpOptions(options);
         validateDemoOptions(options);
         const commandResult = await immediateCommandResult(options);
         if (commandResult !== undefined) {
             return commandResult;
         }
         options = await applyRememberedSettings(options, {
-            thinking: hasExplicitThinkingOverride(args)
+            thinking: hasExplicitThinkingOverride(args),
+            stats: hasExplicitStatsOverride(args),
+            permission: hasExplicitPermissionOverride(args)
         });
         const connection = await resolveRuntime(options);
         const selectorOptions = startupModelSelectorOptions(options, connection);
-        const extensions = await writeDefaultExtensions(options, selectorOptions === undefined ? {} : { startupModelSelector: selectorOptions });
-        const app = createLocalpiAppDefinition(options, connection, extensions);
-        return await launchResolvedRuntime(app, connection);
+        const extensions = await writeDefaultExtensions(options, {
+            ...(selectorOptions === undefined ? {} : { startupModelSelector: selectorOptions }),
+            runtime: {
+                providerId: connection.providerId,
+                baseUrl: connection.baseUrl,
+                model: connection.model
+            },
+            engines: engineEntries(await providerConfigs(options))
+        });
+        await ensureLocalpiSkillsDir(options);
+        const app = createLocalpiAppDefinition(options, connection, extensions, await writeLocalpiTheme(options.stateDir, options.forwardedArgs));
+        return options.acp
+            ? await launchAcpRuntime(app, connection)
+            : await launchResolvedRuntime(app, connection);
     }
     catch (error) {
-        return fail(`localpi: ${errorMessage(error)}`);
+        return fail(`${paint("localpi:", "red")} ${errorMessage(error)}`);
     }
 }
 function validateDemoOptions(options) {
@@ -74,6 +93,52 @@ function validateDemoTty() {
         throw new Error("--demo requires an interactive TTY on stdin and stdout; run it directly in a terminal");
     }
 }
+function validateAcpOptions(options) {
+    if (!options.acp) {
+        return;
+    }
+    // A command-line immediate command wins over an environment-set LOCALPI_ACP, as it does for demo
+    // mode, so an exported mode switch does not take the status, stop, and list commands away.
+    if (!options.acpFromCli && hasImmediateCommand(options)) {
+        return;
+    }
+    if (options.demo) {
+        throw new Error("--acp cannot be used with --demo; ACP mode owns the terminal");
+    }
+    validateAcpImmediateOptions(options);
+    validateAcpModel(options);
+    validateForwardedAcpOptions(options.forwardedArgs);
+}
+function validateAcpImmediateOptions(options) {
+    if (options.status) {
+        throw new Error("--acp cannot be used with --status");
+    }
+    if (options.stop) {
+        throw new Error("--acp cannot be used with --stop");
+    }
+    if (options.list) {
+        throw new Error("--acp cannot be used with --list");
+    }
+}
+function validateAcpModel(options) {
+    if (options.model === undefined || options.model === "auto") {
+        throw new Error("--acp requires an explicit --model <alias|id|path> or LOCALPI_MODEL value; ACP mode has no terminal for model selection");
+    }
+}
+function validateForwardedAcpOptions(args) {
+    const incompatibleMode = forwardedIncompatibleMode(args);
+    if (incompatibleMode !== undefined) {
+        throw new Error(`--acp cannot be used with forwarded Pi mode ${incompatibleMode}; the ACP adapter starts Pi in rpc mode`);
+    }
+    const sessionFlag = forwardedSessionFlag(args);
+    if (sessionFlag !== undefined) {
+        throw new Error(`--acp cannot be used with forwarded Pi session flag ${sessionFlag}; the ACP client manages sessions`);
+    }
+    const promptInput = forwardedPromptInput(args);
+    if (promptInput !== undefined) {
+        throw new Error(`--acp cannot be used with forwarded Pi prompt input ${promptInput}; ACP clients send prompts over the protocol`);
+    }
+}
 function forwardedIncompatibleMode(args) {
     for (let index = 0; index < args.length; index += 1) {
         const arg = args[index];
@@ -244,6 +309,16 @@ async function launchResolvedRuntime(app, connection) {
     }
     return ok(connection.warnings.length === 0 ? "" : connectionStatus(connection));
 }
+/**
+ * ACP mode keeps stdout for the protocol only, so localpi reports its own diagnostics on stderr and
+ * returns the adapter's exit code unchanged.
+ */
+async function launchAcpRuntime(app, connection) {
+    const code = await runAcpApp(app, {
+        diagnostics: connection.warnings.length === 0 ? [] : [connectionStatus(connection)]
+    });
+    return { code, stdout: "", stderr: "" };
+}
 async function immediateCommandResult(options) {
     if (options.list) {
         return ok(`${await aliasListOutput()}\n`);
@@ -258,6 +333,37 @@ function helpCommandResult(options) {
         ? ok(usage())
         : undefined;
 }
+function hasExplicitStatsOverride(args) {
+    if (process.env["LOCALPI_STATS"] !== undefined) {
+        return true;
+    }
+    if (process.env["LOCALPI_TOKEN_STATUS"] !== undefined) {
+        return true;
+    }
+    for (const arg of args) {
+        if (arg === "--") {
+            return false;
+        }
+        if (arg === "--stats" || arg === "--no-token-status") {
+            return true;
+        }
+    }
+    return false;
+}
+function hasExplicitPermissionOverride(args) {
+    if (process.env["LOCALPI_APPROVAL"] !== undefined) {
+        return true;
+    }
+    for (const arg of args) {
+        if (arg === "--") {
+            return false;
+        }
+        if (arg === "--no-approval") {
+            return true;
+        }
+    }
+    return false;
+}
 function hasExplicitThinkingOverride(args) {
     if (process.env["LOCALPI_THINKING"] !== undefined) {
         return true;
@@ -273,6 +379,9 @@ function hasExplicitThinkingOverride(args) {
     return false;
 }
 function startupModelSelectorOptions(options, connection) {
+    if (options.acp) {
+        return undefined;
+    }
     if (!process.stdin.isTTY || !process.stdout.isTTY) {
         return undefined;
     }