Skip to content

Work classification

Steps for

Classification asks a model to label each finished conversation: what kind of work it was, whether it reached its goal, and what evidence supports that judgment. Stats uses these labels for its work-mode, outcome, and work-frontier charts, and for the period comparison in its Changes tab. Classification and automatic labeling are off by default. Existing explicit choices stay unchanged. Enable them here or in setup’s Label conversations guide.

Labeling digests always remove common secret patterns before text limits apply, even when archive redaction is off. Pattern matching cannot remove every secret or identifier. Review the destination before enabling labeling.

App
Settings → Classification
CLI
hansard classify
Settings, Classification: labeling status, automatic labeling, the wait before labeling, conversation summaries, and the providerSettings, Classification: labeling status, automatic labeling, the wait before labeling, conversation summaries, and the provider
  1. Open Settings → Classification.
  2. Turn Label conversations on to label conversations. Turn it off to stop all classification.
  3. Turn Label new conversations automatically on to let the watcher label conversations every 15 minutes. In Wait before labeling, choose how long a conversation must go without new messages before it is labeled, from 12 hours to 14 days, or choose Custom… and enter a value such as 36h. The default is 7 days. The row also reports the last automatic pass.
  4. To keep a short summary of each conversation after it ends, turn on Summarize conversations after they end. It is off by default. Continue from a summary and recall read the summaries. To summarize older conversations, run hansard summaries run.
  5. Under Model, choose a Provider. Automatic tries Claude Code if you are signed in, then Codex, then Ollama, and shows which one it uses.
  6. Each provider labels with its own light model: claude-sonnet-5 through Claude Code or the Anthropic API, gpt-6-luna through Codex or the OpenAI API. To use a different model, choose a provider and enter it in Model. Clearing the field restores the light model, never the model you chat with. Jev API key sends each conversation to TypeSafe’s Jev model with TYPESAFE_API_KEY. Jev returns typed labels with calibrated confidence instead of written reasons, is billed by input tokens only, and does not support Task value. Horizons from Jev are the midpoint of the chosen range.
  7. Under Extra labels, turn optional label sets on or off.
  8. To label waiting conversations now, select Label now beside Label waiting conversations, which also reports how many are waiting. To add the extra labels to conversations that are already labeled, select Add now beside Add to labeled conversations. If the provider sends data off this computer, Hansard asks you to confirm first. Stop ends the run.

A run labels up to 200 conversations, oldest first, and shows pending, complete, retrying, and failed counts while it works. It resumes where it left off if interrupted.

Check what is configured and how much is pending:

Terminal window
hansard classify status

Turn labeling on, then automatic labeling:

Terminal window
hansard classify enable
hansard classify auto enable

Label pending conversations now, or tune the automatic pass:

Terminal window
hansard classify run
hansard classify run --profile enrichment --limit all
hansard classify auto --stale-after 3d --limit 50
hansard classify auto disable

To inspect one conversation’s stored labels, run hansard classify show followed by its session ID. hansard classify clear --session followed by a session ID removes that conversation’s labels, and hansard classify clear --yes removes every stored label. Clearing labels never touches archived conversations.

hansard classify run accepts these options:

Option Effect
--profile <profile> Chooses which request to run: core (the conversation request, default), task, enrichment (every enabled request except core), or all.
--limit N|all Sets the maximum number of jobs. The default is 200.
--source <provider> Labels only one harness’s conversations.
--since 30d|all Labels only conversations that started in the window.
--include-sdk-jobs Also labels one-shot SDK jobs, which are skipped by default.
--force Labels conversations again even when their labels are current.
--batch-size N Sets conversations per model request, up to 16.
--workers N Sets how many requests run at once, up to 8.
--no-wait-for-imports Starts without waiting for running imports to finish.
--json Prints a machine-readable summary.

hansard classify auto takes --stale-after (the idle threshold), --limit (jobs per 15-minute pass, default 100), and --window, which limits automatic labeling to conversations active within it, 30 days by default. --window all removes the limit. Older conversations are labeled only by hansard classify run. The first automatic pass starts a few minutes after the watcher launches, and pending imports always go first.

Backend Setting What it uses
Automatic auto (default) Claude Code if it is signed in, then Codex, otherwise Ollama.
Ollama local-model Your Ollama server, http://localhost:11434 by default. Needs a model tag such as qwen2.5:7b-instruct. Hansard asks the model not to think, so a thinking model returns its label before the request times out.
Claude Code sign-in claude-cli Your signed-in Claude account. No API key.
Codex sign-in codex-cli Your signed-in Codex account. No API key.
Anthropic API key anthropic ANTHROPIC_API_KEY from Hansard’s environment. Billed by usage.
OpenAI API key openai OPENAI_API_KEY from Hansard’s environment. Billed by usage.
Jev API key jev TYPESAFE_API_KEY from Hansard’s environment. Billed by TypeSafe.

To choose a backend and model from the CLI:

Terminal window
hansard config set classify.backend local-model
hansard config set classify.model qwen2.5:7b-instruct

Hansard remembers a model for each backend. Leaving the model blank restores that backend’s light default. It never selects the CLI’s interactive model. The Codex CLI runs classification at low reasoning effort unless you set classify.reasoningEffort.

