Omniscio

Weekly Session Analysis (agent-friction dashboard + weekly deep analysis)

A read-only developer panel that mines your past agent sessions for friction and waste. A free, always-on dashboard tallies timeouts, hook blocks, tool errors and redundant cd prefixes, plus spend concentration; a paid, opt-in deep run spawns one silent session that writes a ranked, lever-tagged report.

On this page

What it is

A read-only developer-tools panel inside Omniscio that mines your past agent sessions for friction and waste, so you can tune the things that make your fleet slower or costlier. It has two layers:

  1. A free, always-on deterministic friction dashboard. The friction signatures — command timeouts, hook blocks, tool errors, redundant cd "<worktree>" && prefixes (and bash-command volume as the denominator) — are tallied per session as its output streams in (at NDJSON ingestion, while the raw tool results are still in hand; the result text is inspected for the signatures then discarded, so nothing bulky is stored). On a bounded schedule the dashboard just SUMs those per-session counters over the recent-long window, plus spend concentration (total window spend, how much of it lands in the priciest 10% of sessions, and the top-cost tail). No AI, no spend, and no transcript files — so it covers every session, not just the ones whose transcripts still happen to be on disk.
  2. An opt-in deep agent-run analysis. On demand it spawns a single silent Claude session that runs a forensic methodology over your recent sessions and writes a ranked, lever-tagged report (each finding maps to a lever: HOOK / SKILL / CLAUDE.md / MEMORY / CONTRACT / TOOL / CONFIG / WORKFLOW / CONTEXT / OTHER). This is paid work — it is cost-capped, runs one at a time, and over the CLI it is approval-gated.

It lives in the Developer Tools sidebar group, and it is a non-spawnable virtual project — you don't start Claude sessions "inside" it; the deep-run session spawns under a real project. The panel is visible, and the free periodic scan runs by default.

Where to find it

Turning it on

Two gates, and they are not the same one.

The panel is visible by default. The registry entry is status: 'in-development' with defaultOn: true, so on a normal install the visibility gate shows the surface and the Lab toggle that flips its setting is rendered — Settings → Lab → Weekly Session Analysis. Because the entry is in-development (not shipped), that setting is also the visibility gate: turning it off hides the panel and its sidebar row, not just the scan.

The scan is the gate that decides everything else. sessionForensicsEnabled must be exactly true, and it defaults to true (the registry entry is defaultOn: true). Two paths honour it: the deep-run IPC handler (src/main/ipc/session-forensics-handlers.ts) and the periodic scanner (scanNow() in src/main/services/session-forensics/session-forensics-service.ts, which also stands down while the service is paused). The "Scan now" path is deliberately exempt — the manual trigger POST /session-forensics/scan calls scanOnce() → runScan() directly, bypassing both checks, so a scan the user explicitly asked for always runs. (The same is true of the other CLI run routes.) The gate is aimed at the automatic work, not at a person pressing the button.

You switch it off from the interface: Settings → Lab → Weekly Session Analysis writes sessionForensicsEnabled. The toggle is load-bearing — the periodic scanner and the deep-run handler both read it, and it is also the surface's visibility gate — so turning it off hides the panel and its sidebar row, stops the automatic scan, and disables the deep run (while Scan now keeps working, since that path is exempt by design). A one-shot migration (migrate-session-forensics-enabled-default-for-existing-users.ts) flips existing installs onto the ON default so an upgraded install behaves like a fresh one — unless you had deliberately turned it off, which the migration's sentinel leaves alone.

The registry entry's AMC_SHOW_SESSION_FORENSICS escape hatch is the standard in-development reveal, and has no bearing here: the feature is defaultOn: true, so its Lab toggle is already rendered and there is nothing to reveal — and no reason to hand-edit config.json.

The companion settings ride the same flag: the scan interval (sessionForensicsScanIntervalHours, 1–168h, default 6), the deep-run daily spend cap (sessionForensicsDailyCostCapUsd, $0.05–$20, default $2), and the weekly auto-run toggle (sessionForensicsAutoWeeklyEnabled, default off).

How it behaves

The dashboard

