Stats and Behavior

Use the three activity views for different questions. Start with Stats for a snapshot, Usage for plan limits, and Behavior for change over time.

StatsSee totals and compare harnesses, models, projects, tools, tokens, and spend.

UsageTrack locally captured plan limits and estimate subscription utilization.

BehaviorCompare one period with the equally long period immediately before it.

Stats

Use Stats in the app

Open Stats from the app sidebar. The controls remain visible beside every Stats tab, so first set the scope before interpreting a chart:

1. Choose 1M, 3M, 6M, 1Y, All, or Custom under Time range.
2. Use Agent, Chat, Subagents, and SDK jobs under Include to decide which session kinds contribute to totals. One-shot SDK jobs are off by default.
3. Choose Harness, Lab, Model, Project, or Device under Show by. The filter below it can then include or exclude individual groups without changing the underlying archive.
4. Use In, Out, and Cache to control token direction, User msgs or Convos for the activity calendar, and Totals or 100% for stacked-chart scale.

Start on Overview to establish the activity window and conversation shape. Then open Tokens & spend for directional usage and pricing coverage, Models for model lifecycle and settings, Work & autonomy for human-turn rates and classifications, Tools & harnesses for tools, commands, skills, MCP servers, slash commands, and file references, and Projects for where the work landed. Reliability surfaces recorded API and tool failures; Memory describes the separate memory archive. All puts the sections in one scroll when comparison is more useful than focus.

The page is interactive rather than a static report. Change one control at a time, confirm the subtitle’s current scope, and use the information buttons on individual cards to see their denominator and inclusion rules.

Terminal equivalent

Use the CLI for a compact terminal summary or a machine-readable result:

hansard stats
hansard stats --provider codex-cli --since 30d
hansard stats --repo github.com/acme/widgets --top 25

Use --tools to print only tool, skill, MCP server, slash-command, file-reference, and shell-command sections:

hansard stats --tools

Use JSON for agents and scripts:

hansard stats --json --top 100

Option	Purpose
--provider <provider-or-alias>	Filter to one provider or source alias.
--since 30d|90d|all	Select the archive date window.
--repo <repo-key>	Filter to an exact canonical project key.
--top <count>	Set rows per table and cap detailed JSON arrays.
--tools	Print only tool and command usage sections.
--include-sdk-jobs	Include one-shot SDK jobs in resource totals.
--json	Return the complete Stats payload.

One-shot SDK batch jobs are excluded from headline resource totals by default so automation does not overwhelm interactive activity. --include-sdk-jobs adds their resource use, but conversation-behavior measures remain separate.

The Where activity happens card has its own SDK-jobs checkbox. That local choice changes only that card; use the global option when SDK jobs should enter the resource totals.

Choose the right breakdown

Choose the identity that matches the comparison:

Show by	Use it to answer	Example
Harness	Which agent app or CLI handled the work?	Compare Codex with Claude Code.
Lab	Which organization owns the recorded harness or model?	Compare activity across model providers.
Model	Which recorded model handled the response?	Compare GPT, Claude, Gemini, or other model families.
Project	Where did the work happen?	Compare repositories or uncategorized work.
Device	Which Hansard installation recorded it?	Compare a laptop with a workstation.

Start with Harness when comparing tools. Switch to Lab only when the organization is the subject of the comparison; switch to Model when the recorded model is what matters.

When a session is missing from totals

Machine-generated status checks and similar probes stay searchable but do not enter activity or Behavior totals. The CLI reports their count on the Machine probes line. If a real project was classified as a probe, correct it with:

hansard config set stats.probeSessions.forceSession '["/path/to/project"]'

Use forceProbe instead when an automated path should be excluded.

Usage

Use Usage in the app

Open Usage from the sidebar. Select Capture accounts to read the currently signed-in supported provider CLIs once, or Start tracking to let the watcher sample them on its normal cadence. The Accounts list keeps each captured account separate; selecting one opens its current quota windows, resets, completed cycles, and daily peaks. Provider notes explain when a source offers activity counters rather than a quota percentage.

