Reference
CLI reference
Every ai-insights command, option, environment variable and exit code.
On this page
The package installs two commands, ai-insights and hindsight, which run the same program. With npx you do not need to install anything: npx ai-insights@latest <command>.
ai-insights [options] scan, write the report, print a summary
ai-insights scan [options] scan and show what was found
ai-insights report [options] write the report (or print JSON with --json)
ai-insights doctor show which histories were found and where
ai-insights mcp start the MCP server on stdio (for your agent)
ai-insights import claude <path> add a Claude chat export
ai-insights install add the plugin to your agents
ai-insights uninstall remove it again
ai-insights nudge print a line when a monthly review is dueCommands
ai-insights
With no command, AI Insights scans, writes the report and shows the numbers, your persona, the top finding, the report path as a link, numbered next steps and a history warning when one applies. Piped or redirected, it prints the same as plain text with no escape codes, so scripts can read it. See Your first run for both.
On a terminal it draws its mark first, then one status line on stderr while it works (finding history, reading sessions, analysing, writing the report), ending with a check mark and the time taken. Piped, in CI or on a dumb terminal there is no status line.
At the end it asks Open the report in your browser? [Y/n]: Enter or y opens it, n does not, and Ctrl-C exits. It asks only when you are at a terminal: never when stdin or stdout is piped, in CI (CI set), or over SSH without a forwarded display, and never for scan, report, doctor or mcp. So an agent or a script running it never waits on the question. --open, --no-open and AI_INSIGHTS_OPEN skip it.
After that, when Claude Code or Codex is on your machine without the AI Insights plugin, it asks once whether to add it. See ai-insights install for what that runs. The same rules decide whether it asks, and a no is remembered for 30 days, or until a newer minor version runs. --no-install-prompt and AI_INSIGHTS_NO_INSTALL_PROMPT=1 turn it off.
Add AI Insights to Claude Code and Codex? It installs the ai-insights plugin:
the MCP server, three skills (analyze-ai-usage, ai-insights-coach,
ai-insights-setup) and a once-a-month reminder when a review is due.
Codex runs the reminder only after you approve it in /hooks.
Each review saves your sessions' stats and prompts in ~/.ai-insights,
so they outlast agents that delete old transcripts.
Install it now? [Y/n]ai-insights scan
Scans and prints what was found, without writing a report. Output from a synthetic history:
History found
Claude Code 12 sessions 2026-11-05 to 2026-11-16 58.4 KB
Codex not found
Cursor not found
Pi not found
OpenCode not found
Gemini CLI not found
12 sessions, 36 prompts, 2.2 agent-hours, 1.6M tokens.
2.2 active hours (2.2 agent-hours across parallel sessions); about $1.13 at API list prices.
Parsed 0, reused 12 from cache.A found agent with unreadable lines or skipped usage records says how many after its size. The last line shows how many transcripts were parsed, how many came from the cache, and how many could not be read.
ai-insights report
Writes the report and prints only its path. With --json it writes nothing and prints the whole report as JSON instead: version, time zone, range, coverage, activity, usage, findings, facets, narrative, recap, retention, the causes of friction and the ratios.
npx ai-insights@latest report --json > report.jsonai-insights doctor
Shows the version and Node version, then for each agent: how many transcripts it found and their dates, how long the agent keeps them, and every location it checked, marked found or missing. It ends with the store: its path, whether it is writable, how many sessions are cached and labels saved, whether a narrative is saved, and when the last report was written. Abridged output from a synthetic history:
ai-insights 0.4.0 on Node 24.22.0
Claude Code: 12 transcripts (58.4 KB), 2026-11-05 to 2026-11-16
keeps transcripts 30 days (the default; cleanupPeriodDays in ~/.claude/settings.json)
found ~/.claude/projects
missing ~/.config/claude/projects
missing ~/.config/Claude/local-agent-mode-sessions
missing ~/.config/Claude/claude-code-sessions
Codex: no history found
missing ~/.codex/sessions
missing ~/.codex/archived_sessions
…
Store: ~/.ai-insights
writable
0 cached sessions, 0 saved facets, narrative not saved yet
last report: none yetai-insights mcp
Starts the MCP server on standard input and output. Your agent starts this for you once the plugin or server is installed; you do not run it by hand. See the MCP reference.
ai-insights import
Adds the history of a chat product from its data export. Chat exports are never looked for on their own: you point AI Insights at the file. See Import chat history for what is read and what cannot be measured.
ai-insights import claude <path> the export .zip, its unzipped folder, or conversations.json
ai-insights import --list show what has been imported
ai-insights import --remove claude remove the import and everything made from itA newer import replaces the earlier one. Imported conversations then appear in every run as their own agent, claude-chat (Claude chat).
ai-insights install
Adds the AI Insights plugin to the agents it finds, through each agent's own plugin commands. It prints the exact commands first and runs them only after you say yes (or with --yes). It edits no agent config file itself, and running it again changes nothing once the plugin is there. A step that fails or takes longer than two minutes is reported with the command to run yourself.
ai-insights install [--harness <name>]... [--yes] [--dry-run]
ai-insights uninstall [--harness <name>]... [--yes] [--dry-run]| Agent | Commands | Uninstall |
|---|---|---|
| Claude Code | claude plugin marketplace add hamedmp/ai-insights, then claude plugin install ai-insights@ai-insights --scope user | claude plugin uninstall ai-insights@ai-insights, claude plugin marketplace remove ai-insights |
| Codex | codex plugin marketplace add hamedmp/ai-insights, then codex plugin add ai-insights@ai-insights | codex plugin remove ai-insights@ai-insights, codex plugin marketplace remove ai-insights |
| Cursor, OpenCode, Pi | Nothing: it prints the install steps (untested installs) | Prints the removal steps |
--harness takes claude-code, codex, cursor, opencode or pi and can repeat. --dry-run prints the plan and changes nothing. Without --yes it only asks at a terminal; piped, it prints the plan and exits 1. Claude Code and Codex download the plugin from GitHub when they install it; see Privacy. Uninstalling leaves your report and cache in place.
ai-insights nudge
Prints one line when a monthly review is due, and nothing otherwise. The plugin runs the same code when a new Claude Code or Codex session starts; see The monthly reminder. It always exits 0.
ai-insights nudge the line, if a review is due
ai-insights nudge --off never remind me
ai-insights nudge --on remind me againhelp is accepted as a command and prints the same text as --help.
Options
Options work with the default command, scan and report. Values can follow a space or an equals sign: --since 30d or --since=30d.
| Option | What it does |
|---|---|
--since <window> | Only history from a window like 30d, 12w, 6m or 1y (a month counts as 30 days, a year as 365), or from an ISO date like 2026-01-31. |
--harness <name> | Only one agent: claude-code, codex, cursor, pi, opencode, gemini or claude-chat (an imported Claude chat export). |
--max-sessions <n> | Read at most n transcripts, newest first. The default is 5,000; the most is 50,000. |
--refresh | Re-parse every transcript, ignoring the cache. |
--json | With report only: print the report as JSON instead of writing HTML. |
--open | Open the written report in your default browser without asking. |
--no-open | Do not ask whether to open the report, and do not open it. |
--no-install-prompt | Do not offer to add AI Insights to your agents after the run. |
-h, --help | Show the help. |
-v, --version | Show the version. |
npx ai-insights@latest --since 90d --open
npx ai-insights@latest scan --harness codex
npx ai-insights@latest --refreshEnvironment variables
| Variable | Effect |
|---|---|
AI_INSIGHTS_HOME | Where AI Insights keeps its cache, labels, snapshots and reports. Default ~/.ai-insights. |
HINDSIGHT_HOME | The pre-0.2 name, used when AI_INSIGHTS_HOME is not set. |
AI_INSIGHTS_DEBUG | When set, a failed command also prints the error's stack trace. |
AI_INSIGHTS_OPEN | 1 opens the report without asking, 0 never asks. --open and --no-open win over it. |
AI_INSIGHTS_NO_INSTALL_PROMPT | 1 never offers to add AI Insights to your agents, like --no-install-prompt. |
NO_COLOR | When set to anything, the result screen has no colour and no links. |
FORCE_COLOR | Colour even when the output is piped, for recordings: 1, 2 (256 colours) or 3 (truecolor); 0 turns colour off. It wins over NO_COLOR. |
FORCE_HYPERLINK | 0 turns off clickable links in terminals that show them as stray characters; 1 turns them on. |
| Agent variables | CLAUDE_CONFIG_DIR, CODEX_HOME, OPENCODE_DB, PI_CODING_AGENT_DIR, CURSOR_CONFIG_DIR, GEMINI_CLI_HOME and others move where history is read from. See Where each agent's history lives. |
Exit codes
| Code | Meaning |
|---|---|
| 0 | Success. |
| 1 | No sessions were found (the default command only), or the command failed. The message starts with ai-insights:. install and uninstall also exit 1 when a step failed, a named agent is not installed, or they would have needed --yes. |
| 2 | A usage error: an unknown command or option, a missing or invalid value, or --json without report. |
$ npx ai-insights@latest --since 5x
ai-insights: --since must be a window like 30d, 12w, 6m or 1y, or an ISO date like 2026-01-31
Run `ai-insights --help` for usage.The install script
scripts/install.sh in the repository sets up the skills and MCP server for agents without a plugin install, or several at once. Run it from a clone.
scripts/install.sh [--all | --harness <name>]... [--dry-run]| Option | What it does |
|---|---|
--all | Every supported agent found on this machine. The default. |
--harness <name> | Only this agent; repeatable. One of claude-code, codex, cursor, opencode, pi. |
--dry-run | Print what would happen and change nothing. |
-h, --help | Show the help. |
Where it puts things:
| Agent | Skills | MCP server |
|---|---|---|
| Claude Code | ~/.claude/skills | claude mcp add --scope user |
| Codex | ~/.agents/skills | codex mcp add |
| Cursor | ~/.cursor/skills | ~/.cursor/mcp.json |
| OpenCode | ~/.agents/skills | opencode mcp add |
| Pi | ~/.pi/agent/skills | None: use pi install for the tools |
It replaces only the folders of the three skills it ships, skips an MCP server that is already registered, and leaves a Cursor mcp.json that is not valid JSON untouched. For Claude Code it notes that the plugin does the same thing: use one or the other.