When the panel has at least one scan, the layout reads top-to-bottom as a triage view:

  • A health headline (the focal point) — names your single worst friction signal in that signal's severity colour, or shows a calm "Running clean" verdict when every signal is healthy. The worst is ranked by severity tier (bad > notable > healthy), tie-broken by a fixed priority — never by raw percentage, because the signals use different denominators.
  • Friction signals — four severity-coloured cards: Timeout sessions, Hook-block sessions, Tool-error sessions, and Redundant cd (redundant cd prefixes as a share of all bash calls). Each shows its percentage, a thin severity bar, and the raw count. Severity reads three ways at once — colour, bar length, and the number — so it never rides on colour alone: a calm surface tone when healthy, amber (status-needs-you) when notable, red (status-error) when bad. Thresholds: the session-percent signals are healthy < 10 / notable 10–33 / bad ≥ 33; redundant-cd (a lower-stakes, differently-scaled signal) is healthy < 5 / notable 5–20 / bad ≥ 20.
  • Agent workflow insights — three informational cards projected from the same deterministic cross-session dialogue aggregates the paid deep run uses, surfaced back to you for free (reused, never recomputed, no schema change): Correction load (the share of the replies you typed that contain a correction word such as "stop" or "still" — a word match, not a judgement — with a few PII-scrubbed sample quotes; app nudges, agent relays and other sessions' messages are never counted), Repeated launch templates (recurring session kick-offs with no matching skill — automation candidates, shown as an "automate these" list), and Reactive vs proactive (the firefighting-vs-building work mix, as a two-segment bar). Neutral-toned (these aren't "wrong", so no severity colour); each card shows a calm empty state until a scan has data.
  • Spend & cost — a separate, informational section (money isn't "wrong", so it is never severity-coloured): the Spend (window) total, the Top-10% spend share concentration, and the Priciest sessions list (rank · name · source · hours · turns · cost, each with a relative-cost bar).

A Scan now button runs an immediate deterministic pass (re-SUMs the DB counters). Everything reflects only the recent window (the friction counters are aggregated only over sessions that ran in the window), so it is labelled by window, never implied as all-time. Before the first scan the empty state previews the metrics a scan will surface (a labelled skeleton grid — no invented numbers) so the panel shows its value instead of a bare button.

The deep analysis

Run deep analysis starts a paid forensic run. The agent reads what you actually typed this week, in parallel, and compares it with the last run. It:

  • pre-flight checks the daily cost cap (SUM(cost_micro_usd) of today's runs vs the cap) and refuses if one is already running;
  • refuses, spending nothing, when your replies cannot be read: if the database turns the read away (busy or restarting), the run is not started, no run row is counted against the week and no empty digest is sent. The panel says session history is unavailable right now, and a later try (or the weekly auto-run) goes through once the read answers; the free insight cards keep their last values meanwhile;
  • reads your own replies from the last 7 days — only sessions you typed into, only rows the shared "written by you" filter keeps (no app nudges, peer or cron messages, board notices or CLI sends), never a session's opening prompt — and writes them, oldest first, into at most 6 message files of ~60 KB under <userData>/session-forensics/<runId>/input/ (the newest messages are kept when a week is bigger);
  • hands over the previous successful run's findings (input/previous-findings.json) so the report can say what is new, still happening or improving;
  • adds a small deterministic background digest (correction-word rate, repeated launch templates without a skill, reactive:proactive mix, model mix, spend tail), which says plainly when some sessions could not be fully read so its counts are a floor;
  • spawns a silent session with source: 'session-forensics' under a real project (the last active project, else the first one) on the model the smart tier resolves to (Opus 5.5 today; it follows new releases and your tier pins in Settings — no model name is written in the code), with a bundled prompt that has it launch one reader subagent per message file in parallel, merge their themes, re-count the top themes across all files, and write plain-language findings;
  • the agent writes findings.json + report.md to <userData>/session-forensics/<runId>/;
  • a watcher (mtime-gated + a max-runtime watchdog) parses the findings into a session_forensics_runs row, records the spawned session's cost, and deletes the copied messages however the run ends (any copies a crash left behind are swept before the next run).

Each finding is richer than a bare lever tag — patternClass (taxonomy id), frequency (the cross-session count = the value multiplier), quote (verbatim evidence), concreteChange (the actual rule/skill/setting to make), impact (quantified payoff), and polarity (problem vs reinforce — a working pattern worth codifying). All the new fields are OPTIONAL + defensively parsed/clamped, so older run rows still render.

Runs are triageable in the panel — expand to read the ranked findings + report, mark read, or dismiss (reversible). Orphaned running rows left by a crash are reconciled to failed on startup.

Weekly auto-run (opt-in). With Run the deep analysis automatically every week on (sessionForensicsAutoWeeklyEnabled, default off), the deep analysis also fires on its own once a week (Monday morning, local time): at most one run per week, never overlapping an in-flight run, and within the same daily spend cap. It is doubly gated (both sessionForensicsEnabled and the weekly toggle must be on). The scheduler is an hourly check in session-forensics-service.ts calling the pure isWeeklyDeepRunDue in session-forensics-weekly.ts.

Forensics reads a session’s past; these are the raw records it reads.

Last verified 2026-10-01