Providers without an installed CLI do not produce capture errors. Saved accounts remain visible when their CLI is unavailable on the current device. On macOS, Codex capture also discovers the CLI bundled with Codex.app or ChatGPT.app. Claude Code versions without the auth command require an update before capture.

Account labels and subscription calculations stay on the local installation. Capturing usage does not send a model prompt. A blank interval cannot be reconstructed later, so an empty chart after sleep or while the watcher was off is an honest gap rather than zero use.

Terminal setup

Enable or disable plan-limit sampling through the setup flow:

hansard config setup --track-usage
hansard config setup --no-track-usage

Usage is separate from archive spend. A plan-limit snapshot describes provider quota state; Stats derives recorded or estimated resource cost from archived sessions.

Behavior

Use Behavior in the app

Open Behavior and choose 1m, 3m, 6m, or 1y in the page header. The current window is compared with the equally long window immediately before it; the left and right arrows move the end of that pair backward or forward without changing its length. Read the headline changes first, then the aligned human-turn strip, work-time matrix, Movers, and—when classification coverage is sufficient—work-mode and goal-bearing outcome comparisons.

Behavior is not another Stats filter. Stats describes one selected scope; Behavior always constructs two adjacent windows and preserves both denominators. When the earlier window has no activity, the app shows No baseline instead of inventing a percentage change.

Terminal equivalent

hansard behavior
hansard behavior --period 3m
hansard behavior --period 1y --end 2026-06-30 --json

Option	Purpose
--period 1m|3m|6m|1y	Select the comparison period; the default is one month.
--end YYYY-MM-DD	Set the inclusive end date in local time.
--json	Return the complete Behavior payload.

Add classification

Run classification from the app

Open Settings → Classification. Turn on Enable session classification, choose Where classification runs, select a model and the label profiles, then review the destination disclosure before selecting Run core backfill or Run enrichment. Enabling the switch alone does not send anything. The run card shows pending, complete, retrying, and failed coverage while a batch is active.

Return to Stats → Work & autonomy to inspect current work modes, outcomes, evidence signals, and enrichment views. Open Behavior to compare work-mode mix and goal-bearing outcomes between adjacent periods. Detailed charts remain gated until the relevant profile covers more than half of eligible conversations; before that threshold, the app shows the remaining coverage instead of an empty chart.

Terminal equivalent

Classification adds work mode, outcome, evidence, task, difficulty, structure, and work-activity views. No model request runs until classify run is started:

hansard classify status
hansard classify run
hansard classify run --profile enrichment --limit all

The default run labels up to 200 conversations. Add --include-sdk-jobs only when one-shot automation should be classified too.

No evidence observed means classification completed without finding the requested signal. Unclassified means no current result exists yet.

Classification can send a digest off the machine

A loopback local-model backend keeps the classification digest local. Codex, Claude, Anthropic, OpenAI, and non-loopback model backends send the configured digest off-machine. Codex and Claude use the authenticated CLI login; Anthropic and OpenAI require the corresponding API key. Remote runs require confirmation.

Troubleshoot missing data

Hansard leaves provider gaps visible instead of guessing. Use the symptom to choose the next check:

Symptom	What it means	Next check
A model, token count, tool argument, or setting says Not recorded	The source may not store that field.	Open the relevant harness guide and review Known limitations.
Tokens appear without spend	No exact provider cost or trustworthy price match was available.	Review the recorded model and route; unpriced tokens remain visible.
SDK work is absent from resource totals	One-shot SDK jobs are excluded by default.	Enable the viewer checkbox or run hansard stats --include-sdk-jobs.
A real session appears under Machine probes	Its path or prompt shape matched an automated status check.	Add a forceSession rule as shown above.
Classification cards show coverage instead of charts	Too few eligible conversations have current labels.	Run hansard classify status, then classify the needed profile.
A newly supported field is still missing after an upgrade	The archive was created by an older importer.	Follow the harness guide’s full reimport command, then run hansard index rebuild.

hansard rebuild refreshes views from the existing archive. It cannot recover a field that the original import never captured.