MirAI

A local mirror of your AI-assisted coding practice. MirAI reads your coding-assistant session traces and, on demand, reports a verification-hygiene index and a conservative lower bound on over-reliance — without ever exposing the content of your transcripts.

100% local · zero network · zero dependencies. MirAI runs on Node alone. Nothing is uploaded, nothing is installed, and the report is built from a whitelist of counters — so no fragment of a transcript can leak, even by accident.

The name is a play on words: MirAI = mirror + AI (the "AI" of Human-Centered AI), and mirai means "future" in Japanese.

MirAI is a research instrument, not a productivity score and not a valid measurement of over-reliance (that comes from a controlled study). Its real engineering contribution is the privacy contract, not the counting.

What it does

• Reads a coding-assistant session (a local .jsonl transcript) in a streaming, structural way — it counts events, it does not read the meaning of your messages.
• Reports a verification-hygiene index in qualitative bands (not a number to game).
• Reports a conservative lower bound on over-reliance: it only counts detected slips, never the ones that went unnoticed, so the figure is explicitly a floor.
• Suggests task-oriented tips (never person-oriented, never a metric sent to management).

Quick start

Prerequisite: Node ≥ 22 (an .nvmrc is provided).

# Try it on the bundled demo session — no setup, touches no real trace:
npx @anthony-mini/mirai demo

# Analyze the current session:
npx @anthony-mini/mirai run --scope current

# Analyze a specific transcript, as JSON:
npx @anthony-mini/mirai run --session ./session.jsonl --json

The report (Markdown + JSON) is written to _mirror_output/.

Run from source (contributors)

git clone https://github.com/anthony-mini/mirai.git
cd mirai
node bin/cli.js demo
npm test          # node --test

Commands

| Command | What it does | | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | demo | Runs the bundled synthetic session and then a live privacy proof (planted secrets never appear in the report). Fully reproducible — ideal for a demo. | | run [workflow] | Runs a workflow (default hygiene) and writes the report to _mirror_output/. | | sessions | Lists your recent local sessions with their signals (acceptances/reads/churn/band) — see which have activity, and get a ready command to analyze one. --project filters to the current project, --limit N caps the list. | | aggregate | Analyzes all your local sessions into one fleet report (totals, active vs query-only, hygiene bands, over-reliance-floor concentration, tool-usage signature, per-project rollup, weekly timeline). Counters only; cached in ~/.mirai for instant re-runs. | | insights | Reads the assistant's own self-assessment of your sessions (what Claude Code's /insights wrote) and puts it beside MirAI's structural counters. Two proxies, side by side; MirAI never runs /insights for you. --open prints where Claude's HTML report is. | | learn | Turns this session into a learning companion: next-session tips to use your Claude Code tools more deliberately, plus optional 60-second refresher cards for concepts (e.g. a Singleton) found in the code you accepted. An offer to improve, not a grade. | | list | Lists the pre-configured workflows. | | status | Shows install status. | | install | Installs the /mirai command into a coding assistant (--scope user or --scope project). |