For every connection Hansard makes, see What leaves your machine.

With search by meaning on, Hansard can answer some label requests from the labels of the most similar conversations instead of the model. First measure how often that agrees with the model on your archive:

Terminal window
hansard classify neighbors

The command predicts each labeled conversation only from conversations that started before it, and records for each label the vote share at which the neighbors agree with the model at least 90% of the time. Then turn it on:

Terminal window
hansard config set classify.neighbors.enabled true

A request is answered from neighbors only when every label in it reaches its recorded share. Every other conversation still goes to the model, so this never adds a request. The conversation request, which holds work mode, outcome, and evidence, always goes to the model. Labels from neighbors count in Stats like the model’s, stay out of Personal Sync, and give way to a model label for the same conversation.

Settled conversationIdle for 7 days by default
DigestUp to 16,000 characters built from the archive
ModelSigned-in Claude or Codex CLI, an API, or Ollama
LabelsWork mode, outcome, difficulty, and work performed, shown in Stats and Behavior

Each conversation is labeled by one model request per view of it, so the conversation is sent once instead of once per label. These request defaults apply only after labeling is enabled:

Request Reads Labels On by default
Conversation The conversation digest Work mode, outcome, success and failure evidence, purpose, task family, primary output, collaboration mode, decision autonomy, your expertise in the task, and who made the planning and execution decisions Yes, always
Task horizon & O*NET work Your requests only, never the agent’s replies How long the task would take an experienced person without AI, ten difficulty facets rated 1 to 10 (including how hard mistakes are to undo, how novel the task is, how much the environment changes, and how much information must be found), task boundaries, and the work functions matched to a copy of the O*NET taxonomy bundled with Hansard (one extra lookup request; nothing is requested from O*NET) Yes
Task value The conversation digest A rough, comparative value estimate for the task No

A field the model returns malformed is retried on its own; the rest of the reply is kept.

The core labels use these values:

  • Work mode: Plan, Build, Fix, Understand, Test, Operate, Analyze, Orchestrate, or Communicate.
  • Outcome: Succeeded, Partially Succeeded, Failed, or No clear goal. Success rates count only the first three, called goal-bearing sessions.
  • Success evidence and Failure evidence: how strong the proof is, from 1 to 5. No evidence observed means the model checked and found none. Unclassified means no current label exists yet.

Horizon and difficulty are judged from your requests alone, never from how fast the agent worked or whether it succeeded.

For a subagent run without a human request, task labeling reads the request its parent agent wrote from the parent’s archived conversation. These labels record request_author: agent, and Stats keeps them apart from human task figures. A run whose parent request is unavailable remains not applicable and sends no task request.

If the parent request becomes available later, preview the affected runs:

Terminal window
hansard classify subagents --dry-run

Run hansard classify subagents to label them. The default window is 30 days, with a limit of 200 runs. The automatic pass never sends this catch-up work. Each run uses one task request, sent in batches, and at most one O*NET selection request. Existing conversation labels remain in place.

Hansard skips machine-started sessions such as status probes and Codex action assessments, and one-shot SDK jobs unless you include them. It labels a conversation again only when its content or the label definitions change. Switching the model or provider keeps existing labels; run hansard classify run --profile all --force to relabel with the new one.

  • Stats → Work shows work modes and the work frontier, and Stats → Outcomes shows outcomes and evidence. Detailed charts appear once more than 25% of eligible conversations are labeled; before that, a coverage card shows progress. See Stats.
  • The Stats Changes tab compares work-mode mix and outcomes with the prior period, and its Write a retrospective button uses the same backend. See Compare periods.
  • In a classified conversation, the Details panel beside the conversation includes a Classification section with its work mode, outcome, evidence, and status flags such as verified success.
  • hansard stats includes a classification section, and hansard classify show prints one conversation’s stored labels.

Labels are a model’s estimates, not ground truth. Use them to compare large groups of conversations rather than to grade a single one.

To stop only the automatic background pass and keep explicit runs:

Terminal window
hansard classify auto disable

To turn classification off entirely:

Terminal window
hansard classify disable

In the app, turn off Label new conversations automatically or Label conversations in Settings → Classification. Existing labels stay until you run hansard classify clear --yes.

A run or automatic pass stopped with a usage, spend, or sign-in message. The CLI backend reported a limit or is no longer signed in. hansard classify status shows the reason under the last pass. Sign in again or wait for the limit to reset; the watcher retries on its next pass.

Settings says the model declined some conversations. The model refused to label them on usage-policy grounds. Hansard labels the rest of their batch one conversation at a time, and each declined conversation waits a week before it is tried again, unless its content or the provider changes. The run and the automatic passes continue.

A run waits before starting. Explicit runs wait for active imports to finish and for a short quiet period. To start anyway, add --no-wait-for-imports.

Classification requests appear as conversations in the archive. Run hansard classify cleanup --dry-run to preview them, then hansard classify cleanup to remove them.

Stats shows a coverage card instead of charts. Fewer than 25% of eligible conversations have current labels. Run hansard classify run --limit all, or wait for automatic passes to catch up.