retrolens

RetroLens — AI Conversation Log Navigator

Navigate AI agent conversation logs like a debugger. Point at a log directory, list sessions, then drill into turns, tool calls, and raw data.

Recommended Flow

The typical workflow follows these steps. Each step has a corresponding command (for Claude Code) and a detailed workflow section below.

/retrolens         → Discover log locations, see what's available
       ↓
/retrolens:connect → Choose a project, connect to its logs, verify
       ↓
/retrolens:analyze → Pick session(s), drill into turns, map phases
       ↓
/retrolens:reflect → Extract human lessons + agent directives

For non-Claude-Code agents, follow the same flow using the Workflow sections (A → B/C → D) directly.

Quick Start

First check whether retrolens is already installed:

retrolens --version

If the command is found, proceed to CLI Commands below.

If not found, ask the user which option they prefer:

1. Already installed — retrolens is installed but not on PATH. Ask the user where/how it was installed (e.g., which venv, conda env, or directory), then help activate the correct environment or adjust PATH.

2. Agent installs — let the agent install it. Ask the user which method to use:

   Method	Command
   pip	pip install retrolens
   uv	uv pip install retrolens
   pipx	pipx install retrolens

   Run the selected command and verify with retrolens --version.

3. Install manually — the user will install it themselves. Provide the install options above for reference and wait for them to confirm it's ready.

---

CLI Commands

cfg — Set Working State (Do This First) ⭐

retrolens cfg set --path /path/to/logs   # Set log directory (auto-detects format)
retrolens cfg set --source vscode        # Override detected source type
retrolens cfg set --reader ./reader.py   # Register a custom reader
retrolens cfg show                       # View current config
retrolens cfg clear                      # Reset to defaults