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 an AI-written 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 AI-written profile with user-supplied OpenAI or Anthropic API keys
• Interactive first-run wizard
• Sensitive-topic exclusion before safe 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 transcript files and writes reports to reports/. Generated reports are gitignored by default.

AI profiles are opt-in with npm run 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. Before sending anything, the CLI shows a plain review of what will be sent: destination, model, workspace, selected safe examples, masked secrets, private messages skipped, and estimated size. It will not send the request unless you pass --yes.

When an AI profile is enabled, the provider receives local metrics plus selected safe 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 safe 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

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 AI 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 an AI-written 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 an AI-written 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 safe example prompts are used.
• Secrets are masked inside examples.
• Private messages are skipped from examples and AI payloads.

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 an AI profile with OpenAI using the advanced command:

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

Generate an AI 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