cursor-insights

Usage insights report built from locally stored Cursor Agent conversations (~/.cursor/projects/.../agent-transcripts/*.jsonl).

Inspired by Claude Code’s /insights command — see the reference implementation: insights.ts.

Requirements

• Python 3.11+
• Cursor agent sessions already recorded (open the project in Cursor and chat with the agent)
• For AI analysis: ANTHROPIC_API_KEY or OPENAI_API_KEY

Installation

cd cursor-insights
python3 -m venv .venv
source .venv/bin/activate
pip install -e .

Usage

From this directory:

# All Cursor workspaces on this machine (default)
python cli.py

# Last 30 days only
python cli.py --days 30

# Single repository
python cli.py /path/to/my-project

# Related worktrees (same basename)
python cli.py /path/to/my-project --include-related

# Report + AI analysis
python cli.py --with-ai --open

# Force provider / model
export ANTHROPIC_API_KEY=...
python cli.py --with-ai --provider anthropic --model claude-sonnet-4-20250514

After pip install -e ., the insights command is also available (entry point for cli.py).

Outputs

Mode	HTML report	AI cache
All projects	.cursor-insights/report.html (in this repo)	.cursor-insights/cache/
Filtered project	<project>/.cursor-insights/report.html	<project>/.cursor-insights/cache/

Useful flags:

• --output path.html — custom output path
• --json — write JSON alongside the HTML report
• --max-ai-sessions 50 — cap LLM facet extractions (default: 50)
• --refresh-ai — ignore cached facets

How conversations are read

1. Cursor writes JSONL files under ~/.cursor/projects/<slug>/agent-transcripts/<uuid>/<uuid>.jsonl
2. The slug maps from the project path: /home/user/foo/bar → home-user-foo-bar
3. The script parses user / assistant messages and tool calls (Grep, Shell, MCP, etc.)

No Cursor API — local file reads only.

Report contents

Without --with-ai: stats (sessions, messages, tools, languages, estimated git commits, charts).

With --with-ai: per-session facets (goals, friction, satisfaction) + narrative sections (At a Glance, work areas, friction, Cursor tips, etc.).

Project layout

cli.py           # entry point
discovery.py     # find transcripts
parser.py        # JSONL parsing
aggregate.py     # aggregation
report.py        # HTML report
facets.py        # AI facets + cache
insights_ai.py   # narrative AI sections
llm.py           # Anthropic / OpenAI client
transcript.py    # LLM transcript formatting
test/

Tests

pytest test/

Environment variables

Variable	Description
ANTHROPIC_API_KEY	Anthropic provider (preferred in auto mode)
OPENAI_API_KEY	OpenAI provider
CURSOR_INSIGHTS_MODEL	Default model override (else Sonnet 4 / gpt-4.1-mini)