RetroLens 🔬
A debugger for AI conversations — let any agent navigate, analyze, and learn from past chat sessions.
What is this?
Every day you use AI agents (VS Code Copilot, Claude Code, Cursor…) to write code. Those conversation logs are full of reusable workflows and hard-won lessons — but they're locked inside opaque log files.
RetroLens is a lightweight CLI + Skill that gives any general-purpose AI agent the ability to:
- 📂 Discover log sessions across platforms
- 🔍 Navigate sessions like a debugger — overview → turn → tool call
- 💡 Analyze what happened and extract lessons, workflows, and agent directives
The CLI handles only what agents can't do well — parsing complex log formats and providing a structured traversal API. All analysis and writing is done by the agent itself, guided by SKILL.md.
┌─────────────────────────────────────────────┐
│ AI Agent (Copilot / Claude / Cursor / ...) │
│ │
│ Reads SKILL.md → learns how to use CLI │
│ Calls CLI → gets structured JSON data │
│ Analyzes → uses its own LLM reasoning │
│ Writes → LESSONS.md, AGENTS.md, etc. │
└──────────────────┬──────────────────────────┘
│ CLI calls
▼
┌─────────────────────────────────────────────┐
│ retrolens CLI │
│ │
│ cfg → configure log path & source │
│ ls → list sessions │
│ read → drill into turns & tool calls │
└──────────────────┬──────────────────────────┘
│ Parses log files
▼
┌─────────────────────────────────────────────┐
│ Log Files │
│ VS Code Copilot · Claude Code · Custom │
└─────────────────────────────────────────────┘
Integrating this skill
retrolens must be installed for agent use.
pip install retrolens
retrolens --version
Then add the skill to your agent.
Claude Code
This repo ships a Claude marketplace that installs the retrolens-plugin/ bundle as a plugin.
Step 1: Add marketplace
/plugin marketplace add JoelYYoung/retrolens
Step 2: Install the plugin
/plugin install retrolens
Manual install alternative:
git clone https://github.com/JoelYYoung/retrolens.git
cp -r retrolens/retrolens-plugin ~/.claude/plugins/retrolens
/reload-plugins
VS Code Copilot
VS Code Copilot discovers skills from your repo at .github/skills/<name>/SKILL.md.
From this repo, copy the skill into your target project:
mkdir -p .github/skills/retrolens
cp retrolens-plugin/SKILL.md .github/skills/retrolens/SKILL.md
Generic Skill-Based Agents
If your agent supports local skill folders, copy the skill file:
cp retrolens-plugin/SKILL.md <your-agent-skills-dir>/retrolens/SKILL.md
Then prompt the agent to follow the workflows in SKILL.md while calling the retrolens CLI.
Quick Start
You can specify what to analyze and what artifact to produce.
Common workflows:
1) Find sessions for this project
Use the RetroLens skill to locate conversation logs for this repository and list the most recent 10 sessions (title, date, turn count).
2) Add support for a new log format (custom reader)
This is only needed if your logs are not from VS Code Copilot or Claude Code.
Use the RetroLens skill: logs for a new platform are in <LOG_DIR>. Sample the files, implement a custom reader, and validate it can parse turns and tool calls correctly.
3) Analyze a specific session (ID/prefix: XXX)
Use the RetroLens skill to analyze session XXX: summarize the goal, key pivots, failures and fixes, then write reusable directives to notes/session-XXX-lessons.md.
4) Postmortem the latest session
Use the RetroLens skill to postmortem the latest session and produce 5 human-facing lessons and 5 agent directives in notes/retrolens-latest.md.
Providing the project path, log directory (or platform: VS Code / Claude Code), and the desired output file name will speed things up.
How It Works — the Skill Model
RetroLens is designed to be used by AI agents, not by humans directly. The included SKILL.md teaches any general-purpose agent how to navigate and analyze conversation logs through a series of workflows:
