Skip to content
DocsCLI reference

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>.

Usage
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 due

Commands

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.

Output, after the report
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:

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.

Terminal
npx ai-insights@latest report --json > report.json

ai-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:

Output, from a synthetic history; home folder shortened to ~; abridged
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 yet

ai-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.

Usage
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 it

A 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.

Usage
ai-insights install [--harness <name>]... [--yes] [--dry-run]
ai-insights uninstall [--harness <name>]... [--yes] [--dry-run]
What install runs
AgentCommandsUninstall
Claude Codeclaude plugin marketplace add hamedmp/ai-insights, then claude plugin install ai-insights@ai-insights --scope userclaude plugin uninstall ai-insights@ai-insights, claude plugin marketplace remove ai-insights
Codexcodex plugin marketplace add hamedmp/ai-insights, then codex plugin add ai-insights@ai-insightscodex plugin remove ai-insights@ai-insights, codex plugin marketplace remove ai-insights
Cursor, OpenCode, PiNothing: 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.

Usage
ai-insights nudge          the line, if a review is due
ai-insights nudge --off    never remind me
ai-insights nudge --on     remind me again

help 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.

Options
OptionWhat 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.
--refreshRe-parse every transcript, ignoring the cache.
--jsonWith report only: print the report as JSON instead of writing HTML.
--openOpen the written report in your default browser without asking.
--no-openDo not ask whether to open the report, and do not open it.
--no-install-promptDo not offer to add AI Insights to your agents after the run.
-h, --helpShow the help.
-v, --versionShow the version.
Examples
npx ai-insights@latest --since 90d --open
npx ai-insights@latest scan --harness codex
npx ai-insights@latest --refresh

Environment variables

Environment variables
VariableEffect
AI_INSIGHTS_HOMEWhere AI Insights keeps its cache, labels, snapshots and reports. Default ~/.ai-insights.
HINDSIGHT_HOMEThe pre-0.2 name, used when AI_INSIGHTS_HOME is not set.
AI_INSIGHTS_DEBUGWhen set, a failed command also prints the error's stack trace.
AI_INSIGHTS_OPEN1 opens the report without asking, 0 never asks. --open and --no-open win over it.
AI_INSIGHTS_NO_INSTALL_PROMPT1 never offers to add AI Insights to your agents, like --no-install-prompt.
NO_COLORWhen set to anything, the result screen has no colour and no links.
FORCE_COLORColour 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_HYPERLINK0 turns off clickable links in terminals that show them as stray characters; 1 turns them on.
Agent variablesCLAUDE_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

Exit codes
CodeMeaning
0Success.
1No 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.
2A usage error: an unknown command or option, a missing or invalid value, or --json without report.
Output
$ 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.

Usage
scripts/install.sh [--all | --harness <name>]... [--dry-run]
Install script options
OptionWhat it does
--allEvery supported agent found on this machine. The default.
--harness <name>Only this agent; repeatable. One of claude-code, codex, cursor, opencode, pi.
--dry-runPrint what would happen and change nothing.
-h, --helpShow the help.

Where it puts things:

Install script targets
AgentSkillsMCP server
Claude Code~/.claude/skillsclaude mcp add --scope user
Codex~/.agents/skillscodex mcp add
Cursor~/.cursor/skills~/.cursor/mcp.json
OpenCode~/.agents/skillsopencode mcp add
Pi~/.pi/agent/skillsNone: 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.

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