Skip to content
DocsTroubleshooting and FAQ

Reference

Troubleshooting and FAQ

Fixes for missing history, Node versions, unpriced models and missing MCP tools, and answers to common questions.

On this page

Start with doctor. It shows the version, your Node version, every place AI Insights looked for each agent, and whether its own folder is writable.

Terminal
npx ai-insights@latest doctor

No agent sessions found

Output
No agent sessions found. Run `npx ai-insights@latest doctor` to see where AI Insights looked.
AI Insights reads Claude Code, Codex, Cursor, Pi, OpenCode and Gemini CLI history from their usual folders on this machine.
More help: https://ai-insights.app/docs/troubleshooting

With --since or --harness, a third line names them: the filter may be what left nothing.

  • History in another place. If you set CLAUDE_CONFIG_DIR, CODEX_HOME or a similar variable for your agent, set it the same way when you run AI Insights. doctor lists each location as found or missing. The variables are in Where each agent's history lives.
  • A narrow window. --since or --harness may leave nothing. Run without them.
  • No history kept. If the agent deleted its transcripts, there is nothing left to read, and AI Insights only has stats for sessions it read before.

Node version problems

  • Node older than 20: AI Insights needs Node.js 20 or newer. Check with node --version and upgrade.
  • OpenCode found but empty: OpenCode keeps its history in a SQLite database that needs Node 22.5 or later to read. doctor prints a note under OpenCode when this is the problem.
  • Codex compressed rollouts: .jsonl.zst files need Node 22.15 or later, or a zstd program on your PATH.

History only goes back a month

Claude Code deletes transcripts 30 days after they last changed, and Gemini CLI deletes chats after 30 days, unless you raise their settings. AI Insights cannot read what is gone. Raise the setting now so the next run can look further back; see How long agents keep history. AI Insights keeps the stats of sessions it has already read, so running it regularly keeps more of your history in the report.

Cost says some requests are unpriced

The cost estimate prices each request from a table of exact model ids. A new or renamed model, a provider tier without a published price, or a model routed through another provider is counted as unpriced instead of borrowing a price. The report and ai_insights_report show the unpriced share next to the estimate, so you can see how much of the total it covers. Upgrading with npx ai-insights@latest picks up newer pricing tables. Cursor sessions carry no token counts at all, so they are never priced.

The MCP tools do not appear

  1. Start a new session or restart the agent. Agents usually load new MCP servers and skills only at startup.
  2. Check the package starts: npx -y ai-insights --version.
  3. Check the server is registered, for example with claude mcp get ai-insights or codex mcp get ai-insights. Register it by hand if needed; see By hand.
  4. Ask your agent to run the ai-insights-setup skill. It checks each step and tells you the fix.

On Pi, a build without MCP support loads the skills but shows a warning that the ai_insights_* tools are unavailable.

The store is not writable

If doctor prints NOT writable: set AI_INSIGHTS_HOME to a folder you own, point AI Insights at a folder you can write to:

Terminal
AI_INSIGHTS_HOME="$HOME/ai-insights-data" npx ai-insights@latest

For a full error trace on any failing command, set AI_INSIGHTS_DEBUG=1 and include the output when you open an issue, after checking it for anything private.

FAQ

Does AI Insights send my history to a model?

No. It never calls a model API. Only if you run the agent review does your own agent read short, redacted excerpts, under the account and settings you already use.

Do I need the plugin?

No. npx ai-insights@latest gives you the cards, the video, the findings and the suggestions. The plugin adds the agent review and the coach that turns findings into edits you approve.

Why does every run give the same findings?

The deterministic layer has no randomness: the same history gives the same result. Findings change when your history does, and Since your last run shows which look resolved.

Why are agent-hours larger than the hours in a day?

Agent-hours add up the active time of every session, so two sessions running side by side for an hour count as two agent-hours. Active hours count the clock time when at least one agent was working.

Is the cost what I paid?

No. It is an estimate at API list prices. On a subscription your spend is different. Where an agent records its own cost, the report shows that separately.

Why does Cursor show no tokens?

Cursor's local transcripts hold prompts and tool calls but no token counts.

How do I remove everything?

Delete ~/.ai-insights/ (or the folder AI_INSIGHTS_HOME points to). If you published, use Remove my entry on the website; see Removing what you published.

Do I need Matrix OS?

No. AI Insights is free, MIT licensed and works without it. A Matrix OS account is used only to sign in on the website if you choose to publish.

Where do I report a bug?

In GitHub issues. Include the output of npx ai-insights@latest doctor, and never paste transcript content or prompts you would not want public.

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