3.1. spear-chat
This page is the day-to-day surface: the commands outside the chat, the commands inside it, where the assistant’s knowledge comes from and on what delay it changes, and the guards that will interrupt you.
3.1.1. The corpus is the unit
Everything is a corpus: a working tree with its own retrieval index
and conversation history. A corpus declares what it does — indexer:
buildsystem selects the curated BitBake/Yocto walk, autoindex builds a
missing index on sight, prompt_file gives it a domain prompt, collection
names an existing index instead of deriving one from the path. kind is a
free-form label and changes nothing. Any other tree gets the generic indexer
and a collection derived from its path.
The active corpus is auto-detected from the current directory; otherwise a picker lists them. Launching in an unregistered multi-component workspace offers to split it into one corpus per large sub-tree, so that a huge upstream tree never dilutes the index. Projects and corpora is the full account.
3.1.2. Permission modes
One permission mode is always in force: --safe (the default, read-only),
--ask (each mutation and command confirmed) or --auto (no
confirmation), and --no-network takes the network away from any of them.
What each mode allows, and where writes may land, is
Security model; the flags and their aliases are listed in
Configuration reference.
3.1.3. Command line
Command |
Purpose |
|---|---|
|
the assistant; uses the corpus containing the current directory, else an ad-hoc one on it |
|
open a registered corpus by name (aliases |
|
ad-hoc, on the current directory |
|
federate an extra corpus into this session, or drop one that would be attached |
|
the permission mode, as above |
|
no network in any mode |
|
which backend to talk to; without one, an interactive launch shows a
picker and preselects the last choice. |
|
point at a remote pod without editing |
|
use the Anthropic API instead of an OpenAI-compatible endpoint; it answers normative and general questions, and does not drive the coding core |
|
session settings, each also an environment variable; |
|
start without this corpus’s stored conversation, and leave it stored |
|
write down every model turn, or answer from a recording while the tools, files and gates still run for real |
|
manage the corpus registry ( |
|
|
|
rebuild a corpus with the curated walk |
|
index any tree |
Note
Tools always run in the current directory, whatever corpus is
attached. To work on another tree, cd into it — no flag relocates the
workspace. See Projects and corpora.
spear-corpus scan <workspace> splits a multi-component tree into
per-component corpora by file count; the chat offers the same split
automatically when you open such a workspace. The command-line tool and the
in-chat /corpus are one implementation — same registry, same walk.
Entry points documents each executable in more detail.
3.1.4. In-chat reference
Direct tools, no model in the loop:
!read!ls!grep!find!edit!run!web
Session commands:
/search <q>/reindex/history/skills/undo/clear(/new)/tools/model(/switch)
/model(or/switch)Change backend or model without leaving the session.
/clear(or/new)Start a fresh conversation. The corpus, its workspace knowledge and its index are unaffected; only the conversation is dropped, from the store as well. To start one session without it and keep it for later, launch with
--fresh./corpus [list|add|rm|scan]The registry, without leaving the session. Registering does not switch corpus (
spear-chat --corpus <name>does), but a tree registered inside another is excluded from it at the next/reindex— which is the usual reason to register one./remember <fact>Record a fact about this workspace, as
/knowledge adddoes with its defaults (Workspace knowledge)./recall <rule>Add a working rule for every corpus; with no argument, list them (What the assistant learns, and when it takes effect).
/knowledge [add|list|show|accept|amend|revoke|check|export|purge|migrate-remember]Manage this workspace’s recorded knowledge (Workspace knowledge).
/forget <regex>Prune the history-search index. The archive file itself is kept.
/good//badSave the last exchange as a fine-tuning sample, or log a bad one. Bad ones are never trained on. See Training and fine-tuning.
3.1.4.1. Operator commands
These two are typed in the session and are never reachable by the model. The agent cannot rebind the document it is being held to, nor drive the fine-tuning machinery.
/standard [status|list|use|ingest|verify]Ingest a specification, bind one, inspect the binding. The binding decides how normative answers are grounded and is shared by every session on the machine, so check it before trusting one:
/standard status. See Normative mode: authoritative standards./finetuneThe fine-tuning control plane. See Training and fine-tuning.
Multi-line paste is supported; ctrl+c interrupts generation; Enter
confirms tool prompts; arrows, Home/End and ctrl+r come from
readline. quit, exit or q ends the session.
3.1.5. Web access
Four routes reach the network, and all of them disappear under
--no-network:
Freshness questions (“latest version of …”) auto-trigger a search before the model sees the turn; results and sources are shown.
Explicit phrasings (“search the internet for …”) auto-trigger the same way.
!web <query>— manual.The model’s own
search_internetandfetch_urltool calls.
search_internet finds pages and fetch_url reads one — HTML, PDF or
plain text — or saves it to disk. Both run in the chat process rather than in
the sandboxed shell, so reading works even in safe mode; but fetch_url is
http/https only and refuses any host resolving to a private, loopback or
link-local address. It reaches the internet, not the LAN the assistant happens
to sit on. A long PDF comes back in slices, and the result names the pages
range that continues it. save_as=<path> downloads the file itself, never a
truncated one, and is a mutation — so it obeys the permission mode like any
write. That is the route to a document you mean to ingest as a standard. The
pair is described from the harness side in The web pair.
3.1.6. What the assistant learns
Workspace knowledge, learned rules, skills, rules, the tool guide, the retrieval corpus and the history search each take effect on their own clock; What the assistant learns, and when it takes effect lists them and says which to use for what.
3.1.7. The base model
Two behaviours of the base model are worth knowing before you judge the harness by them:
Qwen3 models have a thinking mode. The chat disables it through
chat_template_kwargs.enable_thinking=false; leaving it off is deliberate, since here it only burns tokens.The model uses the workspace knowledge it is shown but verbally denies having a memory when asked. That is a pretraining reflex: judge it by behaviour, not by its self-description. If a bad answer lands in history,
/undoit — the model imitates its own past answers.
3.1.8. What a turn is allowed to do
Which request class a turn falls into decides which path runs it (Request modes and evidence): an implementation request runs on the coding core behind SpearHost (in a standard-bound session, on the normative runtime’s change workflow, The bound-session change workflow), a question about a bound standard on the normative runtime, and a change that must satisfy the standard through the MIXED orchestration. On every path:
the permission mode decides whether anything is written or run at all (Security model);
every path a tool touches must resolve inside the workspace, and a shell command is held to the same write scope as the file tools;
generated files and snapshot or third-party copies are never written;
every mutation is checkpointed (the file’s earlier content is kept under the state directory) and recorded in the audit trail;
a turn that keeps repeating a refused operation is stopped by the refusal breaker (Tool execution harness);
one model response, and the rounds and tool calls of a turn, are bounded (Configuration reference);
the verdict at the end is computed from what the tools did, not from what the model says it did (Evidence and verdicts).
The authorization rules are Security model; the confinement behind them is Sandbox, Network backend and Resource control.