wisp

wisp is a small AI agent that runs on your Mac and stays there. It drives Apple’s on-device Foundation Model, the one behind Apple Intelligence, or a model you run locally in Ollama, MLX, llama.cpp, or LM Studio, and gives it tools: it can run a command, read and edit a file, report on the machine, and send you a notification. No prompt, file, or command output leaves the Mac, and there is no key, account, or bill.

It is for two kinds of user at once: a person at a terminal who wants a local assistant that cannot do anything behind their back, and a coding agent (Claude Code, Codex, any MCP client) that wants to hand the local chores to something cheaper than itself: run the tests and return the failures, condense a log, summarise a diff, scan a commit for secrets.

Two faces

Both open the same kind of session, with one configuration, one set of approvals, and one audit log.

The safety model, in five lines

1. A policy refuses what should never run (sudo, rm -rf /, piping into a shell, disk tools, a wisp agent of its own).
2. A Seatbelt sandbox confines every command’s writes to the directory wisp was started in, the temporary directories, and the build caches you configure; it can never write ~/.wisp. A command that cannot run sandboxed (brew upgrade) runs outside it only when you approve that one run, every time, or type it yourself after !!.
3. A risk classifier rates each simple command safe, moderate, or dangerous, rules first and a fast Core ML model beside them.
4. You are asked at moderate and above, and your answer has a scope you choose; silence is a refusal, and the agent that called wisp can never answer for you.
5. The audit log records every prompt, tool call, verdict, approval, and command outcome, verbatim, and every reply says what the turn actually ran.

Where to go next

wisp is open source, at github.com/pidster/wisp; every page here has an edit link to its source in the repository’s docs/ folder. The Changelog says what each release changed.

Install and first run

This guide takes you from nothing to a first answer, a first approval, and a conversation. The command reference has every flag; this page has the path through them.

What you need

Nothing else: no API key, no account, and no network for generation.

Install

brew install pidster/tap/wisp

That installs three things: wisp, wisp-tui (the terminal front end wisp chat hands a terminal session to), and MLX’s Metal library, mlx.metallib, beside wisp in Homebrew’s libexec, which wisp needs to run MLX models (ADR 0047). Homebrew also installs the shell completions for zsh, bash, and fish. The binary is unsigned; Homebrew does not quarantine what it downloads, so Gatekeeper does not stop it.

Upgrade with brew upgrade pidster/tap/wisp, remove it with brew uninstall wisp, and delete ~/.wisp to forget everything it kept (What wisp can do to your Mac, “Undoing”).

Check the install: wisp doctor

wisp doctor

wisp doctor checks what a working install needs and exits non-zero when anything fails: macOS 27, the on-device model answering a one-word request, the risk classifier, MLX’s Metal library, sandbox-exec, your config.json, and a writable ~/.wisp, along with the state wisp keeps. Each line is ok or not, with a detail. From a development build of 0.24.2 with a fresh home, on 2026-10-14 (a Homebrew install names its own paths):

ok   macOS: 27.0.0
ok   model: on-device model available and answers
ok   classifier: coreml model risk@0.24.2-default (shipped) prepares
ok   context window: 8,192 tokens, reported by the framework
ok   MLX: Metal library …/default.metallib loads
ok   sandbox: /usr/bin/sandbox-exec present
ok   config: no …/config.json; defaults apply
…
ok   home: … writable

A line that is not ok says what to do; Troubleshooting covers the common ones, and the reference lists every finding.

Ask it something

wisp "What is the date in Tokyo?"
wisp "What is listening on port 8080, and how much disk is free?"

A bare wisp "…" is wisp respond: one prompt in, one reply out, streamed. Under the reply wisp prints what the turn ran (ran: …), counted from its own audit log rather than from what the model says (What wisp checks beside a reply).

Some tasks change state. Running a project’s tests, for one, is a moderate action, and a one-shot wisp "…" has no way to ask you, so it refuses the command and the reply says so. Pass --yes when you mean it:

wisp --yes "Run the tests in $PWD and tell me if they pass"

--yes removes only the question. The deny list, the sandbox, the classifier, and the audit still apply (Approvals and the sandbox).

A conversation: wisp chat

wisp chat

On a terminal, with wisp-tui installed beside wisp (Homebrew’s install has it), wisp chat hands the session to wisp-tui: the conversation scrolls in your terminal’s own history above a pinned input and status line, and the model’s tool calls show as they happen. wisp chat --plain keeps the plain line-based chat, and a piped session is always plain. wisp doctor’s front end line says which you will get.

What to try first:

When the model asks to run a risky command, chat shows the level, the command, the directory, and the reasons, and asks once: [y]once [s]ession [p]roject 30d [a]lways 30d [n]o. What each answer covers is in Approvals and the sandbox.

Where wisp keeps things

Everything wisp keeps is in ~/.wisp, or in $WISP_HOME when it is set: an optional config.json, saved transcripts, remembered approvals, permanent facts, the audit log (logs/audit.jsonl), large tool outputs, and classifier versions. The reference lists every path. To try wisp without touching your real state, point WISP_HOME at a scratch directory:

export WISP_HOME=/tmp/wisp-scratch
wisp doctor

Next

• Let your coding agent use it: Delegating from Claude Code and Codex.
• A larger window and stronger tool use: Local models.
• One-job subcommands that need no prompt (wisp scan, wisp redact, wisp watch, wisp draft, wisp notify): the command reference.

Delegating from Claude Code and Codex

wisp mcp makes wisp an MCP server over stdio, so a coding agent can hand it the local work that would otherwise fill the agent’s own context: run the tests and return the failures, condense a log, summarise a diff, draft a commit message. The raw material stays on the Mac; the agent gets back something small. This guide sets it up and walks through the patterns that work. The MCP server is the reference for every tool, argument, result field, and resource.

Register the server

Claude Code reads .mcp.json in a project (or your user configuration):

{
    "mcpServers": {
        "wisp": {
            "command": "/opt/homebrew/bin/wisp",
            "args": ["mcp"]
        }
    }
}

Codex reads ~/.codex/config.toml:

[mcp_servers.wisp]
command = "/opt/homebrew/bin/wisp"
args = ["mcp"]

/opt/homebrew/bin/wisp is where Homebrew links it on Apple silicon; which wisp says where yours is. Restart the agent, or in Claude Code run /mcp, and the server’s tools appear: in Claude Code as mcp__wisp__respond and the like. Codex needs wisp 0.1.5 or later, which accepts the experimental capability Codex sends at start-up (The MCP server).

wisp mcp takes the flags respond and chat take (--model, --tool, --instructions, --no-tools, --yes, --unsafe), as defaults for every thread; a respond call can choose its own when its thread starts.

What the agent gets

wisp’s own tools (run_command, read_file, edit_file, system_info, and the rest) are not MCP tools. The agent reaches them only by asking respond, so every command runs as a turn of wisp’s model, under the policy, the sandbox, the classifier, your approval, and the audit (ADR 0006). The agent can read what the model can do from the wisp://tools resource (or wisp tools --markdown at a terminal), which gives each tool’s arguments, limits, and a prompt shape that works.

Threads

respond runs on a thread. Name one with thread_id and pass the same id to continue it; omit it and wisp makes one up and returns it. A thread is a conversation of its own, with its own facts, summary, and record; the server holds up to 32 (maxThreads), dropping the least recently used, and close_thread frees one when the work is done.

Five arguments shape a thread and are taken only when it starts; on an existing thread they are an error:

task (a sentence the model sees beside each request) can be given at any call, and schema shapes one reply.