In Claude Code, mirai install lays down five slash commands: /mirai (this session's report), /mirai-fleet (a report across all your sessions), /mirai-sessions (list your recent sessions), /mirai-learn (the learning companion for this session), and /mirai-insights (what the assistant says about itself, beside what your traces show).

Pre-configured workflows (declarative JSON in src/skills/mirai/workflows/):

• hygiene (default): the main report — hygiene band, tips, over-reliance lower bound.
• resume: a factual structural summary of the session (counts by type/tool), with no signal and no interpretation.
• learn: the learning companion — next-session guidance + concept refresher cards.
• insights: the assistant's own self-assessment, cross-read against the traces.

Insights × mirror (mirai insights / /mirai-insights)

Since 2026, the assistant does more than count: Claude Code's /insights asks Claude to grade its own sessions ("very helpful", "goal mostly achieved") and writes the result next to your transcripts. That grade is a self-report, and a self-report is exactly what this instrument refuses to take at face value — a system can be trusted without being trustworthy (Shneiderman, 2022), and the aim is to calibrate trust on real reliability, not to maximize it (Lee & See, 2004).

So mirai insights reads that assessment, keeps only its closed vocabularies and counters (never its free text), joins it to MirAI's own signals session by session, and reports where the two readings part: sessions Claude graded well while the traces show a deficit. Two kinds, never merged into one sentence — no verification act at all and fewer reads than acceptances, and a large diff applied without reading that file first (which can happen inside a session that checked plenty elsewhere).

Three refusals make it usable rather than reassuring:

• It cannot congratulate you. The count is one-directional: a harsh self-grade is never credited back. Zero gap is reported as an absence in the traces, never as a clean bill of health.
• It disqualifies bad joins. A session whose transcript grew materially after it was graded, or whose two readings differ by more than a factor (the assistant re-reads what survives a context compaction; MirAI streams the whole file), is set aside and said so — comparing two states of one session would be a bug, not a finding.
• It never runs /insights for you. Producing that assessment means asking a model to re-read your transcripts. That stays your decision; MirAI reads files that already exist, and stays offline.

npx @anthony-mini/mirai insights          # or /mirai-insights in Claude Code

Learning companion (mirai learn / /mirai-learn)

The mirror measures; the companion helps you act. The durable antidote to over-reliance is competence — a developer who understands the concept behind the AI's code can verify it instead of deferring to it. So mirai learn turns one session into two optional, self-directed outputs:

• Next-session guidance — from the session's signals, concrete Claude Code habits for next time (ask for a diff walkthrough, run the tests and ask "what could break?", try plan mode, refresh CLAUDE.md), plus the one habit worth repeating: give Claude a way to verify its work.
• Learning roadmap — short, generic refresher cards (what it is · when not to use · pitfalls · a self-check) for concepts detected in the code you accepted, so you understand what you accepted.

Privacy by construction. Concept detection is local and emits only a fixed vocabulary of concept labels; the cards are bundled, generic text. No code, diff, or transcript content ever leaves your machine — the same whitelist guarantee as the rest of MirAI.

Sample output

A single session (mirai demo, on a synthetic session):

# MirAI — session report

8 acceptance(s) analyzed, verification hygiene low.

**Verification hygiene: low**

Signals: 8 acceptance(s) · 1 read(s) · 6 blind diff(s) · 3 re-edit(s)

## Tips
- 6 large diff(s) accepted without reading the file first: reading before accepting, or running the
  tests right after, helps catch side effects.

## For information: over-reliance lower bound
At least 1 acceptance(s) out of 8 were followed by a re-prompt signal (floor).

mirai aggregate (or /mirai-fleet) reports across all your local sessions — the telling part is where the over-reliance floor concentrates (e.g. "~73% of the floor is on one project"), plus a per-project rollup, the hygiene band distribution, and your tool-usage signature.

Privacy & guarantees

Privacy is the point, so it is enforced by construction rather than by promise:

• Redaction before reading. Secrets, credentials and denylisted terms are masked before any line is parsed (src/skills/mirai/config/denylist.txt, overridable).
• Whitelist output contract. The report is assembled from an explicit whitelist of fields — all counters or a hashed session id — so no transcript fragment can transit, even accidentally.
• Zero network. MirAI never opens a socket. There is no update check, no telemetry, nothing. A test (test/no-network.test.js) guards this on every change.
• Conservative by design. The lower bound under-counts on purpose: an error accepted and never noticed leaves no trace, so it cannot be counted. The report always says so.
• Adversarial test. Secrets planted on purpose in every plausible field of a session (free text, file paths, command output…) are checked, on every change, to never surface in the report.

How it works

redact (mask before reading) → reader (structural streaming read) → signals (acceptance, corrective re-prompt, blind diff, churn) → report (aggregate into a hygiene band + conservative lower bound) → contract (whitelist the output) → written to _mirror_output/. The analysis core is node: only — no third-party code — so it stays auditable on the privacy side.

Contributing

Contributions are welcome. See CONTRIBUTING.md. In short: Node ≥ 22, run node --test, and keep the non-negotiable invariants (zero dependency, zero network, whitelist output, conservative bound, task-oriented and non-judgmental restitution).

License

MIT © 2026 anthony-mini