0.2.0 • Published yesterdayCLI

@anthony-mini/mirai

Licence

MIT

Version

0.2.0

Deps

Size

176 kB

Vulns

Weekly

Summary Dependency Versions

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.
`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 four slash commands: /mirai (this session's report), /mirai-fleet (a report across all your sessions), /mirai-sessions (list your recent sessions), and /mirai-learn (the learning companion for this session).

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.

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.