Repository navigation
docs(wiki): Local Models, the walkthrough from install to cloud plus local - #808
Merged
Merged
Conversation
The local model window could hold one model. A second install was refused (409 already-installed), and a model a Remove kept could never be freed from the window again. The store can now hold several models, and exactly one of them is the model in use: the one the endpoint record lists, the runtime is started for and a session may be launched on. Server - LocalModelStateFile.library lists every model that passed the check (id, label, context, digest, size, coding agent). The service writes the entry when verify passes; the reducer carries it and remove drops it. An installed file of an earlier build counts its one model. - POST /api/local-model/install is allowed from installed: it adds a model, and the earlier one stays. A replaced job no longer deletes a model of the library, only an unchecked or partial download. - POST /api/local-model/use switches to a checked model: a job of the two steps verify and connect. The stored digest is compared before anything is loaded (model-changed otherwise). Nothing is downloaded. - DELETE /api/local-model/models deletes one model by its name, through the runtime's own delete, never by a path, never the model in use. - Adding and switching answer 409 sessions-open while a live session uses the endpoint. Until such a job ends installed, a session start is refused with the new code job-unfinished. - The view carries library (the state's entries joined with what the running runtime lists: ready, changed, missing, unverified) and store (the size of the blob folder). Both are cached and refreshed in the background, never read on the one-second poll. - With nothing installed, remove is offered while the store still holds models an earlier Remove kept. Window - The installed screen lists the models on this Mac with the context each was checked with, its state and its size on disk, with Use and Delete per row (Delete asks once, in the row) and Add a model. - In the chooser a model that is on this Mac already says so and is switched to without a download or a confirm screen. - A paused or failed job that has a checked model beside it shows the way back to that model. Every route is admin only in multi-user mode, like the existing ones. Not run on a Mac: the tests use fakes and the fake runtime, and the listing, store size and delete were checked against a real Ollama 0.13.0 on Linux, not the pinned 0.40.15 build for macOS. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
The guide, the API reference, the invariants and the two CLAUDE files describe the library with one model in use: the state file's list, the three verbs and their refusals, the two cached listings of the view, and the window's list with its row actions. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
… the Stop A job started from a model the person had stopped runs the runtime, and the model it ends on is in use and running. The stored "stopped" flag stayed set, so that model would not have started with the server again. Both verbs now set it back once their job started, the way Start does. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
A pi session on a custom endpoint got a model list entry with only the model id. pi then takes the model for a 128,000-token one (its footer reads "/128k") and asks for 16,384 reply tokens, so on a 65,536 or 32,768 window it never compacts before the server's real window is full. The entry now carries `contextWindow` (the full window) and `maxTokens` (a quarter of it, 8,192 at most) whenever the endpoint's context length is known: the same two figures the DeepSeek Harness patch already carries, now from one helper. An unknown length writes neither, as before. Measured on pi 1.5.2: with both fields `pi --list-models` shows the window, and the request carries `max_tokens: 8192`. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
…d DeepSeek Harness
An installed model knew one coding agent: the one it was installed with.
The launch check never asked about the agent, only about the endpoint
and the model, so nothing stopped a second one. What was missing is the
list, and a way to get an agent that is not on the Mac yet.
The install view gains `harnesses`: every catalogue harness the model in
use can be run with, each with how it stands (`ready`, `installable`,
`installing`, `setup-needed`), the literal install command, a readiness
mark for scripts, and the actions the server accepts for it. `cli` stays
the default agent, and names one that can be started whenever one can,
so a client that reads only `cli` never starts an agent that is gone.
`POST /api/local-model/agent { cli }` installs one more agent beside an
installed model. It is not a job and not an event of the reducer: the
state stays `installed` whatever the installer does, so a failed npm
install never blocks a session on a model that works. Same install slot
and same compiled stock command as the `agent` step, one at a time, the
outcome in memory only.
The catalogue:
- `pi` is no longer gated. Its two open questions were answered by a run
against a real model (the `name:tag` id reaches the runtime unchanged;
its first request is 2,096 tokens), and Codeman now passes it the
window. Its minimum is 65536 like the others: nothing below was run,
and no model row offers less, so no Mac's pick changes.
- `deepseek` is new. It is a launcher: its install command leaves it
with nothing to launch, so it is never reported installable (read off
`discovery.launcherProfile`, not the id) and a Mac is offered it only
where it was already set up. Its tool round trip was seen on a
scripted endpoint only; the header says how to gate it again.
- a row may carry `readyMark`; `opencode` has the measured one.
A switch no longer refuses for the agent a model was checked with when
another agent that can run it is on the Mac.
Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
…ne that is missing The installed screen gets one more block, "Start a session with": a chip per coding agent the model in use can be run with, as a radio group, the server's default selected. A chip that is not on the Mac says so. The main button follows the selected chip: - an agent that can be started: "Start a session", with that agent; - an agent that is not on the Mac: its literal install command above the button, and "Install <agent>". The click is the consent; the server runs its own stock command, and the window shows "Installing" on the chip while the model stays ready and another agent can be started; - an agent that needs a setup of its own (DeepSeek Harness without a terminal profile): one line that says where, nothing to press. A failed install shows the server's sentence under the chip with the installer's last words folded away; the model's own headline is untouched. On a stopped model Start stays the one main button. The choice is remembered on the device. A server that lists no agents gets the screen it had. Rendered in Chromium at 1440, 390 and 320 px on a dark and a light skin: the chips wrap, nothing leaves the window. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
…ed with, and the agent install - docs/local-models.md: the four agents with their first request, whether the window installs them and what was seen where (a real model, a scripted endpoint, Linux, not the pinned runtime); what differs for Pi and for DeepSeek Harness; installing one more agent beside a model. - docs/api-reference.md: `POST /api/local-model/agent`, `install.harnesses`, the `install-agent` action, and `install.cli` as the default agent. - docs/architecture-invariants.md, CLAUDE.md, src/web/CLAUDE.md: the rules: the agent is chosen per session, the agent install is not a job, a launcher is never installable, a readiness mark is a measured one, and the window's one builder for the agent chips. - docs/custom-model-endpoints.md: Pi's context window. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
`spawn_worker <name> local` started the one agent the model was installed with. The server now lists every agent the model can be run with, so the skill passes the choice on: - `local_model` adds `agents` (each with its status, whether it is the default, and the readiness mark the server measured) and `models` (what is on the Mac; only the active one runs). A new reason, `no-agent`: installed, but nothing that can run the model is there. - `spawn_worker <name> local:<cli>` (`local:pi`, `local:deepseek`, `local:opencode`, `local:claude`, also as `name:local:pi` in `spawn_workers`) starts an agent whose status is `ready`. Anything else fails the spawn before a session exists and names the agents that are startable. No agent is ever installed from here: that stays a person's click in the window. A Codeman that lists no agents knows one, and only that one can be named. - The readiness mark comes from the server when it names one, else from what this skill measured (OpenCode `┃`, Pi `extended-keys`), and `LOCAL_READY_MARK` overrides both. - A Pi worker on the local model is started with `piConfig.approveProjectTrust: false` (--no-approve). On a custom model Pi keeps no home, so it asks to trust the folder in every session with Trust preselected, and the task prompt's Enter would answer that. Pi's mark is the last line of its startup, a warning about tmux's `extended-keys` option. Its composer rule is painted in the first frame, before Pi takes Enter: a prompt sent at the rule stayed unsent, 2 of 2, and one sent at the warning was submitted, 4 of 4 (pi 1.5.2, Linux). It is a side effect, not a contract, so a Pi that stops printing it fails the spawn and the worker is deleted, never handed back on a guess. The preamble changed, so CODEMAN_PREAMBLE moves to 1.51.0 in the preamble, the SKILL.md copy of it and every version check, and the plugin mirror is synced. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
…local A page of its own in the user manual: install a model, pick the coding agent per session (and install one that is missing), keep more than one model on the Mac, and hand work to the local model from a cloud session with the codeman skill, with the prompts to say and the limits to know. Linked from the sidebar and the Home index, and from the two pages that already mention the local model (Custom Model Endpoints, Codeman Skill). Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
…not typed into
dsh-TUI 0.19.0 opens a setup guide ("Step 1 of 4") in every session
until a person has finished it once, and the guide's cursor is the same
glyph the skill waits for as the composer: the readiness mark matched on
it in 2 of 2 launches. An Enter there acts on the highlighted step,
which is a sign-in. A spawned worker was handed back "ready" on that
screen, and the first task prompt would have been typed into it.
After the mark, the rendered pane is now read once: a worker that shows
the guide is deleted and the spawn fails with what to do (finish the
guide once from the Run menu). For `local:deepseek` and for a plain
`deepseek` worker alike.
Also says which verb reads a local DeepSeek worker's answer: `sendmark`.
The harness reports the end of a turn, but dsh 0.2.2 renamed its
transcript file and Codeman reads an empty answer from it for now.
Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
A second scripted run, on dsh 0.2.2-rc.1 with a freshly installed dsh-TUI 0.19.0 under a scratch home: the model name reaches the endpoint unchanged, the first request is 6,983 tokens with 27 tools, and a tool round trip completes. Two things that version does differently are written down where a reader of the harness table looks: a setup guide opens in every session until a person has finished it once (and its cursor is the readiness mark), and its transcript file was renamed, so `last-response` is empty for it. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
…inished once Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
… session" Selecting a chip stored it for the device at once. Someone who clicked "DeepSeek" (Needs setup) or "Pi" (Not installed) just to see what it says then got a window that reopened on that chip: "Install Pi", or no main button at all, with "Start a session" out of sight. The device now remembers the agent a session was STARTED with, an opening of the window selects it only while it can be started, and a selection made in one opening does not carry into the next. Otherwise the server's default agent is selected, as before. Also: a real-browser test for the chips (they wrap inside the window at 1440, 390 and 320 px, the install command included, one tab stop), and one sentence in the API reference: a readiness mark says the composer is there, not that nothing else is (DeepSeek Harness's setup guide draws the same glyph). Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
…his model" refusal
Seen on a MacBook (M5 Pro, 2026-11-12): with a worker of the codeman skill open on the
local model, Stop, Remove and a switch of models answered
Sessions are still using this model: . Close them first.
A session an agent starts has no name of its own (a quick-start without sessionName), and
the refusal listed session.name. The tab of such a session shows the last folder of its
working directory, else the first eight characters of its id, so the sentence now uses the
same label (sessionLabel() beside sessionNamesUsingEndpoint()).
The sentence has shipped since 1.50.0 for Stop and Remove. This branch adds it to Use and
to the install of another model, which is where a person with local workers open meets it.
Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
…-button screen Seen on a MacBook (M5 Pro, 2026-11-12): pressing Use on a model in "Models on this Mac" ran the switch and then showed the screen that ends an install, "X is ready on this Mac" with Start a session alone. The list was gone, so deleting the model just switched away from meant closing the window and opening it again. That screen is right after a download: the person installed a model and wants a session. A switch is pressed IN the list by someone who is tidying it. A switch is a job without a `model` step, so the window now tells the two apart from the job it just watched and ends a switch on the whole installed screen: the list with "In use" on the other row, Add a model, Stop and Remove. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
…-choice # Conflicts: # src/web/CLAUDE.md
…er file Seen on a MacBook (M5 Pro, 2026-11-12), in a real Claude Code session: the lead started a Pi worker and an OpenCode worker on the local model in ITS OWN case, sent both their tasks at once, and reported afterwards that one written answer was lost. Both prompts had named the same file, codeman-answer-<token>.md, and the second worker's summary replaced the first one's. The code the workers wrote was not affected. The token was the second plus $RANDOM. Claude Code runs zsh on a Mac, and zsh hands every subshell the same $RANDOM until the parent shell reads it (measured there: four subshells, one number, where bash drew four). The token line is itself a subshell, so under zsh the "random" part never changed, and two calls in one second shared a token. Workers in their own cases never noticed: same name, different folders, and the marker is matched per pane. The token now ends in six characters of the worker's id. The test makes $RANDOM a plain variable that always reads the same, which is what zsh does, and runs two calls at once. The reference gets one sentence for hand-built markers in a fan-out. No new preamble version: 1.51.0 is not released yet. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
This was referenced Nov 12, 2026
Merged
Ark0N
pushed a commit
that referenced
this pull request
Nov 12, 2026
…loud plus local Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What this changes
A new page in the user manual, Local Models (
docs/wiki/Local-Models.md), the written walkthrough for running a coding model on your own Mac next to cloud models:It is linked from the sidebar and from the Home page's index (
test/wiki-home-index.test.tsrequires both), and the two pages that already mention the local model point to it: Custom Model Endpoints (which also gains one bullet on choosing the coding agent) and Codeman Skill.docs/wiki/is mirrored to the GitHub wiki by CI when a change to it reachesmaster, so the page goes live with the merge.What is not in it
Testing
test/wiki-home-index.test.tspasses (the Home index links every sidebar page).