Skip to content
DocsGetting started

Start

Getting started

Run AI Insights with one command, read what it prints, and find the report and the files it keeps.

On this page

Requirements

  • Node.js 20 or newer. Check with node --version. A few sources need more: OpenCode's database needs Node 22.5 or later, and compressed Codex rollouts need Node 22.15 or later or a zstd program on your PATH. See Node version problems.
  • Some agent history. At least one of Claude Code, Codex, Cursor, Pi, OpenCode or Gemini CLI used on this machine. See What it reads.
  • No account, no API key and no network access beyond what npx needs to download the package.

Your first run

Terminal
npx ai-insights@latest

AI Insights draws the Matrix OS rabbit at once, then shows what it is doing on one line (finding your history, reading sessions, analysing, writing the report) and ends with a check mark and the time it took. Then it shows what it found and asks whether to open the report. On a synthetic history of 58 Claude Code and Codex sessions, an 80-column terminal ends like this (in colour, with the report path and the website as links you can click):

Output, from a synthetic history; home folder shortened to ~
         ▀▄▄
      ▄▄▖ ▀▜▄
       ▀▛█▄ ▀▙
         ▝▀▀▌▝▄▄
             ▐██▙     ▄▀█ █   █ █▄ █ █▀ █ █▀▀ █ █ ▀█▀ █▀
         ▝▀▀▀▀▝       █▀█ █   █ █ ▀█ ▄█ █ █▄█ █▀█  █  ▄█
      ▀▀▀▀▀ ▀▝▀▘      by Matrix OS · v0.7.1
    ▝▀▀▀▀▘▀ ▀▀▀▘
    ▀▀▀▀▀▘▀▘ ▀▀
  ▀▀ ▀▘▝▀▀▘▝▘ ▀

  ✓ 58 sessions (Claude Code 46 · Codex 12) read and analysed in 0.1s

  ╭─ 2026-10-23 → 2026-11-16 ────────────────────────────────────────────────╮
  │ 58             23             28             151.1M         $69.71+      │
  │ sessions       active days    active hours   tokens         est. cost    │
  │                                                                          │
  │ Claude Code, Codex · 31 agent-hours in parallel · 22% of requests        │
  │ unpriced                                                                 │
  ╰──────────────────────────────────────────────────────────────────────────╯

  ◆ The Night Delegator
    also The Clear Briefer · The Context Keeper · The Stress Tester
  ▲ Top finding  `pnpm e2e` keeps failing
  ▸ Report  ~/.ai-insights/reports/report.html

  What to do next ────────────────────────────────────────────────────────────
  1  Open       press Enter below to open it in your browser, or click the
                report path above.
  2  Cards      the report opens on your cards; Download video or images saves
                them.
  3  Publish    Publish to the leaderboard next to your cards, then again in
                the box; sign in on ai-insights.app and press Publish.
  4  Share      post your cards or ai-insights.app/u/<handle> with
                #MyAIInsights.
  5  Go deeper  run the analyze-ai-usage skill in your agent.

  ! 5 Claude Code sessions can be deleted within 7 days (from 2026-11-22).
    Keep them: add "cleanupPeriodDays": 365 to ~/.claude/settings.json or run
    npx packmem archive.

  Keep your history with Matrix OS  →  matrix-os.com

  Open the report in your browser? [Y/n] no

From the top:

  • The numbers: the dates covered, sessions, active days, active hours (clock time with at least one agent working), tokens and the estimated cost at API list prices. Under them: which agents, the agent-hours (the same time summed over sessions running in parallel, so it can be larger) and how much usage could not be priced.
  • Your persona and the extra titles you earned, when the report has a recap.
  • Top finding: the most severe finding, or a note that more history makes for better tips.
  • Report: the full path to the HTML file. Most terminals let you click it (with Cmd or Ctrl held in some).
  • What to do next: open the report, which starts on your cards; export them with Download video or images, publish to the leaderboard (Publish to the leaderboard next to your cards, then the same button in the box it takes you to, then sign in on ai-insights.app and press Publish; see Publish to the leaderboard), share with #MyAIInsights, and run the agent review. The last step goes away once you have run the review.
  • History warning (only when it applies): how many sessions your agents can delete within the next 7 days, and the setting that keeps them.
  • Keep your history with Matrix OS: a link to matrix-os.com, the same one the report ends with. AI Insights itself uploads nothing.
  • The question: press Enter (or y) to open the report in your browser, n to leave it. Add --open to open it without asking, --no-open to never be asked, or set AI_INSIGHTS_OPEN=1 or 0 to make that your default. It is never asked when the output is piped, in CI or over SSH without a display.

The screen fits narrower windows down to 40 columns, uses plain ASCII where the terminal cannot draw boxes, and drops colour and links when NO_COLOR is set. When the output is piped or redirected (a script, CI), it prints stable plain text with no escape codes instead:

