Lens

Lens is a local-first CLI for understanding how you work with coding agents. The first version reads Cursor agent transcripts from your own machine, computes local metrics, optionally adds your builder profile with your own API key, and writes private Markdown plus HTML reports.

It is inspired by tools that analyze AI coding sessions, but it is designed as an open-source project with local ownership and explicit privacy boundaries.

Current Status

Implemented:

• Cursor transcript discovery from ~/.cursor/projects/*/agent-transcripts
• Parent-session parsing for JSONL transcripts
• Optional subagent inclusion
• Workspace summaries
• Local metrics
• Best-effort redaction for displayed excerpts
• Local Markdown and static HTML report generation
• Optional builder profile with user-supplied OpenAI or Anthropic API keys
• Interactive first-run wizard
• Sensitive-topic exclusion before selected redacted examples and AI payloads

Not implemented yet:

• Claude Code and Codex CLI transcript adapters

Privacy Model

By default, the tool does not call any AI API and does not upload anything.

It reads local Cursor transcript files and writes reports to reports/ in the directory where you run the command. Treat generated reports as private files unless you intentionally share them.

Your builder profile is opt-in with agents-lens ai <workspace>. If no key is configured, the CLI can ask for either an OpenAI or Anthropic API key and use it for that run only. The key prompt is hidden in interactive terminals. Before sending anything, the CLI shows a plain review of what will be sent: destination, endpoint, model, workspace, selected redacted examples, masked secrets, sensitive-topic prompts excluded, and selected data size. Direct commands require --yes; the guided wizard requires an interactive yes. When you choose all workspaces, the wizard asks for AI consent once for the full batch.

When your builder profile is enabled, the provider receives local metrics plus selected redacted examples. Raw transcript files are not sent wholesale.

Before examples are shown or sent to AI, the tool excludes messages matching sensitive-topic policy categories such as secrets, trading/finance, personal identity, admissions/applications, medical/legal, auth credentials, and private credential files. Aggregate local counts may still reflect overall activity, but sensitive text is not used for selected examples or AI payloads.

Redaction is best-effort. Do not treat it as a formal security boundary.

Use With npx

The npm package is prepared as agents-lens:

npx agents-lens
npx agents-lens eXperiments
npx agents-lens ai eXperiments --yes

What happens when you run it:

• Requires Node.js 20 or newer.
• Scans Cursor transcripts from ~/.cursor/projects/*/agent-transcripts.
• Shows the workspaces it finds and asks what to analyze.
• Writes Markdown and HTML reports to ./reports.
• Opens the HTML report if you choose to.
• Does not call an AI provider unless you explicitly ask for your builder profile.
• If you choose all workspaces with AI enabled, Lens shows one batch review and asks once before sending one selected-data request per workspace.

After a global install, both agents-lens and the shorter lens binary are available:

npm install -g agents-lens
lens eXperiments

Local Setup

npm install
npm run build

For builder profiles, copy the env example and add your own key:

cp .env.example .env

Then set one or both keys in .env:

OPENAI_API_KEY=...
ANTHROPIC_API_KEY=...

You can also skip .env and paste either key when the CLI asks for it.

Easiest Start

For local development, run the guided flow:

npm run lens

The wizard will:

• Find Cursor transcript workspaces.
• Ask which workspace to analyze, or all workspaces.
• Generate a local report by default.
• Ask before adding your builder profile.
• Generate Markdown and static HTML reports.
• Open the HTML report in your browser.

Generate a local report for one workspace:

npm run lens -- eXperiments

Same command, with the explicit word report if you prefer:

npm run lens -- report eXperiments

Generate your builder profile:

npm run lens -- ai eXperiments --yes

Lens still shows what will be sent before the AI call:

• Raw transcript files are never sent wholesale.
• Only local metrics and selected redacted examples are used.
• Secrets are masked inside examples.
• Sensitive-topic prompts are excluded from examples and AI payloads.
• “Selected data size” is not the full workspace size. It is only the local metrics plus selected redacted examples prepared for the AI request.

Analyze all workspaces locally:

npm run lens -- all

Generate local reports for all workspaces with the explicit word report:

npm run lens -- report all

Clean generated reports:

npm run lens -- clean

Actually delete generated reports:

npm run lens -- clean --yes

Advanced Commands

Scan available Cursor transcript workspaces:

npm run scan

Inspect one workspace:

npm run inspect -- --workspace eXperiments

Generate local Markdown and HTML reports:

npm run analyze -- --workspace eXperiments

Generate and open the HTML report:

npm run analyze -- --workspace eXperiments --open

Generate your builder profile with OpenAI using the advanced command:

npm run analyze -- --workspace eXperiments --llm --provider openai --yes

Generate your builder profile with Anthropic:

npm run analyze -- --workspace eXperiments --llm --provider anthropic --yes

Override the model:

npm run analyze -- --workspace eXperiments --llm --provider anthropic --model claude-3-5-sonnet-latest --yes

Include subagent sessions:

npm run scan -- --include-subagents

Use a custom Cursor projects directory:

npm run scan -- --cursor-projects-dir /path/to/cursor/projects

How Transcript Discovery Works

Cursor stores agent transcripts outside the repo, under local Cursor project folders. This tool scans:

~/.cursor/projects/*/agent-transcripts/**/*.jsonl

By default, it skips subagents/ so the first report reflects user-facing conversations. Pass --include-subagents to include those sessions.

Cursor workspaces may not map one-to-one with a repo subfolder. If Cursor was opened at a parent directory, the transcript workspace will be that parent directory.

Development

npm run check
npm run build