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

spear-chat

the assistant; uses the corpus containing the current directory, else an ad-hoc one on it

spear-chat --corpus <name>

open a registered corpus by name (aliases --project, --checkout)

spear-chat --here

ad-hoc, on the current directory

spear-chat --with <name> / --without <name>

federate an extra corpus into this session, or drop one that would be attached

spear-chat --ask / --auto / --safe

the permission mode, as above

spear-chat --no-network

no network in any mode

spear-chat --local / --remote / --reds

which backend to talk to; without one, an interactive launch shows a picker and preselects the last choice. --pod is an alias of --remote

spear-chat --remote --pod-host H --pod-port P

point at a remote pod without editing pod.conf

spear-chat --provider anthropic --model <id>

use the Anthropic API instead of an OpenAI-compatible endpoint; it answers normative and general questions, and does not drive the coding core

spear-chat --ctx 65536 --temp 0.1 …

session settings, each also an environment variable; --help lists them all and the flag wins

spear-chat --fresh

start without this corpus’s stored conversation, and leave it stored

spear-chat --record FILE / --replay FILE

write down every model turn, or answer from a recording while the tools, files and gates still run for real

spear-corpus list|add|rm|scan

manage the corpus registry (/corpus in the chat)

spear-server

llama-server alone

spear-reindex [path]

rebuild a corpus with the curated walk

spear-index [dir] [--max-files N] [--exclude D]

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 add does 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 / /bad

Save 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.

/finetune

The 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:

  1. Freshness questions (“latest version of …”) auto-trigger a search before the model sees the turn; results and sources are shown.

  2. Explicit phrasings (“search the internet for …”) auto-trigger the same way.

  3. !web <query> — manual.

  4. The model’s own search_internet and fetch_url tool 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, /undo it — 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.