Piped output, same history
58 sessions across Claude Code and Codex, 2026-10-23 to 2026-11-16.
28 active hours (31 agent-hours across parallel sessions) on 23 days; 151.1M tokens, about $69.71 for the requests we can price; 22% unpriced.
Top finding: `pnpm e2e` keeps failing
Persona: The Night Delegator (also The Clear Briefer, The Context Keeper and The Stress Tester)

Report: ~/.ai-insights/reports/report.html
5 Claude Code sessions can be deleted within 7 days (from 2026-11-22). AI Insights keeps their stats; to keep the transcripts, add "cleanupPeriodDays": 365 to ~/.claude/settings.json or archive them with `npx packmem archive`.

Next steps
  1. Open the report: open the file above in your browser, or run again with --open.
  2. Your cards: the report opens on them; "Download video or images" saves them.
  3. Publish to the leaderboard: press "Publish to the leaderboard" next to your cards, then again in the box; sign in on https://ai-insights.app/ and press "Publish".
  4. Share it: use the X or LinkedIn buttons in the report, or post your cards or https://ai-insights.app/u/<handle> with #MyAIInsights.
  5. Go deeper: run the analyze-ai-usage skill in your agent to add what went well and what got in the way.

Open the report in any browser. It is one file with everything inside it, so you can also move it or keep a copy. If nothing is found, the command prints No agent sessions found. with what to try and exits with code 1; run npx ai-insights@latest doctor to see where it looked.

Where files go

AI Insights writes only to its own folder, ~/.ai-insights/. Set AI_INSIGHTS_HOME to put it somewhere else. Folders are created readable by you only (mode 700) and files likewise (mode 600).

Files AI Insights writes
PathWhat it holds
reports/report.htmlThe latest report. Open this one.
reports/report-<time>.htmlA timestamped copy of each report. The newest 20 are kept.
reports/report.jsonThe latest report as JSON.
sessions/<agent>/The parsed sessions, cached so the next run only re-reads transcripts that changed.
facets/<agent>/Session labels your agent saved during the agent review.
snapshots/A small summary of each run, used for “Since your last run”.
device.jsonA random id for this installation, made once. Share links carry it so the website keeps one entry per computer. Never made from your computer's name or hardware.

Deleting the folder is safe: the next run rebuilds the cache from whatever transcripts your agents still keep. You lose the stats of sessions whose transcripts are gone, the saved labels and the run history. A new device id is made too, so the next publish from this computer shows up on your profile as a new computer; remove the old one there.

Run it again

Later runs are faster because unchanged transcripts come from the cache. Each run saves a snapshot, so the report gains a Since your last run section. To use the newest release rather than a copy npx cached earlier, ask for it by tag:

Terminal
npx ai-insights@latest

To look at part of your history, pass --since 30d (or 12w, 6m, 1y, or a date like 2026-01-31) or --harness codex. Every option is in the CLI reference.

From your agent instead

If you use Claude Code or Codex, you can install the plugin and ask your agent to build the report. That route adds the agent review: your own agent labels a sample of sessions and writes a short narrative.

Claude Code
/plugin marketplace add hamedmp/ai-insights
/plugin install ai-insights@ai-insights

Then start a new session and run /analyze-ai-usage. Other agents and details are in Install the plugin.

Or let the command line do it: after the report, npx ai-insights@latest offers to install the plugin into Claude Code and Codex, and npx ai-insights@latest install does the same at any time.

The monthly reminder

With the plugin installed, a new Claude Code or Codex session can show one line when a review is due:

Shown at session start
AI Insights: your monthly review is due. Run /analyze-ai-usage, or npx ai-insights@latest in a terminal. (Turn this off: npx ai-insights@latest nudge --off)
  • It is due when no report has been written this calendar month. It shows at most once a month, on the first new session that finds it due.
  • It is shown to you, not added to your agent's context, and it runs offline: a small script inside the plugin reads two files in your AI Insights folder (reports/report.html for its date, and nudge.json, where it records the month it last showed).
  • Codex runs plugin hooks only after you review and trust them (in /hooks), so there it starts once you have approved it, and again after an update changes it. Codex documents plugin hooks for its desktop app; in the Codex CLI it is untested. Resumed, cleared and compacted sessions never show it.
  • npx ai-insights@latest nudge --off turns it off; --on turns it back on. Uninstalling the plugin removes it.

Why monthly: Claude Code and Gemini CLI delete transcripts after 30 days by default. Each run saves the stats and your prompts from every transcript it reads (see What is kept), so a review a month keeps that history after the transcripts are gone. It does not keep the agent's replies or anything needed to resume a session.

Formerly Hindsight

AI Insights was called Hindsight until version 0.2. If you used it then, nothing needs to change:

  • The package installs a second command, hindsight, which runs the same program as ai-insights.
  • If ~/.ai-insights/ does not exist and ~/.hindsight/ does, AI Insights keeps using ~/.hindsight/, so earlier results carry over. Nothing is moved or deleted.
  • HINDSIGHT_HOME still works when AI_INSIGHTS_HOME is not set.
  • The old npm package @matrix-os/hindsight is deprecated in favour of ai-insights.

Something wrong or missing? Edit this page on GitHub or open an issue.