Skip to content
DocsThe agent review

Using it

The agent review

How your own agent adds judgement to the report through the analyze-ai-usage skill and the MCP server, and what it sees.

On this page

Two layers

The report has two layers, and only the first needs nothing but the command line.

  1. Deterministic. npx ai-insights@latest counts everything: activity, the recap, tokens, cost and findings. No model is involved.
  2. Judged by your agent. The analyze-ai-usage skill has the agent you already use read short, redacted excerpts of a sample of sessions, label each one from a fixed list, and write a short narrative. The labels add “Did it work?”, the work areas, the wins and the judged causes in “Why sessions go wrong”.

Install the plugin

Each install adds the same MCP server, npx -y ai-insights mcp, and three skills. Start a new session afterwards: agents usually load new tools and skills only at startup.

From the command line

npx ai-insights@latest install runs the Claude Code and Codex commands below for whichever of the two is on your machine, after showing them to you. The end of a normal npx ai-insights@latest run offers the same. See the CLI reference.

Terminal
npx ai-insights@latest install --dry-run   # print the commands only
npx ai-insights@latest install             # run them after you say yes

Claude Code

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

Codex

Terminal
codex plugin marketplace add hamedmp/ai-insights
codex plugin add ai-insights@ai-insights

Pi (untested)

Terminal
pi install git:github.com/hamedmp/ai-insights

Pi loads the skills and registers the MCP server through the package's Pi extension. A Pi build without MCP support still loads the skills and shows a warning that the ai_insights_* tools are unavailable.

Cursor and OpenCode (untested)

From a clone of the repository, run the install script for that agent:

Terminal
git clone https://github.com/hamedmp/ai-insights
cd ai-insights
scripts/install.sh --harness cursor     # or: --harness opencode

For Cursor it adds the server to ~/.cursor/mcp.json and the skills to ~/.cursor/skills. For OpenCode it copies the skills to ~/.agents/skills and runs opencode mcp add.

Several agents at once

Run scripts/install.sh with no options. It finds the agents on your machine, copies the skills into each one and registers the MCP server with each agent's own mcp add command. It needs no root, writes only inside your home folder, and is safe to run again. Add --dry-run to see what it would do first. All options are in the CLI reference.

Getting updates

The plugin carries the package version, and both agents keep the installed copy until that version changes. Neither updates it on its own unless you turn that on:

Updates by agent
AgentTo updateAutomatic
Claude Codeclaude plugin update ai-insights@ai-insights in a terminal, or /plugin marketplace update ai-insights in a session; then restartOff by default for this marketplace. Turn it on in /plugin, under Marketplaces, ai-insights, Enable auto-update
Codexcodex plugin marketplace upgrade ai-insights, then start a new sessionNot documented. Codex's source refreshes Git marketplaces in the background at startup and reinstalls a plugin whose version changed, so new releases may arrive on their own
Pi, Cursor, OpenCodeRun the install againNo

The MCP server is separate: npx -y ai-insights mcp asks the npm registry for the newest version each time your agent starts it, so it follows new releases without an update step (it needs the network at that moment). The skills and the session-start reminder come from the installed plugin, so they follow the plugin's version. On Codex the reminder runs only after you approve its hook in /hooks, and again after an update changes it; it has not been seen running in the Codex CLI.

By hand

If you prefer to register only the MCP server:

Terminal
claude mcp add --scope user ai-insights -- npx -y ai-insights mcp
codex mcp add ai-insights -- npx -y ai-insights mcp
opencode mcp add ai-insights -- npx -y ai-insights mcp

For Cursor, add this under mcpServers in ~/.cursor/mcp.json:

~/.cursor/mcp.json
"ai-insights": { "command": "npx", "args": ["-y", "ai-insights", "mcp"] }

The three skills

Skills
SkillWhat it does
analyze-ai-usageBuilds the report with your agent labelling a sample of sessions and writing a narrative, then names the three findings most worth acting on.
ai-insights-coachTurns findings into changes you review: edits to CLAUDE.md or AGENTS.md, settings, plugins. It shows each change as a diff and writes only after a yes for that change.
ai-insights-setupChecks that the MCP server answers, runs doctor, and explains which histories were found and what limits the report.

Run the review

In a new session, run /analyze-ai-usage or ask your agent to “analyze my AI usage”. The skill tells your agent to:

  1. Scan, and show you which agents and dates it covers.
  2. Read the summary and findings.
  3. List sessions that still need a label, spread across your agents and the whole period rather than only the newest, and label at most 30 in one run. It skips sessions still running, slash-command-only sessions and sessions with fewer than 2 prompts, and tells you how many it skipped. Labels are saved in batches, so an interrupted run keeps its progress.
  4. Write a narrative from the digest of all labels, replacing any earlier narrative.
  5. Render the report and give you its path and file:// link.
  6. Close with the three most useful findings and offer the coach.

Running the skill again continues where it stopped: labelled sessions are not judged again unless they changed since (for example, a session that was still running when it was labelled).

What your agent sees

Your agent sees only what the MCP tools return:

  • The numbers and findings, with session ids as evidence.
  • Session listings with counts and the first prompt, cut to 160 characters and redacted. Project paths are shown with your home folder as ~.
  • Excerpts of one session at a time, about 4,000 characters by default. An excerpt is the only place your agent sees the other agent's replies and tool output: your prompts, messages from other agents, tool errors and the final reply are kept first, and routine tool output is cut first. Excerpts are read from the transcript on demand, redacted, and not stored by AI Insights.

The tools tell your agent that excerpt text is data, not instructions, and the skill tells it never to copy a secret into a label even if redaction missed it. Redaction is pattern-based; see Redaction.

Session labels

Each labelled session gets one facet, saved under ~/.ai-insights/facets/. Values outside the fixed lists are rejected, so charts stay comparable from run to run.

Facet fields
FieldValues
underlyingGoal, summary, frictionDetailShort sentences in plain words.
goalCategories1 to 5 of: feature, bug_fix, refactor, tests, review, debugging, research, planning, docs, devops, git_and_prs, data_analysis, configuration, writing, orchestration, tooling, other
sessionTypesingle_task, multi_task, iterative_refinement, exploration, quick_question
outcomefully_achieved, mostly_achieved, partially_achieved, not_achieved, in_progress, unclear
helpfulnessessential, very_helpful, moderately_helpful, slightly_helpful, unhelpful
satisfactionsatisfied, likely_satisfied, neutral, dissatisfied, unclear
frictionsA count per type: misunderstood_request, wrong_approach, buggy_code, incomplete_work, ignored_instructions, over_engineering, permission_block, tool_failure, environment_issue, external_blocker, context_loss, slow_or_stuck
primarySuccessnull, or one of: correct_code_edits, multi_file_changes, good_debugging, fast_accurate_search, good_explanations, proactive_help, good_planning, autonomous_execution
drivenByperson, agent, mixed (optional)

The narrative has a headline, work areas, your interaction style, wins, frictions, suggestions and “horizon” ideas with starter prompts. Suggestion text meant for pasting is rejected if it holds a placeholder such as <n> or an ellipsis. Tool details are in the MCP reference.

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