Each result carries the reply and, in structuredContent, a receipt of what the turn did: ran (what was called, counted from the audit log), calls (each call, its output inline when small and otherwise a wisp://threads/{thread_id}/output/{id} reference), refusals, and verification, which names any result the reply reports that no call produced (What wisp checks beside a reply). An agent that checks ran and verification before trusting a reply catches a model that says it ran something it did not.

The condensing tools

The condensing tools need no thread and keep their input on the Mac. triage is the one to reach for first: given a command, it runs it through the same gate as run_command and returns a headline and the failures:

{ "command": "swift test 2>&1", "working_directory": "/Users/me/src/project" }

Most failures are read exactly from known formats (Swift and clang diagnostics, swift-testing, rustc, cargo test, pytest, go test), with no model turn at all; the model judges only what those do not explain (ADR 0039). Given path instead of command, it reads an output file already on the Mac. The other tools take the text, a path, or a command in the same spirit; each one’s arguments are in the reference, with what was measured of it.

Approvals reach you, never the agent

When the model inside respond wants to run something risky, wisp asks you two ways at once, and the first answer wins (ADR 0046):

• Your client’s dialog, when it supports MCP elicitation (Claude Code does). Accept runs the command with the scope chosen in the form; Decline refuses it.
• Another of wisp’s faces. The request waits in ~/.wisp/pending, and if the dialog has not been answered within 10 seconds (approval.bannerDelaySeconds) a notification names it: “wisp: approval needed”, with the command and wisp approvals approve <id>. Answer from any terminal, in a running wisp-tui, or with /approvals approve <id> in a plain wisp chat.

wisp approvals pending
wisp approvals approve a1b2c3d4 --scope session
wisp approvals deny a1b2c3d4

Nothing in the MCP conversation can approve a command, so the agent cannot answer for you: wisp’s own model is refused wisp approvals approve|deny by policy, and those commands run only with a terminal on standard input. A request nobody answers within approval.timeoutSeconds (600 s) is refused. The same channel carries a fact the agent asks you to keep (wisp facts keep|drop) and, when the thread has the ask tool, the model’s question to you (wisp questions answer|decline); an agent should tell you such an id and wait, never answer it itself. Approvals and the sandbox covers what is asked and what each scope covers.

A worked example: a thread for git

This repository runs every git command its agents issue through wisp, as a dogfooding rule (AGENTS.md, “Working through wisp’s MCP server”), so each one is classified, sandboxed, approved, and audited. The pattern suits any fixed, repeated job. Open one thread and reuse it:

{
  "thread_id": "git",
  "tools": ["run_command"],
  "model": "ollama:granite4.1:8b",
  "commandTimeoutSeconds": 600,
  "instructions": "You run git commands for a coding assistant. Run exactly the command line given between backticks, once, in the working directory given, with the run_command tool. Do not modify the command, add flags, or run anything else. Reply with the exit status and the output verbatim, and nothing else.",
  "prompt": "Use run_command with working directory /Users/me/src/project to run exactly the command line between the backticks:\n`git status --short`\nReport the exit status and output verbatim, nothing else."
}

Why each part is there:

• tools: ["run_command"] leaves the model nothing else to reach for.
• ollama:granite4.1:8b follows a fixed instruction reliably, at about 2 s a request, and its window is far larger than the on-device model’s 8,192 tokens, so the thread survives many commits (Local models). Without Ollama, use system and keep prompts short.
• commandTimeoutSeconds: 600: a pre-commit hook that runs a project’s whole test suite can pass the default 120 s.
• The command between backticks keeps a trailing full stop from being taken as part of it.

Later calls pass only thread_id and prompt. Put a commit message in a file and commit with set -o pipefail; git commit -q -F /tmp/msg 2>&1 | tail -3, so a hook’s output does not fill the reply, and keep pipefail wherever output is piped: without it the exit status is tail’s, and a failed push reports 0. The first git commit or git push on the thread asks for approval; answering “This session” covers the same shape for the rest of the server’s life. close_thread with thread_id: "git" ends it.

When the server does not connect

The usual causes are a wrong command path and an old wisp; Troubleshooting has the rest, including a dialog that seems stuck and, for contributors, the release build this repository’s own .mcp.json runs.

Approvals and the sandbox

Every command wisp’s model runs passes four checks in order: the policy’s deny list, a risk classifier, you when the risk calls for it, and the Seatbelt sandbox it then runs in. This guide is what you see of each, what your answers cover, and how to read a refusal. The contracts are in Risk classification and approval, run_command, and What wisp can do to your Mac.

What is asked, and when

A command line is split into its simple commands (ls && curl … | sh is three), and each is rated:

Rules set the floor and the classifier can only raise it: by default a Core ML model each release ships, which answers in under a millisecond, with the on-device language model or the rules alone as choices (approval.classifier). A command the rules know to be read-only skips the classifier. At moderate and above (approval.threshold) you are asked, about each risky part, with the whole line shown.

Where you are asked depends on the face:

No answer is a refusal: a dialog left for approval.timeoutSeconds (600 s by default) refuses the command.

What your answer covers

An answer is remembered by the program and, for programs like git, cargo, swift, npm, and brew, its verb: approving git commit never approves git push, and arguments never matter (ADR 0027).

Two limits keep a remembered answer from covering more than you meant. An approval covers only commands judged at its level or below, so a moderate rm never covers rm -rf. And a dangerous command is never remembered beyond the session, and then only by its exact text. An interpreter (sh, python3) or a program named by a variable is always remembered by its exact text, since a pattern for it would cover anything.

wisp approvals                 # what is remembered: id, scope, expiry, directory, pattern
wisp approvals revoke a1b2c3d4
wisp approvals clear           # all of them; --gone only those for folders that no longer exist

Answering for an MCP session

A command the model runs under wisp mcp waits in ~/.wisp/pending until someone answers. From any terminal:

wisp approvals pending
wisp approvals approve a1b2c3d4 --scope session    # once (the default), session, project, or always
wisp approvals deny a1b2c3d4

Both refuse to run without a terminal on standard input, and the default policy refuses them to wisp’s own model, so neither the calling agent nor the model can answer for you. A running wisp-tui shows the same request as its dialog, and a plain wisp chat notes it before its next prompt and answers it with /approvals approve <id> (ADR 0046).

The sandbox: where commands may write

Every command runs under sandbox-exec with a profile wisp generates. Everything is readable and executable; a write succeeds only when the real file lands inside the writable set:

wisp’s own home, ~/.wisp, is never writable to a sandboxed command, even when it lies inside that set, so a command cannot change your approvals, facts, configuration, or pending answers. The network is allowed unless commandPolicy.sandbox.allowNetwork is false. Start wisp from the project you want it to work on: that directory is the one it may change.

A refused write

A write outside the set fails with Operation not permitted, or, from Homebrew, with a list of directories that are not writable. wisp then checks the paths the error names against the writable roots and adds one line to what the model sees (ADR 0054):

So a refusal in a reply is either the policy (error: command denied by policy: …), you or silence (error: command not approved: …), or the sandbox (a sandbox: line). Troubleshooting covers the programs that cannot run sandboxed at all.

Outside the sandbox, one command at a time

Some chores cannot run in the sandbox whatever you widen: brew upgrade (Homebrew runs a sandbox of its own, which cannot nest inside wisp’s), cargo install (it writes ~/.cargo/bin), rustup update (~/.rustup). Two ways run one such command without the sandbox (ADR 0064):

• The model asks, with run_command’s outsideSandbox: true. The deny list still applies, and then you are asked about that exact line every time, whatever its level and your threshold, marked OUTSIDE the sandbox on every face. It is approved once or not at all: nothing remembers it, and --yes does not answer it. Where no person can be asked, it is refused.
• You type it in chat after !!: !!brew upgrade. Typing it is the approval, as for a command after a single !, which runs in the sandbox. In wisp-tui, ! at the start of a command line turns the input box from command mode’s amber to a muted red.

Either way the command may write anywhere you can, ~/.wisp included. Turn both off with:

wisp config set commandPolicy.sandbox.allowOutsideSandbox false

Switches that remove protection

Both flags print a warning on stderr.

What the audit log shows

Every step above is written to ~/.wisp/logs/audit.jsonl, verbatim and in order (Logging):

wisp logs --last 20
wisp logs --kind approval.decided          # every approval, and what it was remembered as
wisp logs --kind policy.decision --kind command.outcome --last 10
wisp logs --follow                         # as it happens, MCP calls included

Local models

wisp needs nothing beyond Apple’s on-device model, but that model has an 8,192-token window, and a long conversation or a large tool output fills it fast. A model you run locally gives wisp a larger window and, on the models measured, more reliable tool use, and it still runs on your Mac. This guide is when to add one and which; How to install local models has the steps for each runtime, and Model backends the reference.

When the on-device model is enough

For short questions, single commands, the condensing tools (several of which read their input exactly, with no model turn at all), and the risk classifier, the on-device model does well and costs nothing to set up. Add a local model when you see conversations condensed after a few turns, long tool outputs cut, or a multi-step task go astray; or when you delegate repeated work from a coding agent and want a thread to last many turns.

Which runtime

wisp has been tested against fake llama.cpp and LM Studio servers, not yet a real one (Model backends).

Which model, as measured

From the local-model comparison of 2026-10-04 on this project’s Mac (Measurements):

Not for tool work: llama3.2:3b, which writes tool calls as text and misses edits, and ministral-3:14b, which made no calls in that comparison.

A thinking model can be told not to think, which is often much faster: on 2026-10-10 granite4.2:8b without thinking ran at granite4.1:8b’s speed, where thinking made it 4 to 15 times slower, and still got every draft right.

wisp config set ollama.models.granite4.2:8b.think false

The shortest path: Ollama

brew install ollama
brew services start ollama
ollama pull granite4.1:8b
wisp models                                    # lists ollama:granite4.1:8b
wisp --model ollama:granite4.1:8b "What is listening on port 8080?"

Using a model

If chat’s configured model is unavailable as it starts (Ollama not running, say), chat starts on system and says so; a one-shot wisp "…" and an MCP respond fail with the reason instead, and never fall back.

Windows and memory

wisp sizes each Ollama and MLX model’s window when it is chosen, from the model’s shape and the Mac’s free memory at that moment, capped at the model’s maximum (ADR 0043). The same model may get a smaller window when memory is tight. wisp models shows each model’s window (CONTEXT) and how it was decided; to hold one model to a size:

wisp config set ollama.models.qwen3.8:27b.contextLength 16384

A llama.cpp or LM Studio model’s window is the one its server holds it at.

Turning models off

wisp models --all                          # every model, with the reason any cannot be used
wisp models disable ollama:llama3.2:3b     # hidden from /model and refused wherever a model is chosen
wisp models enable ollama:llama3.2:3b

The default model cannot be disabled until another is the default. Enabling an MLX or llama.cpp model whose capabilities are not declared checks them on the model first, and records what passes (ADR 0056).

Configuration

wisp runs with no configuration at all. When you want it to behave differently, the settings live in one optional file, ~/.wisp/config.json (or $WISP_HOME/config.json), which you can change from the command line, from chat, or by hand. This guide is a tour of what is worth changing and how; the reference lists every field with its default.

Look before you change

wisp config                     # every setting in effect, defaults applied, as JSON
wisp config list                # the settings `set` can change: each one's value or (default), and what it does
wisp config get approval.threshold

$ wisp config get approval.threshold
moderate	the default

The model’s inspect tool and the MCP resource wisp://config show the same view, read-only.

Change a setting

wisp config set model ollama:granite4.1:8b
wisp config set approval.timeoutSeconds 300
wisp config set routing.ladder system ollama:qwen3.8:27b     # a list: words, or a JSON array
wisp config unset approval.timeoutSeconds                    # back to the default

In chat, /config set and /config unset do the same, with Tab completing the settings and their values. Each change is checked before it is written: an unknown setting, a value the setting does not take, or a file that would no longer load is refused with the reason, and nothing changes. The rest of the file is kept as it is, and the file is written readable by you alone. Changes apply from the next session: a running chat keeps the settings it started with. A change that weakens the gate or the audit (the threshold at never or dangerous, the classifier at rules, the audit off) prints a note. Every change is audited as config.change.

wisp’s model cannot change its configuration: there is no tool for it, and its sandboxed commands cannot write ~/.wisp (ADR 0040). A command you approve to run outside the sandbox could, which is why you are asked about each one (ADR 0064).

The settings worth knowing

Editing the file by hand

Some settings are edited only by hand: the rest of commandPolicy (the deny and allow patterns, the sandbox’s writable paths and network), custom tools, and fact kinds. Partial objects are fine; anything you leave out keeps its default:

{
    "systemPromptExtension": "Prefer British spelling.",
    "commandTimeoutSeconds": 300,
    "commandPolicy": {
        "sandbox": { "writablePaths": ["~/Library/Caches", "~/.cargo/registry", "~/.cargo/git", "~/.npm"] }
    }
}

writablePaths replaces the default list, so repeat the defaults you want to keep. A malformed file, or an invalid commandPolicy pattern, is an error that names the problem (exit 64), and wisp doctor’s config line says whether the file parses. Unknown fields are ignored. Where each section is described:

Instructions, in three layers

What the model is told has three layers, in order (ADR 0017): wisp’s own system prompt, which you cannot change; your systemPromptExtension, for every session on this Mac; and a conversation’s own instructions, from --instructions on the command line or instructions when an MCP thread starts.

Environment

Troubleshooting

Start with wisp doctor. It checks what an install needs, exits non-zero when anything fails, and each line that is not ok says what is wrong; it is the first thing to ask for when someone reports a problem. Then find the symptom below. WISP_LOG=debug wisp … mirrors wisp’s own diagnostics to stderr, and wisp logs --last 20 shows what just happened (Logging).

The model

Restarting Apple’s model service

On 2026-10-13, after 26 days up, modelmanagerd ran out of open files: the model reported itself available, yet every request failed, from wisp and from Apple’s own fm alike. wisp doctor asks the model for a one-word reply rather than trusting the availability flag, and when the request fails with the service’s own error the finding says so and gives the fix:

sudo killall modelmanagerd

launchd starts the service again on the next request; restarting the Mac does the same.

Commands the model runs

The MCP server

The server fails to connect. Run the configured command yourself: /opt/homebrew/bin/wisp mcp (or whatever your command names) should start and wait silently for input; Ctrl-D ends it. A wrong path, or an old wisp, are the usual causes. Codex needs wisp 0.1.5 or later. Stdout is the protocol channel, so nothing is printed there; WISP_LOG=debug in the server’s environment mirrors its diagnostics to stderr.

In this repository (contributors), .mcp.json runs scripts/wisp-mcp, which runs the release build at harness/.build/release/wisp. When the server fails at start-up the cause is almost always that the build is missing: the launcher says wisp MCP server: no release build at …. Build it, then reconnect (/mcp in Claude Code):

scripts/check mcp-build

The build is also stale after code changes until it is rerun. Use scripts/check mcp-build, not a bare swift build -c release, which rewrites the lockfile (below).

An approval dialog seems stuck. The request also waits in ~/.wisp/pending, so answer it from a terminal; the notification named its id:

wisp approvals pending
wisp approvals approve a1b2c3d4        # or: wisp approvals deny a1b2c3d4

A running wisp-tui, or /approvals in a plain wisp chat, answers it too. Failing that, in Claude Code, /mcp reconnect wisp clears the dialog; retry the turn afterwards. A request nobody answers is refused after approval.timeoutSeconds (600 s), never run.

A reply ends [a question waits for the person: …]. The model asked you a question with its ask tool. Answer it yourself with wisp questions answer <id>, in wisp-tui, or with /questions answer <id> in chat; the answer reaches the thread’s next turn. The agent cannot answer it for you (ask).

State

For contributors: the lockfile and MLX

The release builds with --traits MLX, so harness/Package.resolved must pin the packages only that trait resolves (mlx-swift, mlx-swift-lm, swift-numerics, swift-syntax). Any build without the trait, a plain swift build among them, rewrites the lockfile without those pins. scripts/check puts the lockfile back after its own builds and refuses a commit whose lockfile lacks them. If yours lost them, restore it:

git checkout HEAD -- harness/Package.resolved

When the dependencies really changed, resolve with the trait (scripts/check mlx-build) so the new lockfile keeps the pins (Engineering standards).

wisp command reference

wisp runs Apple’s on-device Foundation Model with tools. It has eighteen subcommands (respond, chat, tools, models, mcp, logs, config, doctor, approvals, facts, questions, notify, scan, redact, watch, draft, classifier, completions), plus hidden maintainer ones under classifier; respond is the default, so wisp "<prompt>" works.

Subcommands

wisp respond [<prompt>] (default)

One prompt in, one reply out. The prompt is read from stdin when omitted and stdin is a pipe; on a terminal with no prompt, wisp prints its help instead of waiting for input.

wisp "What is the date in Tokyo?"
echo "Summarise this" | wisp --tool current_date
wisp --no-stream --instructions "Answer in French" "How are you?"
wisp --no-tools --schema verdict.json "Which language is this: fn main() {}"

wisp chat

Interactive session. Lines starting with / are commands; a line starting with ! is a shell command you run yourself (“Commands you run yourself”, below); anything else goes to the model. Replies stream.

With the ask tool on (tools.ask, or --tool ask; tools/ask.md) the model can ask you one question mid-turn: the chat shows it under ? the model asks, numbered options with none of these last, and waits for your line as long as you take (inquiry.timeoutSeconds sets a deadline); Enter alone declines, and Ctrl-C stops the turn as it does elsewhere (ADR 0062). wisp-tui shows the same question as a picker titled “the model asks”.

When the configured model (config.json’s model) is unavailable as chat starts, Ollama not running, say, chat starts on system instead and says so before the first prompt, so you reach /model:

ollama:granite4.1:8b is unavailable (no Ollama server at http://127.0.0.1:11434: Could not connect to the server);
using system. /model ollama:granite4.1:8b once Ollama is running

It is recorded as model.fallback (logging.md). A model named with --model is not replaced: chat fails as before, since you asked for that one, and so it does when system is unavailable or disabled too. wisp respond and MCP respond never fall back (ADR 0056).

On a terminal, when wisp-tui is installed beside wisp, or in a bin beside the folder wisp is in (the Homebrew formula installs wisp in libexec and wisp-tui in bin), wisp chat hands the session to it; wisp doctor’s front end finding says where it found it, or where it looked: the conversation scrolls in the terminal’s own scrollback above a pinned band with the reply in progress, an approval dialog, the input, and the status (ADR 0029). --plain keeps the line-based chat below; a piped session is always plain. wisp-tui takes the same arguments as wisp chat and can be run directly. It starts wisp chat --json under the name wisp chat (tui), which ps shows; wisp finds its own executable by the kernel’s path, never by that name (ADR 0061). In wisp-tui, Up and Down recall the lines submitted this session (the latest 100, a line repeating the one before it kept once): Up from a fresh line keeps what was typed as a draft, and Down past the newest line brings it back. In a message of several rows they first move the cursor a row, keeping its column; recall begins from the first row (Up) or the last (Down). Down from the last row of a fresh line moves the focus to the status bar (“The status bar”, below). The plain chat reads whole lines and has no recall; /history lists them in both. While a command you typed after ! runs, or a model’s turn, the first Ctrl-C (or Ctrl-D) stops it instead and a second quits (“Commands you run yourself” and “Stopping a turn”, below). Ctrl-C or Ctrl-D with nothing open leaves wisp-tui: it sends /quit (so the transcript is saved, as in the plain chat), closes wisp’s input, and waits up to five seconds for wisp to exit before stopping it. Anything wisp wrote to stderr that was not yet shown, such as why it could not start, is printed after the band is gone, and wisp-tui exits with wisp’s status when wisp failed (1 when it had to be stopped).

wisp-tui’s input edits in place, with readline’s keys:

Two keys open a panel over the band, a rounded border around up to 16 rows, with its keys in the bottom border: Up and Down scroll a row, PageUp and PageDown a page, and Esc (or the key that opened it) closes it. Typing is held while it is open; an approval or a choice arriving closes it and takes its place.

The status bar

The status row under wisp-tui’s input is a bar whose items open things (ADR 0029, amended 2026-10-12). Down from the input’s last row (an empty box or a one-line one is on its last row) moves the focus to its first item, the model; the row above the input then names the keys and what Enter does, and the input keeps its line and cursor, without the terminal’s cursor in it. The item with the focus is drawn in black on its own colour (amber for approvals).

The directory, the branch, and the approval mode are not items: there is no view of theirs to open.

A picker that opens over a line being typed (from the bar, or the one /model sends) puts the line aside and gives it back when it closes, so a typed answer starts empty and the draft is never lost. A dialog, a choice, or the panel that opens while the bar has the focus takes the keys, and the focus returns to the input once it closes. The bar takes the focus only between turns, with nothing open over the input; an item that goes while it has the focus (its last question answered elsewhere) passes the focus to the model.

A line you send goes into the scrollback styled like the input it came from, a shade darker: its tint edge to edge, halfway from the input’s blue to black, with half-block strips above and below.

Command mode is a state of wisp-tui’s input box (ADR 0049). Typing ! at the start of the line, into an empty box or in front of what you have typed, switches it to command mode: the ! is the switch, not text, the box turns a muted pale amber (command, #E8B577) with bold black text, its marker becomes !, and what you type is the command. A ! typed after other text, or at the start in command mode, stays text. Backspace with the cursor at the start of the line switches back to the normal prompt, keeping what you typed as ordinary text, so a stray ! costs one key; Delete in an empty box does the same. A paste that starts with ! at the start of the line enters command mode the same way. Enter runs the command and the box returns to the normal prompt; an empty command sends nothing. In the scrollback the command’s line is a stripe in a darker, faded shade of the same colour (commandSent, #745A3C) with light text, ! git status --short, as a prompt’s is the darker shade of the input. Up and Down bring a command back in command mode.

Outside mode is the step after command mode, for a command you run outside the sandbox (ADR 0064, amended 2026-10-14). Typing ! at the start of the line in command mode switches to it: the box turns a muted red (outside, #D27068, darker and greyer than the error colour) with black text, its marker becomes !!, and the hint reads Run a command yourself OUTSIDE the sandbox: it may write anywhere you can. A ! at the start in outside mode is text. Backspace at the start of the line (Delete in an empty box) steps back one mode, to command mode’s amber, and another to the normal prompt, keeping what you typed. A paste at the start of the line steps up a mode for each ! it starts with, as typing them does: !!brew upgrade pasted into an empty box enters outside mode with brew upgrade, and !x pasted at the start in command mode enters outside mode with x. Enter sends !!brew upgrade; its scrollback line is !! brew upgrade on the outside colour’s darker shade (outsideSent, #693834), and Up and Down bring it back in outside mode. Text in the normal box that starts with !! (pasted after a space, say) is not sent unseen: Enter puts the box in outside mode with the rest, and a second Enter sends it. A command mode line whose text starts with ! is sent as ! !x, so it runs in the sandbox as the amber box showed. The colours are a first proposal, not yet chosen from renders as command mode’s were.

While a turn runs, or a command you typed, the input box is inactive: dimmed, with what wisp is doing in place of the cursor, … working: read_file README.md or … working: waiting for the model; for a command you typed, which has no time limit, what it runs, for how long, and how to stop it, … running ollama pull hf.co/… · 42 s · Ctrl-C stops it, ticking each second, then … stopping … · Ctrl-C again quits once you have; a turn you stopped reads stopping the turn · Ctrl-C again quits until it ends. Keys typed meanwhile are held, not shown as typed and not lost: the box says how many (· 3 keys held), and they are applied in order when the turn ends, as if typed then (a held ! into the empty box enters command mode). Held keys only ever go into the input box: when the turn ends with an approval or a choice open, they stay held until it closes, so a letter typed ahead never answers a dialog. Enter is not held: a message is sent only once you can see it.

The input grows a row for each line or wrapped line of the message, up to six rows; beyond that it scrolls within them to keep the cursor’s row in sight. It shrinks back only once the input is empty, as it is when the message is sent, so deleting across a wrap does not resize the band as you type. The terminal’s own cursor marks where typing goes. ratatui fixes an inline band’s height when it is made, so the band is redrawn at the new height; after it shrinks it can sit a row or two above the bottom of the terminal until the next output closes the gap. Each frame is sent as one synchronized update, so a terminal that supports it (Ghostty, iTerm2, kitty, WezTerm, Alacritty) shows only finished frames, and lines are added above the band by scrolling a region rather than redrawing it. The band is redrawn only when something changes it (a line from wisp, a key, a paste, a resize), never while idle. Keys other than a dialog’s answers are ignored while an approval is asked; while a turn runs they are held, as above.

An approval takes the input’s place in the band: a rounded border in the level’s colour, titled with the level, around the command (wrapped to four rows), the whole line when the command is one part of it, the directory, each reason, the pattern the answer is remembered under, and the keys, as wisp chat offers them. Lines too long for the dialog end in an ellipsis. The answer is recorded in the scrollback as one line, ⚠ approved for this session: git push or ⚠ refused: …, and the band gives the rows back to the input. Ctrl-C or Ctrl-D refuses. A dialog takes its keys only once the keyboard has been quiet for half a second after it appears: a key pressed sooner was meant for the input (you were typing when it came up), so it is held for the box, as keys are while a turn runs, and the half second starts again. Typing on therefore never answers a dialog; pausing to read it, then pressing a key, does. Ctrl-C refuses at once. An approval from wisp mcp that arrives while the input box has text does not take the box over: a note says it waits (⚠ waiting in wisp mcp: git push · its dialog opens when the input is empty, or from the status bar), the status bar counts it (approvals: 1, in amber), and its dialog opens once the box is empty, when the line is sent or cleared, or at once from the status bar’s approvals item, the line you were typing kept. An approval or a choice that stops waiting (answered elsewhere, or its approval.timeoutSeconds passed) closes with ⚠ no longer waiting: ….

The plain chat (--plain, or wisp-tui not installed) has no dialog for these, since it reads a line at a time. Before each prompt it notes, once, each request newly waiting in a wisp mcp server, a command to approve, a fact to keep, or a question the model asks (tools/ask.md), with its id; the first of each kind also says how to answer:

⚠ a1b2c3d4 waiting in wisp mcp (claude-code, thread git): run git push origin main in ~/src/wisp, moderate
  answer with /approvals approve ID [once|session|project|always] or /approvals deny ID
⚠ 5e6f7a8b waiting in wisp mcp (claude-code, thread docs): keep as a permanent fact entity release codename = BLUE HERON, from model
  answer with /facts keep ID or /facts drop ID
? 9c0d1e2f waiting in wisp mcp (claude-code, thread git): the model asks: Which config? (~/.wisp | ./wisp.json)
  answer with /questions answer ID, which prompts for the answer, or /questions decline ID

A command the model asked to run outside the sandbox is noted as run brew upgrade OUTSIDE THE SANDBOX, this once, in ~/src/wisp, moderate, and /approvals approve approves it once whatever scope you give, as wisp approvals approve does (ADR 0064).

/approvals approve, /approvals deny, /facts keep, /facts drop, /questions answer, and /questions decline answer one (without an id, they offer what waits to choose from), and /approvals pending lists everything waiting. /questions answer shows the question as wisp questions answer does and reads your answer at its own prompt, a number or an option for a choice, a line of text otherwise, Enter alone writing nothing, so the answer is never part of a command line you typed. A request is noted only between prompts: one that arrives while you are at the prompt is noted once you press Enter (an empty line will do), and its notification announces it meanwhile. A request seen before and gone now is noted once with how it ended, read from the audit log: · a1b2c3d4 no longer waiting: answered in wisp-tui (git push origin main), answered in the client's dialog, its wait ran out unanswered, withdrawn: its server stopped, for a question answered in wisp questions or declined in wisp-tui from its inquiry.settled, or, when the log has no word of it, answered elsewhere or withdrawn. One you answered in the chat is not noted again. The answer goes through the same checks as wisp approvals and wisp-tui (still waiting, the right kind, bound to what was shown, the first answer winning), is written with via chat, and is audited as approval.answered (inquiry.answered for a question) on the chat’s own session; a fact whose server has stopped is kept by the chat itself, as wisp facts keep does. As with wisp approvals, the chat answers only when its standard input is a terminal, so an agent piping lines into wisp chat --plain cannot answer for you; such a chat still notes what waits, and says where to answer. The commands are typed lines, never the model’s: no tool reaches them (ADR 0046, note of 2026-10-12). In wisp-tui the same commands answer from its input, written with via tui; its dialog stays the usual way, and /questions answer there points to the question’s picker, which already shows it (/questions decline declines from the input).

A choice, such as /config set approval.classifier without a value, takes the input’s place the same way: a border titled choose around the question, up to eight options with ▸ on the highlighted one and * on the value in force, and the keys. Up and Down move, Enter chooses, and Esc or Ctrl-C leaves the setting as it was. Where the setting takes a typed value (a number, text, a model not listed), a row below the options takes typing, and Enter with something typed sends that instead. In the plain chat the same choice is a numbered list: type a number or a value, or press Enter to leave it; a line starting with / leaves it too.

Replies are rendered as each line goes into the scrollback, in the little Markdown the model writes: # headings in bold, -, *, and + bullets as •, and `code`, **strong**, and *emphasis* styled with their markers removed. A fenced block keeps its lines as they are, in the code colour, with the fences dimmed; a fence left open closes at the end of the turn. Anything that is not clearly markup, such as 2 * 3 or snake_case, is left as typed. The line still being streamed is shown raw until it is complete.

Commands you run yourself

A line that starts with ! is a command you run, not a message: ! git status --short and !git status --short both run git status --short in the conversation’s working directory, as run_command would, with its output bound (the tail of each stream) but no timeout, and no model turn starts (ADR 0049, amended 2026-10-09). A long command (! ollama pull …, a build) runs until it ends or you stop it: Ctrl-C while it runs, in the plain chat and in wisp-tui, sends its process group SIGTERM and, two seconds later, SIGKILL, so whatever it started stops too; its line then reads ↳ exit -15 (stopped by you) and the chat goes on, the model told of it as of any command you ran. Ctrl-C does not quit chat while such a command runs; a second one, while it is still stopping, kills it at once and quits, as a second Ctrl-C does during a model’s turn; at the prompt Ctrl-C quits. While it runs the plain chat’s working line says … 42 s · running ollama pull … · Ctrl-C stops it, and after the first Ctrl-C notes stopping ollama pull …; Ctrl-C again quits. Esc does not stop it, as it does not stop a turn. If wisp-tui quits or closes wisp’s input while one runs, wisp kills it, so none outlives the chat. A bare ! runs nothing and says so. A ! inside a message is text. wisp-tui has a command mode for it (above); the plain chat, which has no box, colours the line’s prompt marker in the command colour once you press Enter.

A line that starts with !!, the two marks together, is a command you run outside the sandbox (ADR 0064, amended 2026-10-14): !!brew upgrade and !! brew upgrade run brew upgrade without wisp’s Seatbelt profile, for the chores the sandbox refuses (Homebrew, cargo install, rustup update). Typing it is the approval, as for !: nothing asks, nothing is classified. The policy’s deny and allow lists still apply, and so do the output bound, no time limit, and Ctrl-C. It may write anywhere you can, ~/.wisp included. Before it runs chat says ! running OUTSIDE the sandbox, as you typed it: it may write anywhere you can, and the plain chat colours the line’s prompt marker in the outside colour; wisp-tui has outside mode for it (above). With commandPolicy.sandbox.allowOutsideSandbox false it is refused, · blocked by policy: running outside the sandbox is turned off here (…); type it after a single ! to run it in the sandbox. With the sandbox off, or wisp inside another sandbox, it runs as a ! command does and says · !! changes nothing here: …. Only the two marks together count: ! !x, with a space, runs !x in the sandbox. !! alone runs nothing. !! is not the shell’s history, which sh -c does not keep. The model’s notice says you ran it outside the sandbox, and the audit marks it (outsideSandbox: true on policy.decision, command.outcome, and command.typed).

Stopping a turn: Ctrl-C while the model is working, in the plain chat and in wisp-tui, stops the turn (ADR 0049, amended 2026-10-11). The request to the model is cancelled (a local runtime’s connection is closed, MLX’s generation cancelled; Apple’s models stop at their next words), and a run_command the model started in the turn is stopped as a command you typed is: its process group gets SIGTERM, and SIGKILL two seconds later. Chat notes stopping the turn; Ctrl-C again quits, then stopped by you, and returns to the prompt; a second Ctrl-C while it is stopping kills what the turn still runs at once and quits. The conversation keeps what you asked and what ran, each call with its output (a stopped command’s says so), and no reply; the model sees that on its next request. The stop is audited as turn.stopped. Esc does not stop a turn.

The checks that protect the Mac stay; the ones that stand in for you go:

What the command printed (stdout, then stderr) is shown as a tool’s output is: ↳ exit 0, then up to shownOutputLines lines and the fold line, … 84 more lines, 3210 bytes in all: /show 8a7b6c5d, which /show and /last (or Ctrl-O in wisp-tui) print whole, from the output store when it was larger than the tool-output budget (command.typed names the stored output in stored). The model is told on its next request, as a reference after the turn: one entry, [the person ran `git status --short` themselves in /Users/me/src/wisp (exit status 0, 4 lines); this was not your action; …], with the output itself when it is short (320 bytes or less), or its first and last lines and, with memory (tools/memory.md), memory "recall entry 7" to read the rest (without it, its output is not repeated; do not run it again to see it). It is never presented as something the model did. Facts are taken from the output as from run_command’s (the working directory, a test result, the git branch), as observations ranked with a tool’s and named as your command, so a later run of the same command, yours or the model’s, replaces them; what you state with /fact still outranks both. A command that was refused is audited and not told to the model.

Each command runs in its own shell, as the model’s do: !cd elsewhere does not change the conversation’s directory. respond over MCP does not interpret !; there the prompt goes to the model as text.

What a session shows, and where it goes:

• A banner with the version, model, tool count, and audit session, then a status line above every prompt, in two halves:

  • On the left, system:15% used · ~/src/wisp:main+12-3: the model and how much of its window the conversation uses (amber past 80%), then the directory, its git branch, and the lines added (green) and removed (red) in tracked files since the last commit, staged or not.
  • On the right edge, the approval mode (approve at moderate, never asks, --yes).

  Each part is omitted when unknown. Before a repository’s first commit there is nothing to count, so a change shows as *. GitState reads the branch from .git/HEAD and the counts from git diff --numstat HEAD, with a two-second cap. wisp-tui shows the same left half. Its right half starts with what waits for you, questions: 1 and approvals: 2, each only when there are some, then adds the last turn and its tokens, approve at moderate · last:3.1s · ↓4,009 ↑79, with tokens read (↓) in pale yellow and written (↑) in pale blue, or the working line while a turn runs. When the row is too narrow, parts go in turn: the directory shortens to its last folder, then the approval mode and the turn go, then the directory, then the context gauge; what waits stays. Its items take the focus (“The status bar”, above).

• The model’s tool activity as it happens, one dim line per call and result, from the same events the audit log records: ⚙ run_command git status, then ↳ exit 0; ⚙ read_file README.md, then ↳ 2048 bytes in 0.0 s: 1\t# wisp.

• Under each result, the output itself, as the tool returned it, indented and in the quiet tone: up to shownOutputLines lines (20; a setting) and at most 2 KiB, then, when there is more, … 84 more lines, 3210 bytes in all: /show 8a7b6c5d. /show with that id (the start of the output’s tool.result audit event id) or with its store entry id prints the output whole, and /last the last one: the stored whole when the model was given only part of it (/show, below). You see the real output rather than the model’s copy of it, and the model is told so, so its reply comments on the output instead of retyping it (decision D12 of the layered-context proposal). Like the tool lines, the output goes to stderr.

• The model’s thinking, for a reasoning model that reports it (Ollama streams it for qwen3.8:27b, gemma4:12b, gemma4:26b, ornith:9b and others; ADR 0053): when it stops thinking, a dim line ∴ thought for 4.2 s, 42 tokens, and the thinking under it folded as a tool’s output is, with /show and the id on its fold line for the rest. It is kept for you: no request carries it back to the model, and the model’s memory does not recall it. /inspect thinking shows every stretch the conversation kept.

• What the gate decided for each command, under its call:

  • its rating: · safe by rules: a known read-only command (0.2 ms), or (remembered) when the session reused an earlier verdict;
  • how it was let through: · approved (session), · allowed by your approval for this session, or · allowed by your standing approval;
  • or why it was not: · denied, · no answer in time, denied, · blocked by policy: …. A task routed to a model says so: · secrets runs on system: ….

• While a turn runs, a dim line that says what it is doing and for how long, redrawn each second on a terminal: … 12 s · running git status (8 s), … 3 s · waiting for the model, and while a reasoning model thinks, … 9 s · thinking (6 s) (ADR 0053); the plain chat keeps to this one line, which it redraws in place, rather than an animation. It is erased before anything else is written, and is not drawn while a reply is streaming or an approval is asked.

• Under each reply, what the turn actually ran, counted by wisp from the turn’s audit events, never from the reply (ADR 0051): ran: read_file ×2 · run_command ×10 (2 failed, 1 denied) · edit_file ×3 · notify. Tools are in the order of their first call, with a count above one; failed is a non-zero exit status, a timeout, a command that could not start, or a tool error; denied (by the policy) and declined (by you, or no answer in time) are counted apart, since those never ran. At most six tools are named, then +N more. A turn that ran no tool shows nothing, unless its reply names one of the conversation’s tools, when it shows ran: no tools. A command you typed after ! is not a turn and has no line.

• Beside it, when the reply cites entries in wisp’s reference forms (entry 19, memory "recall entry 7", entries 16-30, entries 19, 20 and 21) that the conversation does not hold, a muted line names them: cited but not in this conversation: entries 19–30 (12) (ADR 0055). Ranges are expanded up to 100 numbers in all, and the line says when it checked only those.

• After both, when the reply reports a result that no call in the turn produced (a tool written in call form with a result beside it, a command said to have run, an exit status, a denial, a test or build outcome, a notification posted, a file removed, output quoted, a count), a muted line quotes the first such claim and says why: unsupported: "Removed the scratch file." (no rm, rmdir, unlink, or trash command ran in this turn) +1 more (verification.md, ADR 0060). It is checked by exact readers against the turn’s complete call list from the audit log, with each call’s whole output; verification.mode (readers by default, model, off) adds a model step or turns it off. A verified reply shows no line.

• Under each reply, how long the turn took and, when the model reports usage, the tokens it read and wrote across the turn’s requests: 3.1 s · ↓4,009 ↑79. wisp-tui puts the same figures in its status line. The count is the agent’s running total across every session it has used, so a turn in which wisp replaced the model’s session (references, condensing, an overflow retry) is still counted in full; /new keeps the total. /tokens is a different figure: the size of the transcript.

• Replies on stdout; everything else (banner, status, prompt, tool lines, notes, approval dialogs) on stderr, so wisp chat > transcript.txt captures only the replies.

• Colour when stdout is a terminal, from wisp’s palette (Style.Palette, shared with wisp-tui‘s palette.rs; scripts/check palette fails the gate if they differ): one green-blue in tones: the brightest for the prompt, the git branch, tokens written, and a context from half to 80% used; the main tone for status facts and ok states; a quiet tone for tool lines, notes, separators, and a context under half used. Amber marks approvals, moderate, and a context past 80%; ember marks dangerous and errors; green and red mark lines added and removed; pale yellow marks tokens read; a muted pale amber (command, apart from the approvals’ amber) marks a command you typed: the plain chat’s prompt marker, and wisp-tui’s input box in command mode, whose scrollback stripe is its darker shade (commandSent); a muted red (outside, darker than ember) marks one typed after !!, to run outside the sandbox, in the same places, with its darker shade (outsideSent). White is for the conversation, bold for your own words. Colour is off when piped, when NO_COLOR is set, or when TERM is dumb.

/stats counts two kinds of call. A turn is one message through the conversation’s model until the reply; the framework runs the tool loop inside it, so its time includes the tools the model called and any approval it waited for, and a turn that ends in an error counts as failed. A classifier call is one risk classification by the model classifier approval.classifier names (system-model or coreml); it fails when the classifier could not judge and fell back to moderate. The rules classifier is not timed: it answers in microseconds, and a command on its read-only list never reaches the model classifier, so it is not counted. The store is a fixed-size ring in the session’s memory, shared by every conversation of the session including /model switches; nothing is written to disk, and the audit log (seconds on response and classifier.verdict) is the durable record.

When the model wants to run a risky command, chat asks on stderr with a compact dialog: the level and command, the whole line when the command is one part of it, the directory, each reason on a line (shortened to 110 characters), the pattern the answer is remembered under, and one key line: [y]once [s]ession [p]roject 30d [a]lways 30d [n]o. y approves it for the rest of this turn, s for the session, p for this project (30 days, this directory), a always (30 days, anywhere); n, an empty answer, or end of input refuses it (approval.md). A command the model asks to run outside the sandbox opens ⚠ approve OUTSIDE the sandbox, says never remembered, and offers only [y]once [n]o: it is asked every time, whatever its risk (tools/run_command.md).

Status lines and the > prompt go to stderr, replies to stdout, so wisp chat 2>/dev/null prints only what the model said. A turn is one message from you and everything the model does to answer it.

Headless chat: wisp chat --json

--json replaces the terminal with JSON Lines on stdin and stdout so another program can be the face while the session, tools, gate, and audit stay in this process. The wisp-tui front end in tools/ drives it (ADR 0029). One object per line, type names it; a front end ignores types and fields it does not know, so new ones can be added without breaking it.

Out, to the front end:

In, from the front end: first, optionally, {"type":"hello","effects":["approve","notify"],"client":"wisp-tui","version":"0.15.0"}, the host effects the front end carries (ADR 0044). approve: it answers approval lines; a hello without it has every approval denied without being asked. notify: it posts notifications itself, so wisp sends notify lines and never writes to the terminal. approve-mcp: it also answers commands waiting for approval in wisp mcp servers, so wisp lists ~/.wisp/pending every half second and sends each as an approval line with source: "mcp", and a withdrawn line when it no longer waits. keep-facts: it also answers requests from wisp mcp callers to keep a fact as a permanent fact, sent the same way as approval lines with kind: "fact". answer-questions: it also answers the model’s questions waiting in wisp mcp servers, sent as choice lines with kind question and source: "mcp" (ADR 0062). Unknown effects are ignored; client and version are for the audit (host.hello). A front end that sends no hello keeps the behaviour from before it existed: approvals over the protocol, notifications posted by wisp’s own process (never through the terminal, which the front end owns). wisp-tui sends approve, approve-mcp, keep-facts, and answer-questions, and notify when its terminal has a notification sequence (Ghostty, iTerm2, WezTerm, kitty). It queues an approval that arrives while another is shown (and one from wisp mcp while its input box has text, with a note and approvals: N in the status bar, which opens it), and marks one from wisp mcp in the dialog: “waiting in wisp mcp for claude-code, thread git”, and “· wisp mcp” in its title. A fact to keep is a dialog of its own, titled “keep as a permanent fact? · wisp mcp”, answered with k (keep) or d (drop); Ctrl-C drops it, as it refuses a command. Then {"type":"message","text":"…"} for a chat line, slash commands included; a text that starts with ! is a command the person runs, exactly as a line typed in the plain chat (ADR 0049). wisp-tui sends what is typed in command mode this way, {"type":"message","text":"!git status"}, so the protocol needs no type of its own for it and a front end without a command mode can still run one; a text that starts with !! is a command the person runs outside the sandbox, which wisp-tui sends from outside mode, {"type":"message","text":"!!brew upgrade"} (ADR 0064, amended 2026-10-14). No turn lines follow: the command’s audit events arrive as event lines (policy.decision, command.outcome, command.typed with the output), then status. While it runs, {"type":"interrupt"} stops it (Ctrl-C in wisp-tui): its process group gets SIGTERM, then SIGKILL two seconds later, and a second interrupt kills it at once; command.outcome and command.typed then carry stopped: true. During a model’s turn interrupt stops the turn as Ctrl-C does in the plain chat (“Stopping a turn”, above), and a second kills what it still runs. With nothing running, interrupt does nothing. When wisp’s input closes while a command or a turn runs, what it runs is killed. Then {"type":"output","id":"…","session":"…","page":2} asks for a page of a tool’s output whole, answered with a view of kind output, beside the loop like a completion: id is the event’s (an event’s output.id, or a view’s id), session the audit session a view named (absent for the conversation’s own), page from 1 (absent, 1). wisp-tui sends one when Ctrl-O opens the panel and as it scrolls past the pages it holds. Then {"type":"answer","id":"…","decision":"once|session|project|always|no"} for an approval (keep or drop for a fact to keep), and {"type":"choose","id":"…","value":"…"} for a choice, with value null or absent for no answer, or for a choice with toggles {"type":"choose","id":"…","values":["system","ollama:granite4.1:8b"]}, the values left on; without values nothing changes, so a front end that answers it as a plain choice changes nothing, and {"type":"complete","id":"…","text":"…","cursor":N} to ask for completions of the input at Unicode scalar N, answered by completions even while a turn is not running; completion comes from the same list of settings and values as /config, and the models this Mac can run are looked up once per session. A line that is not a JSON object is taken as a message, so the protocol can be driven by hand; a JSON object of a type wisp does not know is ignored (and reported once on stderr under WISP_LOG), so a newer front end’s line never arrives as an empty message:

printf 'What is the date in Tokyo?\n/quit\n' | wisp chat --json

Everything else about the session is as for the terminal chat: the same flags, transcripts, and audit. Only the presentation moves out of the process.

The order in which the lines pass, from the banner to exit:

sequenceDiagram
    participant tui as wisp-tui
    participant wisp as wisp chat --json
    tui->>wisp: hello, optional: approve, notify
    wisp->>tui: note: the banner and the help line
    loop until /quit or end of input
        wisp->>tui: status
        tui->>wisp: message
        alt a slash command
            wisp->>tui: output lines, or a choice
            tui->>wisp: choose, for a choice
        else a line starting with !
            wisp->>tui: activity, event lines with the output, activity null
        else a chat line
            wisp->>tui: turn, phase start
            wisp->>tui: event and delta lines, interleaved
            opt a risky command
                wisp->>tui: approval
                tui->>wisp: answer
            end
            opt a notification, when hello declared notify
                wisp->>tui: notify
            end
            wisp->>tui: an empty output line ends the reply
            wisp->>tui: turn, phase end
        end
    end
    wisp->>tui: exit
    Note over tui,wisp: complete and completions may pass at any time

wisp tools

On a terminal, lists the registered tools the way wisp --help lists subcommands: a TOOLS: heading, each name in a column, its description wrapped to the terminal’s width (from the terminal, else COLUMNS, else 80), and a pointer to the full catalogue:

TOOLS:
  current_date  Returns the current local date and time.
  run_command   Runs a shell command on this Mac and returns its exit status
                and output. Use it to build or test software, list or read
                files, and inspect the system.

  See 'wisp tools --markdown' (or --json) for parameters and example prompts.

Piped or redirected, it prints one name<TAB>description line per tool, for scripts. --json prints the full catalogue (description, JSON Schema arguments, limits, example prompt) and --markdown the same as Markdown; these are the texts served to MCP clients as wisp://tools and wisp://tools.md. See tools/.

wisp logs

Shows the audit log (~/.wisp/logs/audit.jsonl and rotated files) as one-line summaries, oldest first.

See logging.md for the event catalogue.

wisp models

Lists the models --model and config.json can use, with everything wisp knows about each: Apple’s two, then every model each local backend serves, each shown only if it can serve a conversation. That is decided by logic, not a list of names: the model must resolve (installed, reachable, entitled, and able to converse; an Ollama model that does not report completion, such as an embedding model, cannot) and must declare tool calling, since a conversation has tools. The listing also shows what you can turn on: every disabled model, and, in a build with MLX, every complete mlx-community model in the Hugging Face cache that the MLX models folder does not link yet. A backend that does not answer gets one line in parentheses. The configured default is marked * (ADR 0056).

A column no listed model has a value for is left out, and an empty cell stays empty. On a terminal the table is fitted to its width (from the terminal, else COLUMNS, else 80): when the columns do not leave the last 20 cells, FORMAT goes first, then RUNTIME, FROM, WHERE, PARAMS, SIZE, and CONTEXT; MODEL, ENABLED, and CAPABILITIES always stay, and the capabilities wrap under themselves. Rendered by the tests from a listing with a model of each runtime, at 120 columns:

  MODEL                 PARAMS  SIZE      CONTEXT  FROM    WHERE                 ENABLED  CAPABILITIES
  system                                  8,192    model                         yes      tools, structured replies,
                                                                                          vision
* ollama:granite4.1:8b  8.8B    5.35 GB   65,536   memory                        yes      tools, structured replies
  ollama:qwen3.8:27b    27.3B   17.74 GB  32,768   memory                        no       tools, structured replies,
                                                                                          thinking
  mlx:Qwen3-1.7B-4bit           984 MB    40,960   memory  HF cache              yes      tools, structured replies
  mlx:Qwen3-4B-4bit             2.26 GB                    HF cache, not linked  no

At 80:

  MODEL                 SIZE      CONTEXT  ENABLED  CAPABILITIES
  system                          8,192    yes      tools, structured replies,
                                                    vision
* ollama:granite4.1:8b  5.35 GB   65,536   yes      tools, structured replies
  ollama:qwen3.8:27b    17.74 GB  32,768   no       tools, structured replies,
                                                    thinking
  mlx:Qwen3-1.7B-4bit   984 MB    40,960   yes      tools, structured replies
  mlx:Qwen3-4B-4bit     2.26 GB            no

Piped, each model is one tab-separated line with every column, in the order above, whether or not it has a value, so a field is at the same position on every line; the name comes after * or two spaces, and a model that cannot be used has its reason as one more field. --json is the form for scripts: models, one object per model with a field per column (model, runtime, parameters, size and bytes, format, context as a number, contextFrom and contextNote, location as modelsFolder, hubCache, or hubCacheNotLinked, enabled, capabilities, and capabilitiesFrom, how they are known: verified 2026-10-04, config, runtime, or framework), default, usable, and problem, absent facts null; and unreachable, the backends that did not answer.

With --all on a terminal, a model that cannot be used has an empty capabilities cell and its reason on the lines under it, indented and wrapped to the full width; piped, the reason is the last field:

  MODEL         SIZE      ENABLED  CAPABILITIES
  ollama:embed  274.3 MB  yes
    not usable: it cannot hold a conversation

private-cloud is refused from every unsigned build; see backends.md, “Private Cloud Compute”.

wisp tools --markdown and --json include a Measured: line, or a measurements field, for each tool the eval harness has measured (measurements.md).

wisp models is wisp models list; its other subcommands turn models on and off, check what a model can do, and fetch a model.

wisp models enable|disable <name>…

Turns models on and off, by the names --model takes. A disabled model is not offered by /model, Tab, or /config set model, and is refused wherever a model is chosen: /model, --model, config.json’s model, and an MCP caller’s respond model, each with model 'X' is disabled; enable it with wisp models enable X, or /models enable X in chat. The listing still shows it, with ENABLED no. The default model (config.json’s model, or system when it names none) cannot be disabled until another is made the default, so wisp never starts on a model it refuses; a config.json that disables its own default does not load.

A model is refused however it is spelled: ollama:x and ollama:x:latest are one model, as are a llama.cpp model’s file name and its .gguf path, and an MLX or Core AI model’s name and the absolute or ~ path of its directory (links resolved); enabling or disabling one spelling changes the model.

The list is models.disabled in config.json; each change is a config.change with source cli (/models enable|disable and the wisp-tui picker record chat), and the rest of the file is kept. A chat applies its own change at once; other running processes, such as a wisp mcp server, from their next session.

Enabling a complete MLX model in the Hugging Face cache that is not linked links it, as wisp models pull would with nothing to fetch: no request is made, so nothing is asked, and it says what it linked to what. It is recorded as model.pull with outcome linked.

Enabling an MLX model whose capabilities config.json does not declare (mlx.models.<name>), whether it was disabled, not linked, or already enabled, links it if need be and then checks what it can do, as wisp models check does, recording what passes. It says what will run before it starts and asks nothing. The check decides the enabling:

A model the file already declares is not checked again. A llama.cpp model is checked as an MLX model is, and what passes is recorded under llamacpp.models.<name>, since llama.cpp does not say which models call tools; Ollama, LM Studio, Core AI, and Apple’s models report their own capabilities.

$ wisp models disable ollama:nomic-embed-text:latest private-cloud
disabled ollama:nomic-embed-text:latest: hidden from /model and refused until enabled
disabled private-cloud: hidden from /model and refused until enabled
$ wisp models enable mlx:Qwen3-4B-4bit
linked mlx:Qwen3-4B-4bit: ~/.wisp/models/mlx/Qwen3-4B-4bit → …/snapshots/<revision> in the Hugging Face cache; nothing was downloaded
mlx:Qwen3-4B-4bit is enabled
$ wisp models disable system
Error: system is the default model, so it cannot be disabled; make another model the default first (config.json's model: wisp config set model <name>, or /config set model in chat)

wisp models check <name>…

Checks what MLX and llama.cpp models can do, on the models themselves, and records it in config.json (ADR 0056, refined 2026-10-04). It loads the model and asks three short questions, each once, greedily, within a time limit:

reasoning and vision are not checked, and the output says so; declare them by hand if the model has them. The capabilities that pass are written under mlx.models.<name> with the check, verified (date, passed, failed), recorded as model.verified and config.change (logging.md), and used by a chat that ran the check at once. check reports and records only: it does not turn a model on or off, as enable does. A check replaces what an earlier one recorded: a capability it passed before and fails now is taken out. A capability you declared by hand is kept when its check fails, and the output says so. enable runs the same check on a model with nothing declared. Measured on this Mac on 2026-10-04 (an enable, in a scratch home; the times are that run’s, and the lines are as this version prints them, which puts enabled after the check that decided it):

$ wisp models enable mlx:Qwen3-1.7B-4bit
checking mlx:Qwen3-1.7B-4bit: loads the model (968.1 MB) and asks three short questions (a reply, a tool call, a structured reply), allowing 3 min for the first, which loads it, and 60 s for each of the others
  reply: passed in 2.3 s
  tool calling: passed in 0.4 s
  structured reply: passed in 1.4 s
recorded in config.json: mlx:Qwen3-1.7B-4bit can do tools, structured replies (verified 2026-10-04)
enabled mlx:Qwen3-1.7B-4bit
reasoning and vision are not checked: one short question cannot tell them reliably; declare them in config.json if the model has them

{ "mlx": { "models": { "Qwen3-1.7B-4bit": {
  "capabilities": ["toolCalling", "guidedGeneration"],
  "verified": { "date": "2026-10-04", "passed": ["toolCalling", "guidedGeneration"], "failed": [] } } } } }

A model whose runtime reports its capabilities (ollama:, coreai:, system, private-cloud) is not checked: check says so. A failed question says why, such as tool calling: failed in 1.3 s (no call to record_word arrived) or (no answer within 60 s).

wisp models pull <repository> [--trust-publisher]

Fetches an MLX model from Hugging Face, <organisation>/<name>, into the Hugging Face cache and links the MLX models directory (mlx.modelsDirectory, default <home>/models/mlx) to it, after asking. The cache is huggingface_hub’s, shared with Hugging Face’s own tools: HF_HUB_CACHE, else HUGGINGFACE_HUB_CACHE, else $HF_HOME/hub, else $XDG_CACHE_HOME/huggingface/hub, else ~/.cache/huggingface/hub. A file already there is not fetched again. The pull lists the repository, says per file whether the cache has it, and, when anything is to be downloaded, waits for y; anything else fetches nothing:

$ wisp models pull mlx-community/Qwen3-1.7B-4bit
mlx-community/Qwen3-1.7B-4bit at 0123456789ab: 7 files, 938 MB
  config.json            1 KB    already in the Hugging Face cache
  model.safetensors      938 MB  to fetch
  …
Snapshot: /Users/you/.cache/huggingface/hub/models--mlx-community--Qwen3-1.7B-4bit/snapshots/0123…
Link: /Users/you/.wisp/models/mlx/Qwen3-1.7B-4bit to the snapshot, as mlx:Qwen3-1.7B-4bit
Fetch 6 of them, 938 MB? [y/N]

(The revision, file count, and sizes above are illustrative; the pull prints the repository’s own.) Each cached weights file is announced on stderr while its SHA-256 is checked, and each download as it starts ([2/6] model.safetensors (938 MB)). When every file is already in the cache there is no question: the pull says so and links. Then the model is mlx:<name>; wisp models enable checks what it can do and records it, or declare its capabilities in config.json yourself.

Any organisation’s repository can be pulled. One from a publisher in mlx.trustedPublishers (by default ["mlx-community"]; mlx-community is trusted whatever the list holds) goes straight to the download question above. One from any other publisher is put to you first, after the file list, naming the publisher, the repository, its licence as the Hub’s model information gives it (the model card’s license, else a license: tag, else unknown), and what it would download:

$ wisp models pull ornith-ai/Ornith-1.5-9B-MLX-4bit
ornith-ai/Ornith-1.5-9B-MLX-4bit at 89abcdef0123: 9 files, 5.2 GB
  …
ornith-ai is not a trusted publisher (mlx.trustedPublishers).
  Publisher:   ornith-ai
  Repository:  ornith-ai/Ornith-1.5-9B-MLX-4bit
  Licence:     apache-2.0
  Download:    5.2 GB in 9 of 9 files, 5.2 GB in all
Its weights, tokenizer, and chat template would run in wisp's process on this Mac.
Pull it once [o], trust ornith-ai from now on [t], or refuse [N]?

(Illustrative, like the example above.) o pulls it this once and changes nothing; t adds the publisher to mlx.trustedPublishers in config.json (recorded as config.change) and pulls, and later pulls from it are not asked about; anything else, an empty line included, refuses and fetches nothing. Either o or t approves the download it names, so the [y/N] question is not asked again; the question about a real directory at <models>/<name> still is. What pulling from another publisher means is in trust.md, “When you are asked”.

--trust-publisher pulls from a publisher not in the list this once without that question; the setting is unchanged, and the download question is still asked, so the pull still needs a terminal. Without a terminal and without the flag, a pull from a publisher not in the list is refused before any request, naming the flag and the setting. --yes, which approves commands elsewhere, is not an option of wisp models pull.

See backends.md, “MLX Swift”, and ADR 0052.

wisp config

wisp config (or config show) prints the effective configuration as JSON: every setting with its default applied, the model, the run_command policy, and the paths under ~/.wisp, with whether config.json exists. The same view the model’s inspect tool and the wisp://config resource give.

wisp config get KEY prints one setting’s effective value and set in config.json or the default. wisp config list prints the settings that can be changed without editing the file, one per line: the setting, its value in config.json or (default), and what it does. wisp config set KEY VALUE sets one and wisp config unset KEY removes one so its default applies (ADR 0040); chat’s /config set and unset do the same. A config.json that exists but cannot be read (its permissions, a directory in its place) refuses the change and writes nothing, so the settings in it are never lost; the command exits 1 with the reason.

wisp config set approval.classifier coreml
wisp config set approval.coremlModel risk@0.14.0-default
wisp config set routing.ladder system ollama:qwen3.8:27b     # or a JSON array
wisp config set routing.tasks.secrets ollama:qwen3.8:27b
wisp config unset approval.timeoutSeconds

Each change is checked before it is written: an unknown setting, a value the setting does not take, or a file that would no longer load is refused with the reason, and nothing changes. The rest of the file, the command policy and custom tools included, is kept as it is; the file is written readable by its owner only. A change that weakens the gate or the audit (the threshold at never or dangerous, the classifier at rules, the audit off) prints a note, and so does coreml without a model, which then uses the default this release ships. Changes are audited as config.change and apply from the next session: a running chat keeps the settings it started with. The model cannot change the configuration; there is no tool for it.

wisp doctor

Checks that this install can work and exits non-zero if anything fails: macOS 27 or later, the on-device model available and answering a one-word request (availability alone said yes on 2026-10-13 while Apple’s model service, modelmanagerd, refused every request with “Too many open files”; when a request fails with the service’s own error, the finding says to restart it, sudo killall modelmanagerd, which launchd starts again), the configured model available when it is not system (for ollama:<name>, llamacpp:<name>, or lmstudio:<name>, that the server answers, accepts the key if it wants one, and lists the model), the Core ML risk classifier preparing when approval.classifier is coreml (the default), MLX’s Metal library loading in a build with MLX, /usr/bin/sandbox-exec present, config.json parses, ~/.wisp writable. Run it first when something is wrong. wisp --version prints the version: bare (0.16.0) for a release build, and for any other build the version, -dev, and the commit it was built from (0.16.0-dev+4ab6eec), with (modified) after it when tracked files had uncommitted changes (untracked files do not count) (0.16.0-dev+4ab6eec (modified)), so a build from main is not taken for the release whose number it carries. Where the commit is unknown (a source archive) it is 0.16.0-dev. wisp-tui --version follows the same rule. The banner and wisp doctor print the same form; the audit log’s version, the classifier versions, and the MCP handshake keep the bare version.

It also checks what wisp keeps and how it is set. A finding is either ok or not; there is no third state, so an ok that needs a caveat carries it in its detail.

wisp notify <message>

Shows a macOS notification: --title (default wisp), --subtitle, --sound. The same notifier as the model’s notify tool, so the same bounds, per-minute limit, and off switch apply, and the same routes: in Ghostty, iTerm2, WezTerm, or kitty the terminal posts it, elsewhere osascript does (tools/notify.md). The request is audited as notification with source user and the route taken. Exits non-zero with the reason when it is refused.

--route host|terminal|app|osascript uses that route alone, says which on stderr, and fails with the reason (and no usage text) when it cannot be used; app is tried even with notifications.viaTerminalApp off, which is how to probe it (below).

make test && wisp notify "Tests pass" --title "Build" --sound
wisp notify --route app "probe"      # is the banner attributed to your terminal app?

wisp scan [<file>…]

Scans files, or standard input, for credentials and prints each finding’s location, kind, and a masked preview; the value is never printed. A unified diff is scanned by its added lines and located as path:line, so a pre-commit hook can check a commit before it is made. Exits 1 when anything is found, 0 otherwise. The rules are in ADR 0031; they are a best effort, not a guarantee.

git diff --cached | wisp scan        # in .git/hooks/pre-commit: a finding fails the commit
wisp scan --personal export.csv

Each input is audited as secrets.scan with the kinds found, never the values.

wisp redact [<file>]

Prints a file, or standard input, with credentials and personal data replaced by numbered markers ([REDACTED:email#1]; the same value gets the same number) and a one-line summary on stderr. For text on its way to an issue, a chat, or a cloud model.

wisp redact crash.log | pbcopy
wisp redact --thorough support-ticket.txt > ticket-clean.txt

Audited as redaction with the counts replaced per kind.

wisp draft [commit|pr|changelog]

Drafts a commit message (the default), a pull request description, or a changelog line from a diff piped to it, or from git diff --cached run here under the policy, sandbox, and approval. The model summarises the diff per file and writes from the summary; the subject is kept to 72 characters, and a commit body ends with Why: <…> for you to replace (ADR 0035). -m, --model chooses the model: the system model drafts small changes well, and a larger local model such as ollama:qwen3.8:27b does much better on a change of many files. -y, --yes approves running git diff without asking. An empty diff is refused.

wisp draft > /tmp/msg && $EDITOR /tmp/msg && git commit -F /tmp/msg
git diff main... | wisp draft pr

wisp watch <command>

Runs a command at once, then again each time a file changes under the watched paths and, with --every, on an interval, and posts a notification when its outcome turns. A failing run is triaged by the model into its failures, shown under the run’s line; a failure that repeats without a notification is not triaged again. Changes under .git, .build, .swiftpm, target, node_modules, DerivedData, .venv, __pycache__, dist, .next, and .cache, and editor scratch files, are ignored. The command is classified and, when risky, approved once, before the first run; every run still passes the policy and runs under the sandbox, and approving the watch covers its reruns (ADR 0033). A burst of changes (a checkout, a formatter, save-all) starts one run, after the changes have been quiet for the settle period, so a run does not start part-way through the burst; changes during a run still collapse into one pending run.

wisp watch 'swift test 2>&1'                   # rerun the tests on every save
wisp watch --no-files --every 300 'make check'  # every five minutes

Each run prints a line ([22:15:34] run 2 (change): pass, exit 0, 1.3 s; was fail) and is audited as watch.run; notifications are audited as notification with source watch. Ctrl-C stops after the current run; a second Ctrl-C stops at once.

wisp classifier

Risk classifier versions live in ~/.wisp/classifiers/risk: the default each release ships, risk@X.Y.Z-default, never changed, and those trained here, risk@X.Y.Z-local.<n>, never overwritten.

wisp classifier list shows them, the one in use marked *, each with its source and latest measurement. wisp classifier train [--examples <file>] [--from-audit] [--exclude <file>]… [--use] trains a new version with Create ML from labelled commands (level<TAB>command per line) or the bundled examples; --from-audit adds the on-device model’s verdicts on the commands in this Mac’s audit log, and --use switches to it. Anything overlapping ~/.wisp/classifiers/risk/held-out.tsv, or a file given with --exclude, is left out, so a test set of this Mac’s commands is never trained on. wisp classifier use risk@<version> sets approval.classifier to coreml and approval.coremlModel to it, from the next session; wisp classifier remove risk@<version> deletes one trained here, not the default or the one in use. wisp classifier measure [risk@<version>] [--examples <file>] [--classifier rules|system-model|coreml] [--coreml-model <path>] runs a classifier, with the rules beside it, over labelled commands and prints its exact, over-, and under-ratings, misses, and latency per verdict, recording them in the version’s manifest; it exits 1 when a dangerous command is rated safe. Training is audited as classifier.train. See approval.md, “Training and measuring a classifier”. Three hidden subcommands serve the repository rather than users:

• ship trains the default risk classifier a release embeds (scripts/check classifier-default, release.md). With --task personal it trains the personal-data classifier, by hand (ADR 0042).
• split deals a labelled set into parts by family.
• baseline prints the label today’s rules give each line; for secrets, --classifier adds the personal-data classifier.

split and baseline are described in training/README.md.

wisp approvals

wisp approvals (or approvals list) prints standing approvals: id, scope, expiry, directory, pattern (such as head *). On a terminal they are aligned columns under a header, the pattern last and wrapped to the terminal’s width; piped, each is one tab-separated line, for scripts.

ID        SCOPE    EXPIRES      WHERE               PATTERN
a1b2c3d4  project  31 Oct 2026  /Users/me/src/wisp  git push *
e5f6a7b8  always   29 Oct 2026  any directory       head *

A project approval whose folder no longer exists (an agent’s worktree removed since, say) can never match again; it is marked gone: (gone) after its folder on a terminal, with a note under the table, and a sixth field, gone, at the end of its line when piped.

ID        SCOPE    EXPIRES      WHERE                           PATTERN
b12873de  project  3 Nov 2026   /Users/me/src/wisp-wt-a (gone)  git commit *

1 approval is for a folder that is gone and can never match again; 'wisp approvals clear --gone' removes them.

wisp approvals revoke <id> removes one; wisp approvals clear removes all. wisp approvals clear --gone removes only the gone ones: on a terminal it lists them and asks first unless --yes (-y); piped, it removes them at once. It prints each it removed, and decides again as it removes them, so a folder made again since the listing keeps its approvals. Gone approvals are never removed on their own. See approval.md.

wisp approvals pending lists the commands waiting for approval in wisp mcp servers, oldest first, after removing stale ones (a server that stopped, a wait that expired). Piped, each is one tab-separated line: id, level, seconds waited, client/thread, directory, command. On a terminal, a command the model asked to run outside the sandbox reads OUTSIDE THE SANDBOX: <command>; it is approved once whatever --scope says, and the answer says so (approved once, outside the sandbox (session is taken as once): …).

ID        LEVEL     WAITING  FROM             IN       COMMAND
a1b2c3d4  moderate  12 s     claude-code/git  ~/src/x  git push origin main

wisp approvals approve <id> [--scope once|session|project|always] approves one (once, the rest of the turn, by default; scopes as in chat, and a dangerous command is never remembered beyond the session); wisp approvals deny <id> refuses it. Both run only from a terminal, so an agent’s shell cannot answer for you, and wait up to three seconds for the server to take the answer:

$ wisp approvals approve a1b2c3d4 --scope session
approved (session): git push origin main for thread git

An id that is unknown, stale, already answered, or whose request file was altered is refused with the reason and exits 1, as does one answered another way first, which says so; only a decision that is not one, or a fact’s id given to wisp approvals, is a usage error (exit 64). The notification that announced the request names the id (ADR 0046; mcp.md, “Approval”). wisp approvals approve on a fact a caller asked to keep is refused with a pointer to wisp facts. A running wisp-tui shows the same requests as dialogs, and the plain chat notes them between prompts and answers them with /approvals approve|deny (“wisp chat”, above).

wisp facts

Answers a wisp mcp caller’s request to keep one of its thread’s facts as a permanent fact, which only you admit (ADR 0048; mcp.md, “set_fact_scope”). The request waits in ~/.wisp/pending with no time limit, until you answer it, and a notification names it:

wisp: keep as a permanent fact?
release codename = BLUE HERON — wisp facts keep a1b2c3d4

wisp facts pending (the default) lists the facts waiting, oldest first, after removing stale requests. Piped, each is one tab-separated line: id, seconds waited, client/thread, the fact’s id, who proposed it, subject, name, value.

ID        WAITING  FROM             FACT  SOURCE  KEEP AS PERMANENT
a1b2c3d4  12 s     claude-code/git  c3    model   release codename = BLUE HERON

wisp facts keep <id> admits the fact to ~/.wisp/facts.json as yours, as /fact ID permanent does in chat; wisp facts drop <id> leaves it in its thread (not deleted), and that thread does not ask about the same fact again. Both run only from a terminal, so an agent’s shell cannot answer for you, and wait up to three seconds for the server to take the answer. A request outlives the thread and the server that asked: once the thread has closed, the server keeps the fact for you; once the server has stopped, wisp facts keep keeps it itself (and says its server had stopped), and drop just ends the request.

$ wisp facts keep a1b2c3d4
kept as a permanent fact: release codename = BLUE HERON (thread git)

An id that is unknown, stale, already answered, or altered is refused with the reason and exits 1, as does an answer that came after the request stopped waiting; a command waiting for approval (answer that with wisp approvals) is a usage error (exit 64). Until you answer, nothing is kept. A running wisp-tui shows the same requests as dialogs, and applies an answer the same way when the server has stopped; the plain chat notes them between prompts and answers them with /facts keep|drop, applying the answer the same way. The default policy refuses wisp facts keep|drop when the model runs it.

wisp questions

Answers a question the model asked you through its ask tool under wisp mcp (ADR 0062; tools/ask.md; mcp.md, “Questions”). The question waits in ~/.wisp/pending until you answer it (or until inquiry.timeoutSeconds, when set), and one notification names it:

wisp: the model asks
claude-code, thread git
Which config did you mean? — wisp questions answer a1b2c3d4

wisp questions pending (the default) lists the questions waiting, oldest first, after removing stale ones (a server that stopped). Piped, each is one tab-separated line: id, seconds waited, client/thread, the options separated by | (empty for free text), the question.

ID        WAITING  FROM             OPTIONS                          QUESTION
a1b2c3d4  12 s     claude-code/git  ~/.wisp/config.json | ./wisp.json  Which config did you mean?

wisp questions answer <id> shows the question and prompts for your answer: a number or an option’s text for a choice (the last number is none of these), a line of text otherwise; an empty line writes nothing. The answer is typed at the prompt, never given as an argument, so it is in neither the shell’s history nor ps. wisp questions decline <id> sends no answer; the model is told to say what it needed. Both run only from a terminal, so an agent’s shell cannot answer for you, and wait up to three seconds for the server to take the answer; after the server has parked the turn, the answer reaches the thread on its next respond:

$ wisp questions answer a1b2c3d4

? the model asks (claude-code, thread git)
  Which config did you mean?
  1  ~/.wisp/config.json
  2  ./wisp.json
  3  none of these
  type a number, or press Enter to decline › 2
answered: Which config did you mean?; thread git reads it on its next turn

An id that is unknown, stale, already answered, or altered is refused with the reason and exits 1, as is an answer that came after the thread closed; a command’s or a fact’s id is a usage error (exit 64) with a pointer to wisp approvals or wisp facts. A running wisp-tui shows the same questions as pickers, and a plain wisp chat notes them before its prompt and answers with /questions answer|decline ID. The default policy refuses wisp questions answer|decline when the model runs it. Your answer goes to the model, and the agent that called wisp can read the thread.

wisp completions

Shell completion for zsh, bash, and fish: subcommands, flags, and their values. Homebrew installs it with wisp; otherwise wisp completions install puts it where your shell looks.

wisp completions zsh                 # print the script (also: bash, fish; 'print zsh' is the same)
source <(wisp completions zsh)       # try it in this shell only
wisp completions install             # write it for the shell $SHELL names, and say how to turn it on
wisp completions install fish        # or name the shell
wisp completions install --print-path  # where it would go; writes nothing

Directories are created. A file already at the path is replaced only when it is wisp’s (it carries the line starting # wisp completions: near its top); any other file is refused and left as it is, and an identical one is reported as current. A symbolic link at the path (a dotfiles manager’s) is kept: the script is written through it to the file it points to when that file is wisp’s, and a link to anything else, or to nothing, is refused. A refused or unwritable path exits 1 with the reason; only a shell wisp cannot tell is a usage error (64). Shell start-up files are never edited; instead install prints what to add:

$ wisp completions install zsh
wrote the zsh completions to /Users/you/.zsh/completions/_wisp
Unless ~/.zsh/completions is already on your fpath, add these lines to ~/.zshrc, before any compinit there:
  fpath+=(~/.zsh/completions)
  autoload -U compinit; compinit
then start a new zsh (exec zsh).

That advice is left out when FPATH is exported and already holds the directory. bash needs bash-completion 2 (brew install bash-completion@2), which loads the file on demand, or a source line in ~/.bashrc; fish loads its file in new sessions. An unknown shell, or $SHELL naming none of the three when no shell is given, is a usage error (exit 64). Neither form reads or writes ~/.wisp, and installing is not audited: it changes the shell’s set-up, not what wisp or its model may do.

Some values are completed from wisp’s own files when you press Tab, never from the network or a model:

The scripts are generated by swift-argument-parser from wisp’s command tree, committed in harness/Sources/WispCore/Resources/completions/, and embedded in the binary at build time like the system prompt; the gate fails when they no longer match the commands, and scripts/check completions rewrites them (engineering.md).

wisp mcp

Serves the Model Context Protocol over stdio until the client closes the pipe. See mcp.md. A command that needs approval is asked through the client’s dialog, when it has one, and, with approval.outOfBand (the default), filed for wisp approvals approve|deny and wisp-tui at the same time; the first answer wins (wisp approvals). The notification that a command waits is posted only once the client’s dialog has gone unanswered for approval.bannerDelaySeconds (default 10), and not at all if it is answered sooner; a client with no dialog is told at once.

Home directory and configuration

State lives in ~/.wisp, or $WISP_HOME when set. Any command that writes there creates it: respond, chat, and mcp write the audit log (unless audit.enabled is false), chat writes transcripts, and doctor probes that it is writable. tools and logs never create it.

config.json fields, all optional:

Environment: WISP_HOME relocates the directory; WISP_LOG=debug|info|error mirrors diagnostics to stderr. wisp models pull and wisp models find the Hugging Face cache through huggingface_hub’s variables (HF_HUB_CACHE, HUGGINGFACE_HUB_CACHE, HF_HOME, XDG_CACHE_HOME). WISP_LLAMACPP_API_KEY and WISP_LMSTUDIO_API_KEY are the keys of a llama.cpp or LM Studio server that wants one, and win over config.json’s apiKey.

{ "systemPromptExtension": "Prefer British spelling.", "commandTimeoutSeconds": 300 }

A malformed file or an invalid commandPolicy pattern is an error; a missing file is fine. Unknown fields are ignored.

facts.kinds entries each name a kind and set any of class (permanent, dynamic, or ephemeral), normaliser (how names under it are made one: casefold, trim, single for one fact per conversation, command for a command line’s core, path for a path relative to its git repository’s root), description (what the distiller is told such facts are), and distil (false leaves the kind to the tools: the model is not asked for such facts; wisp’s file, service, and machine say so). An entry with a known kind’s name changes only the fields it sets; any other name adds a kind, dynamic and casefold unless it says otherwise. wisp’s kinds are task, decision, preference, entity, tests, file, service, machine, workdir, branch, and answer (context-management.md lists them). An unknown normaliser, a kind without a name, or a share outside 0 to 0.5 makes the config malformed.

{ "facts": { "kinds": [
  { "name": "ticket", "class": "dynamic", "description": "A ticket, its number, and its state." },
  { "name": "entity", "class": "dynamic" }
] } }

Context window

The on-device model’s window is 8,192 tokens on macOS 27, measured on 2026-09-29; an Ollama or MLX model’s is sized from its shape and the Mac’s memory when it is selected, or is the model’s own ollama.models.<name>.contextLength or mlx.models.<name>.contextLength, else ollama.contextLength or mlx.contextLength, when one is set; a Core AI model’s is the one its bundle was exported for; a llama.cpp or LM Studio model’s is the one the server holds it at, read when it is selected (8,192 when the server reports none, or LM Studio has not loaded it).

The model does not carry the whole conversation. Each request is composed from the conversation’s store: the instructions, the facts and the running summary, the recent turns with each tool’s output whole in its own turn and a short reference after it, and the request (ADR 0045). When the context, your next message, and a turn of average size would pass 85% of the window, wisp condenses to context.target (0.6 of the window by default): earlier output as references, then the oldest turns distilled into facts and the summary and dropped, measuring after each step and always keeping the last turn. A request that overflows anyway is condensed the same way and retried once. chat prints a note when this happens, and MCP results carry condensed: true. With context.memory on, the model’s memory tool brings back what the context holds only as a reference, a summary, or a fact (tools/memory.md); you can always see it with /show and /inspect context. See context-management.md.

Exit codes

Requirements

macOS 27 or later. The on-device model must be enabled in System Settings (Apple Intelligence); fm available reports its state.

Tools

Tools the on-device model can call. Each page gives the model-facing contract (name, description, arguments, result format) and the limits that protect the context window. wisp tools prints the live list.

Select tools per session with --tool <name> on the CLI or the tools argument of MCP respond. Every registered tool’s schema is in the prompt on every turn, so enable only what a task needs. All the tools, the default, are every registered tool but memory, models, and ask, which join them when context.memory, tools.models, and tools.ask are on; a named list has any of them only when it names it (memory.md, models.md, ask.md), and tools.disabled can leave any out everywhere.

MCP clients discover these tools through the wisp://tools resource, generated from the registry; the limits and example prompt for each come from the tool itself (WispTool.limits, rendered from its live options, and WispTool.examplePrompt). See ../mcp.md.

Adding a tool

To give the model a command you use often, declare a custom tool in your config; no build is needed (custom.md). To add a built-in tool to wisp itself:

1. Add a struct conforming to WispTool under harness/Sources/WispCore/Tools/, with an @Generable Arguments type, @Guide descriptions on each property, limits rendered from its options, and an examplePrompt that names the tool.
2. Keep the work in a pure helper (like CurrentDateTool.format or FileReader) and test that.
3. Bound the result to the tool-output budget: page it, or pass it through ToolOutput.fitted with the registry’s ToolBudget and OutputStore, so what does not fit is kept and marked rather than dropped (ADR 0050). See ../context-management.md.
4. Append it to ToolRegistry.init; it is wrapped by AuditedTool there.
5. Add a page here and a row above. The description is prompt text; write it for the model.

current_date

Returns the current local date and time. The on-device model has no clock and will guess otherwise.

Arguments

Result

One line: an ISO 8601 timestamp with offset, then the zone identifier.

2026-09-17T13:41:02+01:00 (Europe/London)

Limits

None needed; the result is a single line.

Implementation

harness/Sources/WispCore/Tools/CurrentDateTool.swift. Formatting is a pure static function, tested in CurrentDateToolTests.

run_command

Runs a shell command on this Mac and returns its exit status and output. This is the generic exec tool: the model uses it to build, test, list files, and inspect the system, and through it can reach any binary on the machine.

Arguments

Result

exit status: 0
stdout:
<tail of stdout>
stderr:
<tail of stderr>

Extra lines appear when relevant: timed out: the command was killed after 120 s; ask for up to 1800 s with timeoutSeconds (or …, the most allowed when the limit was the cap), stopped: the person stopped the command, a sandbox: line (below, and for a command asked to run outside the sandbox), and, when more was printed than fits, a held back: note. Empty streams are omitted. A killed process reports its signal negated (for example -15 for SIGTERM).

Output past the bound is held back, not dropped (ADR 0050). The result is bounded as a whole, its header and notes included, to the conversation’s tool-output budget (an eighth of the model’s window, 4 to 64 KiB; context-management.md). When a command prints more, each stream shows its first and last lines, about half its share of the room each, cut at line ends, with a marker between them, and the result ends with a note naming the lines held back and where the whole is:

exit status: 1
stdout:
Compiling Sources/File1.swift
…
[… 2,270 lines (180 KiB) held back …]
…
error: fatalError: 1 of 3 targets failed
held back: stdout lines 44–2,313 (180 KiB); the whole output is kept as output 3f9a2c1b (2,340 lines); memory "recall output 3f9a2c1b from line 44" pages it, "recall output 3f9a2c1b matching PATTERN" filters it, "summarise output 3f9a2c1b" gives the notable lines, "condense output 3f9a2c1b: QUESTION" answers from all of it; do not run the command again to see it

The whole output (the rendering with nothing held back: the header, stdout:, the stream, stderr:, the stream) is kept in the conversation’s output store, ~/.wisp/output/<audit session>/<id>, under the audit call id of the tool call, up to 16 MiB; past that it is cut and the note says the rest was not kept. The line numbers in the note are the stored output’s, so a recall from that line lands on the first held-back line. The room is shared between stdout and stderr in proportion to their size, and a stream with something to show always gets at least a fifth of it, so a short error is not crowded out by a long log. In a conversation without memory the note says the output is kept and not to run the command again; without an output store (the audit off, an agent made directly) it says the held-back lines were not kept. A command is never run again to see what it printed.

In memory the runner keeps a head and a tail of the bound per stream and counts the rest; the moment a byte would be dropped it spills the whole stream to the store as it arrives, so a command printing 1 GiB costs memory of a few times the bound. Before 0.22.0 every byte was held until the command ended and all but the tail of each stream was then discarded.

Limits

Policy and sandbox

Every command passes a CommandPolicy (ADR 0009), configured under commandPolicy in config.json:

Inside the sandbox everything is readable and executable, but writes outside the writable set fail with Operation not permitted. So do writes to wisp’s own home (~/.wisp, or WISP_HOME), wherever it is: the profile denies it after the allow rule (Seatbelt applies the last rule that matches), so a sandboxed command can never change wisp’s approvals, facts, configuration, or pending answers (one the person approved to run outside the sandbox can), even when the home lies inside the writable set (the profile then carries a ; note: comment saying so, and diagnostics log it). wisp itself writes its home in its own process, outside the sandbox. A denied pattern comes back to the model as error: command denied by policy: … so it can try something else.

When a confined command fails with Operation not permitted, wisp checks whether the sandbox refused it (ADR 0054) and adds one line to the result, after the output. It reads the paths the error names (sh: PATH: …, touch: PATH: …, cp, mkdir, rm, mv … to PATH, GNU’s cannot create regular file 'PATH', Python’s [Errno 1] Operation not permitted: 'PATH'), resolves each to its real path as the profile does (/tmp is /private/tmp), and compares it with the writable roots. A tool that checks its directories before it writes never reaches Operation not permitted, so a failed command’s not writable lines are read too: Homebrew’s The following directories are not writable by your user: with its indented list (brew install and brew upgrade under the sandbox print it for /opt/homebrew and ~/Library/Logs/Homebrew), and a line PATH is not writable.. Either way:

The last is a guess, and says so. It names the policy because a model read a bare Error: Operation not permitted from a nested wisp as the deny list’s refusal (session ce87576a, 2026-10-04): a command that ran passed the policy. Seatbelt reports nothing of its own on macOS 27 (probed on 2026-10-04: no kernel deny record for a sandbox-exec profile, with (debug deny) or (deny default); (with report) is refused on a deny rule; (with send-signal …) delivered nothing), so the error output is all there is to check. The line lists at most three paths and about 240 bytes of roots. command.outcome records the verdict as sandboxRefusal. For a refused or a guess, while sandbox.allowOutsideSandbox is on, the line ends ; if it must, ask again with outsideSandbox true (the person approves each run) (ADR 0064).

{ "commandPolicy": { "deny": ["sudo"], "allow": ["^(swift|cargo|git|ls|cat) "],
                     "sandbox": { "enabled": true, "allowNetwork": false, "writablePaths": [] } } }

--unsafe on respond, chat, and mcp turns both layers off with a warning on stderr.

Running outside the sandbox

Some chores cannot run under the sandbox at all (ADR 0064). Probed on 2026-10-14: cargo update in the project works, but cargo install writes ~/.cargo/bin and ~/.cargo/.crates*.toml, rustup update writes ~/.rustup, and every Homebrew write goes to /opt/homebrew/… or ~/Library/Logs/Homebrew, all outside the writable roots; brew upgrade --dry-run stops with Homebrew’s “You should change the ownership of these directories”. Widening writablePaths cannot fix Homebrew: Homebrew 7 runs its own sandbox-exec for fetching, post-install steps, and source builds, Seatbelt refuses a nested profile that differs (below), and Homebrew’s opt-out is refused for the default prefix. Widening by default would also make ~/.cargo/bin and /opt/homebrew/bin, both on PATH, writable to every command.

So the model may ask for one command to run without the sandbox, with outsideSandbox: true:

1. The policy’s deny and allow patterns apply as to any command.
2. With sandbox.allowOutsideSandbox false, it is refused: error: command denied by policy: running outside the sandbox is turned off here (commandPolicy.sandbox.allowOutsideSandbox is false); ….
3. The person is asked about the whole line, every time: whatever the classifier and approval.threshold say (a read-only ls and never included), at moderate at least, with “runs OUTSIDE the sandbox: it may write anywhere you can, ~/.wisp included; this one run only” first among the reasons. No earlier approval covers it, and the answer covers nothing after it. It is approved once or not at all: the faces offer only that, and a wider answer given anyway (wisp approvals approve ID --scope session) is taken as once (approval.md).
4. Where no person can be asked (--yes, non-interactive respond, an MCP client with no dialog while approval.outOfBand is off), it is refused with the reason: error: command not approved: running outside the sandbox is asked of a person every time, and no one can be asked here ….
5. Approved, it runs without sandbox-exec, under the same time limit, output bound, and output store, and the result ends sandbox: ran outside the sandbox, as the person approved, this once.

Without the sandbox, nothing protects wisp’s home: the command can write anywhere the person can, ~/.wisp included. That is what the person approves, for that exact line, and why it is asked every time and named on every face. With the sandbox off (sandbox.enabled false, --unsafe) the argument changes nothing and asks nothing more: sandbox: outsideSandbox changed nothing: the sandbox is off here. When wisp itself runs inside another sandbox, wisp cannot leave it, so the command runs under that one as every command does there: sandbox: outsideSandbox changed nothing: wisp runs inside another sandbox, which confined this command. A command the person types after ! never carries the argument; one typed after !! runs outside the sandbox without asking (below). policy.decision, approval.requested, approval.decided, approval.pending, and command.outcome record outsideSandbox (logging.md).

The person can run a command outside the sandbox themselves, in chat, by typing it after !! (!!brew upgrade; wisp-tui’s outside mode, its input box red): the same runner path as a command typed after !, with outsideSandbox set and no one asked, since typing it is the approval (ADR 0064, amended 2026-10-14). The deny and allow lists apply, sandbox.allowOutsideSandbox false refuses it (… type it after a single ! to run it in the sandbox), and with the sandbox off or nested it changes nothing, as above. It has no time limit, as any typed command; Ctrl-C stops it. Its events carry origin: "person" and outsideSandbox: true (wisp.md). The model is never offered it: !! is a line the person types, not an argument.

Risk classification and approval

A line is split into its simple commands (chains, pipes, subshells, substitutions), and each part is classified safe, moderate, or dangerous by rules plus a classifier (by default the Core ML classifier the release ships, or the on-device model; commands on the rules’ read-only list skip it); at moderate or above a human is asked for that part, with the line shown for context, and approvals are remembered by program (head *): on the terminal in chat; in mcp, through the client’s elicitation dialog and, with approval.outOfBand (the default), through wisp approvals approve|deny and wisp-tui at once, the first answer winning; and refused in non-interactive respond unless --yes. Denials come back as error: command not approved: …. Configure with approval.threshold and approval.classifier. See approval.md.

The person can run a command through the same runner by typing it in chat after ! (ADR 0049; wisp.md, “Commands you run yourself”). Such a command passes the same policy lists and runs under the same sandbox and output bound, but is not classified and never asks: typing it is the approval. It has no timeout: the person stops it with Ctrl-C, which ends its process group as the timeout does (SIGTERM, then SIGKILL two seconds later, or at once on a second Ctrl-C), and records stopped: true (ADR 0049, amended 2026-10-09). Its policy.decision and command.outcome carry origin: "person".

Symlinks

Seatbelt matches real paths, so wisp resolves every profile path with realpath(3) before generating the profile (/tmp and /var are symlinks into /private; a not-yet-existing path resolves its longest existing prefix). At run time the kernel resolves the target of each write, not the name used. Verified on macOS 27:

The invariant: a write succeeds if and only if the real file lands inside the writable set. Hard links are the one different mechanism, but creating one needs write access to the destination directory and the same volume, so it can only alias files the command could already reach.

Programs that will not run sandboxed

Seatbelt will not execute a setuid binary, so /bin/ps and /usr/bin/top fail inside the sandbox (execvp() of '/bin/ps' failed: Operation not permitted, verified on macOS 27 on 2026-09-23). The system_info tool reads the process table through libproc instead (system_info). /usr/bin/log checks for a sandbox itself and exits (log: Cannot run while sandboxed), even under a profile that allows everything (verified 2026-09-24); condense_log with last reads the unified log in process instead (mcp.md).

Nested sandboxes

Seatbelt lets a process re-apply an identical profile but refuses a different one (sandbox_apply: Operation not permitted). Two consequences, both verified on macOS 27:

• Tools that apply their own sandbox cannot run inside wisp’s. Run SwiftPM as swift build --disable-sandbox and swift test --disable-sandbox; Cargo needs nothing.
• When wisp itself runs inside a sandbox (for example wisp running its own tests through its MCP server), its sandbox-exec would be refused. wisp decides this once per process with a probe command of its own (CommandRunner.isNestedSandbox), records nested: true on each policy.decision, and runs commands plainly because the outer sandbox is already confining them. The decision never depends on a command’s output and a command is never launched twice: an earlier version keyed on the refusal text in stderr, which a command could print to get itself re-run unsandboxed (found by review, fixed 2026-09-19). Tests that assert enforcement skip when nested; scripts/check runs the runner suites inside an outer sandbox on every commit and fails if they fail.

Writable root and working directory

The sandbox’s writable set is rooted at the directory wisp was launched in (Options.writableRoot), plus the temporary directory, the per-user cache directory, /private/tmp, and configured paths. A workingDirectory chosen by the model changes where the command runs, never what it may write: a command run in /Users/me with the root at the project can read there but its writes fail. Before 2026-09-19 the per-command directory was the writable root, so workingDirectory: "/" made everything writable.

Process tree and timeouts

Commands are spawned in their own process group (posix_spawn with POSIX_SPAWN_SETPGROUP), stdin from /dev/null, and SIGINT at its default (chat ignores it to take Ctrl-C itself, and an ignored signal would otherwise be inherited). On timeout the whole group gets SIGTERM, then SIGKILL two seconds later; a command the person typed has no timeout and gets the same when they stop it. And whenever the shell exits, on its own or at the timeout, the group is sent SIGKILL until it is empty (for up to two seconds): nothing a command starts outlives it, neither a background job (sleep 30 &, a server the model started) nor a child that ignores SIGTERM. Before 0.21.1 the watchdog stopped when the shell was reaped, so both lived on. A descendant that left the group (setsid) is beyond this; output capture after exit is bounded by one second in case one holds the pipe.

Which limit a model’s command runs under (ADR 0063), first that applies:

The cap is the operator’s: no tool changes config.json, so neither the model nor an MCP caller can raise it. A timed-out result names the limit and, under the cap, how to ask for more; command.outcome records the limit as timeoutSource (call, thread, or default), timeoutSeconds, and timeoutClamped (logging.md). Before 0.24.2 every model’s command had the operator’s one limit, 60 s by default, which killed a git commit whose pre-commit hook ran the full gate (2026-10-13), and a commandTimeoutSeconds of 0, documented as no limit, set a watchdog of zero seconds instead, which fires at once. Custom tools keep their own timeoutSeconds and system_info its floor of 30 s; neither reads the thread’s.

The timeout and the two-second grace are timers on a dispatch queue of wisp’s own, not Swift tasks, so they fire on time whatever else the process is doing. Until 2026-10-10 they were Task.sleeps on Swift’s cooperative pool, and when other work blocked every thread of it (2026-10-10, under the gate’s parallel tests) a 200 ms timeout went unenforced for the whole of a 30 s command (docs/design.md, “Concurrency”). The wait for the shell to exit has a thread of its own too.

Reads are not restricted; omit the tool (--tool current_date, or the MCP respond tools argument) where even that is too much. There is no direct MCP run_command; other harnesses reach it only through the model.

Implementation

CommandRunner in harness/Sources/WispCore/Exec/CommandRunner.swift does the work and is tested by running real commands in CommandRunnerTests; RunCommandTool is the thin model-facing wrapper.

read_file

Reads a page of lines from a text file, numbered, and tells the model how to fetch the next page. The file is streamed, so reading the first page of a multi-gigabyte log costs only the bytes up to the end of that page.

Arguments

Result

Numbered lines, then a marker.

1	# wisp
2
3	An on-device, tool-using AI microharness ...
[more: call again with offset 4]

The final line is either [more: call again with offset N] or [end of file]. A range past the end yields (no lines in range) and [end of file].

Approval

Paths go through the approval gate’s rule classifier as if they were cat '<path>', the path shell-quoted, with # resolves to '<real path>' after it when following links leads to a file the rules rate higher: credential-like paths (.ssh, .aws/credentials, .netrc, keys), by the name given or the file it leads to and in any case (.SSH/ID_RSA), are rated dangerous and ask, or are refused where nobody can answer, exactly as the command would be. Ordinary files pass without a model call. Refusals come back as error: read not approved: ….

The gate is the only control on reads. The read happens in wisp’s own process with your permissions: there is no sandbox and no confinement to the launch directory, unlike run_command’s writes, so the model can read anything you can, your home directory included (trust.md). Prefer --tool to leave read_file out of a conversation that should not read at all.

Limits

A line ends at \n, \r\n, or a lone \r (a classic Mac OS file), so CRLF, CR-only, and mixed files are numbered line by line, exactly as edit_file’s line counts them; the returned lines never include \n or \r.

It reads forward only: there is no search, no tail, and no binary content. To find a line in a large file or see its end, have the model use run_command with grep -n or tail, then read_file at the offset it learns. The file is opened close-on-exec, so no command the model runs meanwhile inherits the handle.

Implementation

FileReader and LineScanner in harness/Sources/WispCore/Tools/FileReader.swift, tested in FileReaderTests including chunk-boundary and early-stop cases; ReadFileTool is the model-facing wrapper.

edit_file

Writes a text file: the whole file, an addition at the end, or one exact replacement. The counterpart of read_file: read a page, then replace exactly what was shown. Decided in ADR 0024.

Arguments

Read the file first, then replace by line:

Use read_file to read /repo/Package.swift. Then use edit_file with mode replace on /repo/Package.swift,
with line set to the number read_file showed for `let version = "0.1.0"` and content `let version = "0.2.0"`.
Report the tool results verbatim.

Line edits

replace with line writes content as given, with two exceptions for the slips small models make most (measured with Qwen3-1.7B on 2026-10-06, ADR 0024, refined that day). Neither guesses: each acts only on an exact condition, and the result says what it did.

Every other line edit is written exactly, so a deliberate whitespace change works: indenting a line (return 1 to return 1), dedenting one ( y = 2 to y = 2, the stripped texts being equal), tabs to spaces, trailing spaces stripped, or an indented line emptied. When find is on no line or on several, or the number is past the end, nothing changes, with the errors below.

The blind spot: a text change and a dedent to column zero in one edit ( return 1 to print(1) at the margin) keeps the indentation. The result says so, and the model can make the edit in two steps, or by find.

Line endings

replace numbers lines exactly as read_file does: a line ends at \n, \r\n, or a lone \r (a classic Mac OS file). Lines are split on the file’s bytes, never on Swift’s Character, which takes \r\n as one grapheme; until 2026-10-12 a CRLF file was one line to edit_file, so a line past 1 was refused and an edit of line 1 replaced the whole file (ADR 0024, refined that day).

write and append write content exactly as given, line endings included, and never read the file.

A guard makes a wider change impossible: before anything is written, the edited file is split again and compared with the original, and an edit whose result changes a line it does not name, has more or fewer line breaks than the edit removes and adds, or changes the ending of the line it touches is refused with nothing written (error: edit at line 1 refused: the file would have 0 line breaks, not 3, more than the edit names; nothing changed). Every edit is built not to reach it; it exists so that a fault in that construction refuses rather than loses data.

Result

One line, and for a replacement the edited line as it now reads, quoted with tabs, quotes, backslashes, line feeds, and carriage returns escaped and cut at 200 characters (a replacement by find that spans lines shows the first three and says how many more):

created /repo/notes.md; now 42 bytes
appended to /repo/notes.md; now 60 bytes
replaced at line 3 of /repo/notes.md; now 58 bytes; line 3 now: "opening paragraph"
replaced at line 2 of /repo/b.py, keeping the line's indentation (4 spaces); now 42 bytes; line 2 now: "    return 10"
line 2 did not contain "return 1"; replaced line 3 of /repo/b.py, the one line that does; now 42 bytes; line 3 now: "    return 10"

Errors come back as text so the model can react: error: text to replace not found: …, error: text to replace occurs 2 times, include more surrounding text: …, error: cannot write …: outside the writable directories (…), error: edit not approved: …, and the guard’s error: edit at line N refused: …; nothing changed.

Confinement

Writes land only under the directories the sandbox lets run_command write under: the directory wisp was launched in, the temporary directory, /private/tmp, the user cache directory, and sandbox.writablePaths from config.json. The check canonicalises the path (symlinks resolved, so /tmp is /private/tmp) and refuses anything else before touching the file system. With the sandbox off (sandbox.enabled: false or --unsafe) there is no confinement, as for commands, with one exception: wisp’s own home (~/.wisp, or WISP_HOME) is never written, sandbox or not and inside the writable set or not (error: cannot write …: it is in wisp's own home, which edits never change), as the sandbox denies it to commands.

Approval

Every edit is judged as the command edit_file <mode> <path> by the full classifier, rules and, when configured, the model. The rules rate every edit at least moderate (“edits a file”) and credential paths (.ssh/, .aws/credentials, .netrc, keys) dangerous, so under the default threshold the first edit in a conversation asks and the answer’s scope applies to later ones: “this session” covers every edit_file call, project and always scopes are keyed to the pattern edit_file * as for a program. Where nobody can answer the edit is refused and the file is untouched.

Limits

Audit and receipts

Each edit that happens is recorded as file.write with path, mode, created, bytesBefore, and bytesAfter (logging.md); the MCP receipt lists it under files. The content itself is in the tool.call event’s arguments.

Measured with the model

The eval (ToolEvalTests, scripts/check eval) runs the 86 replace cases of edit_file.json, each once: files in 35 languages and formats of 2 to 81 lines, one line named by its text, two neighbouring lines, a line emptied or a fragment cut, an empty line filled, near-duplicate lines, non-ASCII text, CRLF files edited by line number and by find, and stale line numbers reconciled by find. A pass is the file ending up exactly as intended. The release runs a fixed subset of 36 spread over those shapes, against a floor set from the configured model’s history (47 of 86 for the whole set, 17 of 36 for the subset); WISP_EVAL_FULL=1 runs all of them (measurements.md, “The case sets” and “The floors”); the recorded result is also on wisp tools --markdown. Until 0.23.0 it was ten small files, three attempts each. The line argument exists because the first version, replace by find only, measured 3 of 5 on 2026-09-20: the model copied find correctly and then put the neighbouring line into content too. A write outside the writable set is refused with the directories named and no file created. A second measurement, edit_file.whitespace (24 cases, a subset of 8 in the release, floors 18 and 5), rewrites only a line’s whitespace: indent, dedent, tabs to spaces and back, trailing spaces or a tab stripped; it is kept apart so edit_file.replace stays comparable across runs. The line-edit rules above were measured before and after on 2026-10-06 (measurements.md, “edit_file’s line rules”).

Implementation

FileWriter in harness/Sources/WispCore/Tools/FileWriter.swift (confinement from CommandPolicy.writableRoots, the list the Seatbelt profile is built from), tested in FileWriterTests, with lines split by TextLines (TextLines.swift), tested with read_file’s numbering in LineEndingTests; EditFileTool is the model-facing wrapper, tested in ToolWrapperTests.

inspect

Shows wisp’s own state to the model: the effective configuration, this conversation’s status, the standing command approvals, or recent audit events. Read-only. The same views back the MCP wisp:// resources and wisp config; see ADR 0018.

Arguments

Result

• config: pretty JSON, every setting with its default applied, the model, the run_command policy, and the paths under ~/.wisp (the same as wisp config); compact JSON on one line when the pretty layout would pass the 4 KiB cap, as it does with every backend’s settings, so no setting is cut.
• status: pretty JSON with session, entryPoint, turn, model, tools, sessionApprovals (how many patterns are approved for this session), auditFile, version.
• approvals: pretty JSON array of standing approvals: id, pattern, workingDirectory (null for always), scope, level, grantedAt, expiresAt, source.
• audit: one summary line per event, oldest first, the same lines wisp logs prints. no matching audit events when nothing matches.
• calls: one line per tool call of a turn, numbered, with the tool, its arguments (shortened), and its outcome: a command’s exit status (and whether it timed out), denied by policy; did not run, not approved; did not run, threw: …, an error: … result’s first line, or ok, N bytes. Built from the turn’s audit events (TurnCalls, as respond’s calls), so a turn’s calls fit where its raw events did not (ADR 0050). no tool calls in turn N when there are none.

turn 3: 3 tool calls
1. run_command {"command":"swift build"} → exit status 1
2. read_file {"path":"/a"} → ok, 3612 bytes
3. inspect {"what":"audit"} → error: unknown kind 'nope'

An unknown what or kind is returned as error: … text naming the accepted values.

Limits

Output is bounded to the tool-output budget (an eighth of the model’s window, 4 to 64 KiB; context-management.md); a view past it is kept whole in the conversation’s output store and shown as its first and last lines with a marker and a held back: note naming how to page it. audit reads the audit file (and its rotated predecessors), so a session whose audit log is disabled sees nothing. Every call is itself audited as tool.call and tool.result like any other tool, so reading the audit log leaves a trace in it; the same call made again in a turn, with the same arguments, is answered with a [repeated call: …] line above its result (six inspect(audit) calls in one turn of session ce87576a, 2026-10-04).

Example

wisp "Use inspect with what: audit, last: 5, kind: command.outcome and tell me which commands ran and their exit status."
wisp "Use inspect with what: calls to list this turn's tool calls, then check each claim you made against them."

Implementation

InspectTool in harness/Sources/WispCore/Tools/InspectTool.swift renders Introspection (Session/Introspection.swift), which a WispThread builds with the session’s home, config, store, and a status closure. Tested in IntrospectionTests and, through the MCP server with a scripted model, in WispServerWireTests.

notify

Shows the user a macOS notification: a title and a message, the way a long-running task says it has finished or that it needs you. The same notifier backs wisp notify on the command line (wisp.md). Decided in ADR 0030; how it is posted, in ADR 0044.

Arguments

Result

notification posted via <route> (host, terminal, app, or osascript, below), or error: notification not shown: <reason> when notifications are off, the message is empty, the per-minute limit is reached, or every route failed. The model is told the reason and can say so. Delivery is not awaited: a route that took the notification has done its part.

Limits and controls

How it is posted

The limit, the bounds, and the off switch apply first; then the first of four routes that works posts it, in this order:

Under wisp mcp, MCP has no notification primitive, so the server posts from its own process: the host and terminal routes are skipped (the client owns the terminal, and a sequence written from the server would interleave with its frames; ADR 0044), and the app route posts under the client terminal’s bundle identifier when the server inherited one, osascript otherwise. The calling agent is told: respond’s result lists each notification its turn posted or tried to, with the route taken, as structuredContent.notifications (mcp.md). A command waiting for approval posts one too, source approval, naming the command and the wisp approvals approve line that answers it (ADR 0046).

iTerm2 shows OSC 9 only with a setting on: Settings, Profiles, Terminal, Notification Center Alerts, Filter Alerts, “Send escape sequence-generated alerts” (per Claude Code’s documentation, which uses the same sequence). The write succeeds whether or not the setting is on, so a banner could be lost without a word; in iTerm2 the app route is tried before the terminal route, and wisp-tui leaves notifications to wisp there.

Terminal.app has no sequence, and tmux does not pass one through, so in either a notification falls through to the app route, and to osascript only without it. wisp doctor names the route it would take in the terminal it runs in.

A terminal may hold back its own banner while its window has focus. Probed 2026-09-30: Ghostty posts OSC 9 (and OSC 777, which wisp does not use) as a banner under its own name, but only once another app is in front. That is the terminal route’s behaviour by design, since a person looking at the terminal sees the output; the app route posts regardless.

The two AppleScript routes run /usr/bin/osascript with a fixed script; the title, subtitle, message, and the app’s bundle identifier are passed as arguments and read from argv, so nothing the model writes is ever parsed as AppleScript. Apple’s notification framework needs an app bundle and aborts in a command-line binary (probed on this Mac, 2026-09-23), which is why the last route exists at all. macOS shows its banner as coming from Script Editor, and the first one may ask you to allow notifications for it.

If notifications collect in Notification Center without popping up, Script Editor’s alert style is set to deliver quietly, or a Focus mode is on: in System Settings, Notifications, Script Editor, choose Banners or Alerts. Seen on this Mac on 2026-09-23: both test notifications arrived in the stack and neither showed a banner. For the terminal route the same applies to the terminal’s own row.

Probing the app route

The app route is off until it is shown to work on macOS 27: whether a banner sent to a terminal app by bundle identifier is attributed to that app, and not to Script Editor. To check it in the terminal you use:

wisp notify --route app "probe"

The first time, macOS asks whether wisp’s terminal may control the app (Automation); allow it and run the command again, since the first attempt gives up after five seconds. Then look at the banner: it should show your terminal’s name and icon. Probed 2026-09-30 on macOS 27 in Terminal.app and Ghostty, both attributed to the terminal, so the route is on by default; wisp config set notifications.viaTerminalApp false turns it off, and notifications then fall through to osascript (Script Editor). wisp notify --route terminal "probe" checks the terminal route the same way.

A helper app posting through Apple’s UserNotifications, so banners come from Wisp itself, is planned for when wisp can be signed (backlog.md, “When wisp can be signed”).

Implementation

Notifier in harness/Sources/WispCore/Support/Notifier.swift, one per session so the rate limit covers every conversation, tested in NotifierTests with an injected runner and clock. The routes are NotificationRoutes and TerminalNotification in Support/NotificationRoutes.swift, carried by each face’s SessionHost, tested in NotificationRoutesTests with an injected environment and terminal writer. NotifyTool is the model-facing wrapper and posts through the host. wisp-tui’s side is tools/wisp-tui/src/notify.rs.

Custom tools

Your own tools for the model, declared in ~/.wisp/config.json: a command line with {placeholders} and the typed arguments that fill them. The model sees an ordinary tool; a call substitutes the values and runs the line exactly as run_command would, through the policy, classifier, approval, sandbox, and audit. Only your own config can define them; a project cannot. Decided in ADR 0036.

{
  "tools": {
    "disabled": ["notify"],
    "custom": [
      {
        "name": "issue",
        "description": "Shows a GitHub issue of the current repository.",
        "arguments": { "number": { "type": "integer", "description": "The issue number" } },
        "command": "gh issue view {number}"
      },
      {
        "name": "line_head",
        "description": "Shows the first lines of a file.",
        "arguments": {
          "path": { "type": "string", "description": "The file" },
          "lines": { "type": "integer", "description": "How many lines", "default": 5 }
        },
        "command": "head -n {lines} {path}",
        "timeoutSeconds": 10
      }
    ]
  }
}

Fields

tools.disabled lists built-in tools to leave out: current_date, run_command, read_file, edit_file, inspect, notify, system_info.

How a call runs

Values are substituted into the command: strings single-quoted, so a value cannot break out of its argument (it's becomes 'it'\''s'), and checked against the enum; integers, numbers, and booleans as written. Substitution is one pass over the template, so a value that holds another placeholder ({b}) stays text and is never filled in itself (before 0.21.1 it was, which let one value unquote another). A missing required value or one of the wrong type comes back to the model as error: … without running anything. The substituted line then goes through run_command’s runner: the policy’s deny patterns, the risk classifier and approval (judged on the substituted line, so a template that writes, installs, or reaches the network is asked about as the same command would be), the sandbox, the timeout, and the output bound. The result is run_command’s: the exit status and bounded output. Every call is audited as tool.call, and its command as classifier.verdict and command.outcome (logging.md).

Checking

A bad definition makes the config malformed, and every command says which tool and why:

Error: malformed ~/.wisp/config.json: custom tool 'issue': the command uses {num}, which is not a declared argument

wisp tools lists the tools a session gets, custom ones last; wisp tools --markdown shows each one’s limits and an example prompt, as the MCP resource wisp://tools.md does.

system_info

Answers questions about this Mac without the model composing shell: which process is on a port, how much space is free, what fills a folder, which of your processes are busiest, memory, one process, battery, macOS and hardware, network. wisp runs fixed, read-only commands (or reads the process table through libproc), parses them, and returns a short table. Decided in ADR 0034.

Arguments

What each topic reads

Limits and controls

Errors come back as error: …: a port outside 1 to 65535, a path that is not a folder, or process without a name (the message says how to call again).

Measured

SystemInfoEvalTests (scripts/check eval): the 54 plain questions of system_info.json, none naming the tool, every topic in several phrasings and five ambiguous questions that accept each topic a careful operator would, each asked once, with run_command and memory also offered. The release asks a fixed subset of 24 spread over the topics, against a floor set from the configured model’s history (39 of 54 for the whole set, 16 of 24 for the subset); WISP_EVAL_FULL=1 asks all of them (measurements.md, “The case sets” and “The floors”). Until 0.23.0 it was eight questions twice each: on 2026-09-24 on the system model, after the process name became required, 15, 16, and 16 of 16 on three runs. Before that change (2026-09-23) the question naming an app failed about half the time, the model leaving out the name and falling back to ps.

memory

The conversation’s memory, for the model: one tool with verbs, as the person’s chat commands have them. recall restores, for the current turn, earlier material that the model’s context holds only as a reference, a marker, a summary, or a fact. note records a fact the model wants kept, as the model’s, below the person’s and a tool’s. task proposes the conversation’s task and its objective, never over the person’s or a caller’s. It reads only the conversation’s own record and the audit log it refers to, writes only the conversation’s facts, runs no command, and needs no approval. This is phase 4c of the layered-context proposal (“Recall”, decisions D2, D8, and D12), widened from a recall tool to memory on 2026-09-30.

It is not the Mac’s memory: system_info’s memory topic reports RAM. The tool’s description says so, and the eval checks that questions about RAM still go to system_info (below).

Off by default. Context checkpoint 2 scored fewer answers with memory than without it on every model it measured (the on-device model, granite4.1:8b, and gemma4:12b), so since ADR 0057 a conversation gets it only when you turn it on or name it. Turn it on for every conversation given every tool:

wisp config set context.memory true

or /config set context.memory on in chat, or "context": { "memory": true } in ~/.wisp/config.json; it applies from the next conversation. With it on, everything on this page behaves as it did before ADR 0057.

When a conversation has it

An explicit list is exactly that list, so the MCP git thread of AGENTS.md (tools: ["run_command"]) stays run_command alone, and --tool read_file --tool memory has memory with the setting off. A conversation without memory is not given the system prompt’s rule about it, and its references say call it again to see it for a tool that only reads, and its output is not repeated; do not run it again to see it for a command or an edit instead of naming a recall; the facts, the running summary, and the references themselves are the same. You can still see any earlier output with /show and /inspect context, which cost the model nothing. With memory, the tool is there from the first turn: a note needs nothing stored, and a recall before anything is stored says the first turn is all in view.

Arguments

One text argument, because the references and markers the model reads already spell a recall (to see it: memory "recall entry 7", (showed the person the read_file output, entry 7), and the entries named in facts’ sources, such as from tool read_file, turn 2, entry 4), and a small model copies a phrase more reliably than it fills optional fields. Every tool’s schema is in every request (decision D4 measured them), so the schema has one field. The first word is the verb; remember is taken as note, and a request with no verb is a recall, so entry 7 alone works. task followed by text proposes the task (below); task alone recalls it.

Tool definition as the model sees it (description, then the argument’s guide):

This conversation's memory, not the Mac's RAM (that is system_info): recall earlier material in full, or note a fact to keep.
request: "recall entry 7", "recall turn 3", "recall task", "recall fact codename", or "note entity release codename = BLUE HERON".

It costs 110 tokens in every request’s instructions, measured with tokenCount(for:) on the on-device model on 2026-10-01 for this text (recall alone cost 103). The task verb is not among the guide’s examples: one added on 2026-10-01 (“task fix the CI build; objective: swift test passes”) took the definition to 123 tokens in every conversation with memory, and was dropped on 2026-10-03; the verb works as before (below).

recall

A header saying what was found and where its content was read from, the lines of one page, then a last line that names the next page or says it ended:

entry 4: read_file output, turn 2 at 14:05:12, from the audit log
arguments: {"path": "/work/harbour/docs/overview.md"}
1	# harbour sync: design overview
…
77	leaves the previous manifest intact and the next run repeats only the unfinished work.
[end of file]
[end of what recall found]

A page that is not the last ends [more: memory "recall entry 4 from line 60"]. A fact’s history names each version’s id, source, time, value, state, and the entries it came from:

fact "ci": 1 subject
tests ci: 2 versions, oldest first:
- c3 [tool run_command, turn 2, entry 9] at 11:02:10: failed (exit status 1); superseded by c9
- c9 [tool run_command, turn 11, entry 30] at 11:07:40: passed; current
memory "recall entry N" shows what a fact came from.
[end of what recall found]

When nothing matches, one line starting memory: says why and what there is: the range of entries or turns stored, or the subjects the conversation knows. A turn’s own entries are not stored until it ends; the model has them whole until then.

Where the content comes from. The audit log is the one verbatim record (decision D8), and the store refers into it: each entry names the audit events that recorded it (tool.result for an output, prompt, response, tool.call). A recall reads an entry’s content from that event. The store’s own copy of the entry, which it keeps in memory (and in the .store sidecar for dropped entries) so that composing never reads the audit files, is the fallback for an entry the audit does not hold: text the model wrote before a tool call, which no event records on its own; an entry whose event has rotated out of the files kept; or a conversation with audit.enabled: false. The header says which (from the audit log, from the conversation's store).

After its turn. What a recall returns is an ordinary tool output: whole in its own turn, and from the next turn on a reference like any other ([output of entry 40 not repeated: memory at …; to see it: memory "recall entry 40"]), so restored material ages out and is never carried in full again.

summarise

summarise entry 7
summarise output 3f9a2c1b overview

The notable lines of a stored entry or output, or with overview an overview, by exact readers and no model (ADR 0050). The notable summary leads with what matters given how the output ended: for a build or test output in a format triage reads, the errors grouped by file or test, the first of each with its line and the lines after it and the later ones in the same place counted under it, the warnings tallied, and the test failures; for a log, its severities and the rare or severe messages; for JSON, its shape; else the lines that mention an error, else the first and last lines. Each point cites its line (L154), the stored output’s numbering, so a recall from that line lands on it. The overview gives the size, how it ended (a command’s exit status, else the last line), the kinds of line counted, the lines that look like headings with their numbers, and the first and last lines. Both say what no reader explained, so the model knows what condense could still answer, and both fit the budget.

notable lines (exact readers, no model): 2,340 lines, 187 KiB; exit status 1 (failed)
2 errors in 1 place; the first of each, root causes first:
L154 error at Sources/B.swift:42:9: cannot find 'frob' in scope (+1 more in Sources/B.swift)
  L155:     frob(1)
  L156:     ^~~~
1 warning (Sources/A.swift ×1)
1 failure-looking line no reader explained, such as: error: fatalError: 1 of 3 targets failed

condense

condense entry 7: why did the link step fail

Answers the question after the colon from the whole of a stored entry or output, by a chunked pass of the conversation’s own model: the output is cut into chunks within the budget (at most 48; the result says when the output had more), each chunk is asked the question in a fresh tool-less session of the same model and told to answer nothing here when it has nothing, the answers that say something are joined in order, and when they do not fit the budget the model is asked once more to combine them. The result names the question, the lines and chunks read, and that the model wrote it; a chunk that fails is counted. Each chunk is one of wisp’s own side calls (ADR 0053, amended 2026-10-11): a model that can think is asked not to, whatever the conversation or the model’s settings choose, and its thinking is not recorded as the turn’s, as the fact distiller, the running summary, and triage are run. It is the one verb that costs model calls, in proportion to the output’s size, and only when asked. Without a model attached (an agent made directly, tests) it says so and points at summarise and the filters. Paging alone is not enough for a long output: a model reading page after page can lose the earlier pages to condensing, so this asks about all of it at once.

note

note SUBJECT NAME = VALUE

SUBJECT is a subject kind the model may note, NAME what the fact is about, and VALUE its value, as the person’s /fact SUBJECT [NAME] = VALUE is written. The forms a small model writes are read too: SUBJECT: NAME = VALUE, and SUBJECT NAME: VALUE with no =. Quotes around the value are dropped.

The result says what was kept, or why not, in a form the model can act on:

noted: entity release codename = BLUE HERON (a proposal until the person keeps it)
noted: tests ci = green
error: no subject weather to note; use one of task, decision, preference, entity, tests, workdir, branch, such as note entity release codename = BLUE HERON
error: say which entity it is before the =, such as note entity release codename = BLUE HERON
error: write note SUBJECT NAME = VALUE, such as note entity release codename = BLUE HERON
error: at most 12 notes a turn; the rest were not kept

In facts’ lines a noted fact’s source reads model, noted, turn 4.

task

task THE TASK; objective: WHAT DONE LOOKS LIKE

Proposes the conversation’s task as the model’s fact (subject task, source model, method noted), with its objective after objective: (also . Objective: or , objective:), kept as one value, THE TASK; objective: WHAT DONE LOOKS LIKE. It is recorded when the turn ends and shown next to each request from the next one (decision D6). The task the person set with /task, or an MCP caller with respond’s task, is never replaced: the request is refused and the result names the task as it stands. task alone, and recall task, recall the task. A task counts towards the turn’s 12 notes, and is cut to 300 characters.

noted the task: add a --dry-run flag to harbour sync; objective: sync prints the plan and copies nothing
error: the person set the task, and it stays: fix the CI build
error: write task THE TASK; objective: WHAT DONE LOOKS LIKE

With the per-request assessment on, the model’s task is also inferred before each request in chat (context-management.md, “The assessment per request”); a task the model proposed either way is the model’s, method noted here and inferred there.

Audit

Each call is a tool.call and tool.result like any tool’s, and a context.memory event with the request and its action. A recall names what was restored: the target (output for a stored output, with its id as output), the entries, facts, and summary versions, the audit events read, the filter applied, and whether the content came from the audit log, the store, or both. A summary names its target and which summary (notable, overview); a condense names its target and the chunks the model read, and a failure when it had no model, no question, or chunks that failed. A note names the subject, name, value, and class kept, or the failure; a task names the value kept or the failure (pinned when the person or a caller set it); each note or task kept is also a fact.recorded (method noted) when its turn ends (logging.md).

Limits

Evaluation

Measured in the context eval’s recalling and noting scenarios (ContextEvalTests, MemoryStrategy); the figures are in the proposal, “Memory, 2026-09-30”. Context checkpoint 2 compared the whole stack with and without memory on its sustained scenario, three runs on each of three models, and found it no help: 4.3 against 5.3 of 10 on the on-device model, 7.3 against 8.0 on granite4.1:8b, and 8.0 against 9.3 on gemma4:12b (ADR 0057). SystemInfoEvalTests offers memory beside system_info and run_command and counts the turns that call it on a question about the Mac: on 2026-09-30, on the on-device model, none of 16 did.

Implementation

MemorySource and Memory (the verb, the note’s form and rules) in harness/Sources/WispCore/Session/Memory.swift; Recall (what a recall names, gathering and paging the material, pure) in Session/Recall.swift; MemoryTool in harness/Sources/WispCore/Tools/MemoryTool.swift; and AuditLog.event(_:) with the AuditReader sinks in Audit/AuditLog.swift. The agent publishes its store, facts, subject kinds, and turn to the tool before every request and records the turn’s notes when it ends (Agent.memory). Tested in MemoryTests, RecallTests, AuditReadBackTests, and MemoryEvalTests.

models

The models wisp can run, for the model: the same actions the person has in wisp models and /models (ADR 0059), less the person’s own. The model can read the listing and one model’s facts at once, and ask the person to pull, enable, disable, or check a model; it cannot trust a publisher or switch the conversation to another model. Every rule (a disabled model refused under any spelling, the capability check on enable, the publisher question before a pull) is the person’s own, from one place, ModelActions.

Off by default. Like memory (ADR 0057), a conversation gets it only when its tool list names it or the setting turns it on for every conversation given every tool:

wisp config set tools.models true

or /config set tools.models on in chat, or "tools": { "models": true } in ~/.wisp/config.json; it applies from the next conversation.

So the MCP git thread of AGENTS.md (tools: ["run_command"]) never sees it.

Contract

Every reply is at most 4 KiB. A refusal is error: not approved: <reason>; a name that is not a model or a repository is error: … naming what a name must be.

Approval

A change the model asks for is an approval request of its own kind (ApprovalRequest.Kind.modelAction), judged as the command models pull <repo>, models enable <name>, and so on by the full classifier, as edit_file’s edits are judged as edit_file <mode> <path>, and asked whatever approval.threshold says: the rules rate them moderate (downloads a model from Hugging Face, changes the models wisp can run). The request names what the person needs:

• for a pull, the download (downloads 2.3 GB in 4 of 7 files from Hugging Face, as mlx:<name>, or that nothing needs fetching), the publisher (trusted, or not trusted: approving pulls it this once, and only the person can trust it, with /models trust), and the licence;
• for the rest, what changes in config.json.

The terminal’s dialog offers only those keys ([y]once [n]o for a pull). Declined, timed out, or unanswered, the request is refused and nothing changes. Under wisp mcp the tool is reachable only through respond, and its requests go to the client’s elicitation and to wisp approvals (with approval.outOfBand, the default), the first answer winning; silence refuses (../mcp.md, “Approval”).

A pull in the background

Once the person approves, the pull runs beside the conversation (Session.modelPulls), at most one per repository: the tool returns at once, the turn goes on, and the model is told not to call again to check on it, because wisp never re-runs a call to see how it went. A pull of a publisher not trusted goes on as an answer of “once” would; the person’s approval named the publisher and licence. A real directory at the link’s path is kept (only the person may agree to replace it).

When it ends, a note is posted to the conversation that asked (by its audit session: chat’s own, an MCP thread_id):

[wisp: the pull of mlx-community/Qwen3-4B-4bit you asked for (approval 7f3a2c1d) finished: fetched 2.3 GB; it is mlx:Qwen3-4B-4bit. Its capabilities are undeclared until it is checked: models enable mlx:Qwen3-4B-4bit asks to turn it on and check it]

A failure, or a cancellation (/models cancel in chat, or the session ending), says so; what arrived is kept for the next pull to resume. Chat shows the note as it arrives; the model reads it with its next turn, where the agent stores it as a notice (ThreadRecord.Kind.notice), which, like a command the person typed, is no turn of its own. Under wisp mcp a client that has moved on finds the note on the thread’s next respond, and the outcome in the thread’s audit (wisp://threads/{thread_id}/audit, model.pull).

Audit

Each call is tool.call and tool.result. A change asked for records classifier.verdict, approval.requested, and approval.decided (its approvalID the request’s id), then what the change writes with source tool and approval that id: config.change, model.verified, model.publisher, model.pull (../logging.md).

Limits

• List pages of 20 models; every reply at most 4 KiB.
• Pulls are MLX models from Hugging Face, as wisp models pull fetches them (../wisp.md); the same names, files, sizes, digests, lock, and link rules apply.
• The listing asks every backend, as /models does: an Ollama that is not running is one line in parentheses.
• Not offered: trust (the person’s, /models trust PUBLISHER or t to a pull’s question) and switch (a model choosing its own successor is a decision not taken; ADR 0059).

ask

Lets the model ask you one question in the middle of a turn and go on with your answer: which of two things you meant, or a value it cannot find. A question is not a permission: no answer runs anything, and every command the model runs afterwards still passes the policy, the classifier, the gate, and the sandbox. Decided in ADR 0062; the inquiry effect each face carries is in ADR 0044’s terms.

Off by default. Like memory and models, a conversation gets it only when its tool list names it or the setting turns it on for every conversation given every tool:

wisp config set tools.ask true

or /config set tools.ask on in chat, or "tools": { "ask": true } in ~/.wisp/config.json; it applies from the next conversation.

So the MCP git thread of AGENTS.md (tools: ["run_command"]) never sees it.

Contract

Every other outcome is a fixed line the model can read: the person declined to answer. Do not ask this again; say in your reply what you needed; no answer within 5 min. Do not guess what the person would say. Say in your reply what you need, and stop (only when a deadline is set); no person can answer here (wisp respond); say in your reply what you need; under wisp mcp, waiting for the person: "…" (question a1b2c3d4). Their answer reaches you as a note on a later turn. Do not guess it. … (../mcp.md, “Questions”). Silence is never an answer: the model is told to stop, and the verification pass flags a reply that says you chose or confirmed something when no question was answered (../verification.md).

Limits and controls

How each face asks

Who may answer: you, in one of wisp’s faces. The agent that called wisp mcp cannot: nothing in the MCP conversation answers a question, wisp’s own model is refused wisp questions answer|decline by the default policy and cannot write ~/.wisp from the sandbox, and the command runs only from a terminal (../trust.md). Your answer is not private from that agent: a thread’s output, context, facts, and audit are readable through wisp://threads/{thread_id}, and the dialog says so.

Example

› Replace the config with the new defaults.

  ⚙ ask Which config did you mean?

? the model asks
  Which config did you mean?
  1  ~/.wisp/config.json
  2  ./wisp.json
  3  none of these
  type a number, or press Enter to decline › 2

The model gets chose: ./wisp.json and goes on in the same turn; the answer is c4 answer "Which config did you mean?" = ./wisp.json among the turn’s facts.

wisp as an MCP server

wisp mcp speaks the Model Context Protocol over stdio, so other agent harnesses can delegate work to the on-device model. It advertises respond; ten condensing tools that keep raw material on the Mac and return a small result (triage, summarise_diff, draft_change, scan_secrets, redact, condense_log, json_shape, dependency_audit, flaky_tests, hot_paths); set_fact_scope; and close_thread. wisp’s own tools (run_command, read_file, system_info, and the rest) are not exposed directly; they are reachable only by asking respond to use them, so every command runs under the model’s policy, sandbox, and approval with the audit trail of a turn (ADR 0006, amended). Stdout is the protocol channel; diagnostics go to stderr. The server runs until the client closes stdin.

Client configuration

Claude Code (.mcp.json):

{ "mcpServers": { "wisp": { "command": "/path/to/wisp", "args": ["mcp"] } } }

Codex (~/.codex/config.toml):

[mcp_servers.wisp]
command = "/path/to/wisp"
args = ["mcp"]

In this repository, .mcp.json runs scripts/wisp-mcp, which starts the release build under the name wisp mcp (claude-code), from WISP_MCP_CLIENT in the server’s env (wisp mcp when unset), so ps tells one harness’s server from another’s (ADR 0061). A Codex configuration that runs the launcher may set env = { WISP_MCP_CLIENT = "codex" }.

Client compatibility

wisp speaks MCP through the official Swift SDK (0.12.1). Where the SDK is stricter than the protocol, wisp normalises the message before the SDK sees it, in CompatibilityTransport, rather than refuse a compliant client. One case so far: an initialize whose capabilities.experimental has object values, which the specification allows and Codex sends ({"codex/auth-change": {}}); the SDK declares the field as a map of strings and fails the whole request with -32603. Each object value is replaced by its compact JSON text ("{}"), nothing else in the message changes, and wisp never reads the field. Found and fixed on 2026-09-20 against 0.1.4; the captured request is a regression test.

The same wrapper sees every outgoing message, so it records the JSON-RPC id of each approval dialog (elicitation/create with _meta wisp/approval), which the SDK does not return; that is how a dialog answered another way first is withdrawn with notifications/cancelled (“Approval”, below).

Discovering the model’s tools

wisp’s own tools are not MCP tools, so a client learns about them from two resources:

Both are generated from the live registry, so they cannot drift from what the model can actually call.

Inspecting wisp

More resources let a client read wisp’s own state without spending a model turn (ADR 0018). They are read-only and show the same views as the model’s inspect tool, wisp config, and chat’s /inspect context. Everything about a respond thread is under wisp://threads/{thread_id}; the URIs with {…} are listed as resource templates (resources/templates/list).

Collections are paged at 50 rows: append ?page=N (from 1); each page gives page, pages, total, and next, the next page’s URI or null. The audit collections (wisp://audit, wisp://audit/{session}, wisp://threads/{thread_id}/audit) hold events, 100 a page, oldest first; &limit=M sets the page (1 to 500), each page gives events, limit, and last (the newest page’s URI) beside page, pages, total, and next, and each event is the object the audit file holds. A context or a stored output longer than 16 KiB is paged the same way, and each page after the first begins with a line saying which page it is. A page past the last, a turn the thread has not had, and a malformed URI are protocol errors (invalidParams).

The context resources compose the view from the thread’s store, in memory, at no cost to the model (decision D12 of the layered-context proposal). They are served only while the thread is open: a closed or evicted thread’s context went with it, and reading it says so, while its summary, output, and audit remain. A thread’s turns are numbered as its audit events number them, from 1. A thread resumed from a saved conversation (chat’s --resume; MCP threads are not resumed today) shows its earlier session’s entries as carried into every turn of its own, with the references and cuts the saving session last sent; the contexts of the saving session’s own turns can be composed only as far as the saved sidecar allows, and are not addressable here.

The facts resources read the stores in memory, likewise at no model cost; a thread’s own only while the thread is open. A thread keeps facts unless facts.enabled is false in the config, in which case reading its facts is an invalidParams error saying so (context-management.md, “Facts”).

The audit and output resources read the audit file, so they are empty (and an output reference is not given) when audit.enabled is false. Reading any resource is not itself audited (the model’s inspect calls are, as tool calls). wisp tools --json and wisp tools --markdown print the same text on the command line. The respond tool description points at wisp://tools.

How to prompt for a tool, in short: name it, give exact arguments, say how to report the result, one tool per prompt, and restrict tools on a new thread to what the task needs. For example:

Use run_command with working directory /path/to/repo to run exactly: swift test 2>&1 | tail -3 .
Report the exit status and output verbatim, nothing else.

Tools

respond

Run a prompt on the on-device model, with wisp’s tools available to it, on a conversation thread.