reprompt-cli 1.5.0__tar.gz → 1.6.0__tar.gz

{reprompt_cli-1.5.0 → reprompt_cli-1.6.0}/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 All notable changes to this project will be documented in this file.
 
+## [1.6.0] - 2026-03-28
+
+### Added
+- **Agent workflow analysis** — `reprompt agent` detects error loops, tool call patterns, and session efficiency from existing session files. Zero config, zero instrumentation.
+- **Codex CLI adapter** — full support for OpenAI Codex CLI sessions (`~/.codex/sessions/`), including user/assistant turns, tool calls (shell + function), error detection with exit codes, and file path tracking. 9th adapter.
+- **Sensitive content detection** — `reprompt privacy --deep` scans stored prompts for API keys, JWT tokens, emails, IP addresses, passwords, env secrets, and home paths. All regex-based, zero network.
+- **Chrome Web Store extension** — `install-extension` now defaults to the published extension ID; `extension-status` shows the Chrome Web Store install link.
+- **Extension E2E tests** — 8 tests covering the full extension -> Native Messaging -> DB -> CLI pipeline across 3 sources.
+
+### Changed
+- **ConversationTurn model** — added `tool_names` and `error_text` fields for richer agent analysis (backward-compatible defaults)
+- **Claude Code adapter** — now extracts individual tool names (Read, Edit, Bash, etc.) from tool_use blocks, not just counts
+- **Suggestions** — `distill` now suggests `reprompt agent`; `agent` suggests `--loops-only` and `privacy --deep`
+- Tests: 1397 -> 1490+
+
 ## [1.5.0] - 2026-03-25
 
 ### Added

{reprompt_cli-1.5.0 → reprompt_cli-1.6.0}/CLAUDE.md

@@ -18,7 +18,7 @@ uv run python -m build                     # build wheel
 
 ```
 src/reprompt/
-├── cli.py              # Typer CLI (scan, import, report, search, demo, status, purge, install-hook, install-extension, extension-status, score, compare, insights, digest, style, template [save|list|use], privacy, compress, distill, lint, wrapped, telemetry, mcp-serve) + bare `reprompt` dashboard + plugin loading
+├── cli.py              # Typer CLI (scan, import, report, search, demo, status, purge, install-hook, install-extension, extension-status, score, compare, insights, digest, style, template [save|list|use], privacy, compress, distill, agent, lint, wrapped, telemetry, mcp-serve) + bare `reprompt` dashboard + plugin loading
 ├── config.py           # pydantic-settings, env vars (REPROMPT_ prefix) + TOML config
 ├── demo.py             # Built-in demo data generator (no network required)
 ├── core/
@@ -40,13 +40,16 @@ src/reprompt/
 │   ├── persona.py       # 6 prompt personas (Architect/Debugger/Explorer/Novelist/Sniper/Teacher)
 │   ├── wrapped.py       # WrappedReport dataclass + build_wrapped(db) aggregation
 │   ├── privacy.py       # Privacy metadata registry + exposure summary per adapter
+│   ├── privacy_scan.py  # Sensitive content detection (API keys, tokens, PII) via regex
 │   ├── compress.py      # 4-layer prompt compression (char norm + phrase simplify + filler delete + structure cleanup)
-│   ├── suggestions.py   # Command journey suggestions ("→ Try:" hints for 5 core commands)
+│   ├── suggestions.py   # Command journey suggestions ("→ Try:" hints for 7 core commands)
 │   ├── conversation.py  # ConversationTurn, Conversation, DistillResult dataclasses
-│   └── distill.py       # 6-signal importance scoring + filtering + summary generation
+│   ├── distill.py       # 6-signal importance scoring + filtering + summary generation
+│   └── agent.py         # Agent workflow analysis: error loop detection, tool distribution, efficiency
 ├── adapters/
 │   ├── base.py         # BaseAdapter ABC + parse_conversation() default
-│   ├── claude_code.py  # Claude Code JSONL parser
+│   ├── claude_code.py  # Claude Code JSONL parser (full conversation + tool names)
+│   ├── codex.py        # Codex CLI JSONL rollout parser (full conversation + shell/function calls)
 │   ├── openclaw.py     # OpenClaw JSON parser (supports ~/.openclaw/ + legacy ~/.opencode/)
 │   ├── cursor.py       # Cursor IDE .vscdb parser (cursorDiskKV + legacy ItemTable)
 │   ├── aider.py        # Aider markdown chat history parser (.aider.chat.history.md)
@@ -87,7 +90,8 @@ src/reprompt/
     ├── wrapped_terminal.py # Rich Prompt Wrapped report rendering
     ├── wrapped_html.py     # Self-contained HTML share card (dark theme)
     ├── compress_terminal.py # Rich output for compress command
-    └── distill_terminal.py  # Rich output for distill command
+    ├── distill_terminal.py  # Rich output for distill command
+    └── agent_terminal.py   # Rich output for agent workflow report
 ```
 
 ## Data Flow
@@ -124,7 +128,7 @@ reprompt-extension (private)   ← Browser extension: Chrome/Firefox prompt capt
 - Pattern upsert (not clear+re-insert) for stable IDs
 - Prompts starting with `<` are filtered (system-injected XML)
 - Config: env vars (REPROMPT_ prefix) > TOML (~/.config/reprompt/config.toml) > defaults
-- Tests: pytest, 1397 tests, 95% coverage target
+- Tests: pytest, 1490+ tests, 95% coverage target
 
 ## Prompt Science Engine
 

{reprompt_cli-1.5.0 → reprompt_cli-1.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: reprompt-cli
-Version: 1.5.0
+Version: 1.6.0
 Summary: Discover, analyze, and optimize your prompts from AI coding sessions
 Project-URL: Homepage, https://github.com/reprompt-dev/reprompt
 Project-URL: Repository, https://github.com/reprompt-dev/reprompt
@@ -50,7 +50,7 @@ Description-Content-Type: text/markdown
 [![PyPI version](https://img.shields.io/pypi/v/reprompt-cli)](https://pypi.org/project/reprompt-cli/)
 [![Python 3.10+](https://img.shields.io/pypi/pyversions/reprompt-cli)](https://pypi.org/project/reprompt-cli/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Tests](https://img.shields.io/badge/tests-1397-brightgreen)](https://github.com/reprompt-dev/reprompt)
+[![Tests](https://img.shields.io/badge/tests-passing-brightgreen)](https://github.com/reprompt-dev/reprompt/actions)
 [![Coverage](https://img.shields.io/badge/coverage-95%25-brightgreen)](https://github.com/reprompt-dev/reprompt)
 
 ---
@@ -88,11 +88,12 @@ $ reprompt compress "请帮我看一下这个代码，就是那个 login 的那
 | Command | Description |
 |---------|-------------|
 | `reprompt` | Instant dashboard -- prompts, sessions, avg score, top categories |
-| `reprompt scan` | Auto-discover prompts from 8 AI tools |
+| `reprompt scan` | Auto-discover prompts from 9 AI tools |
 | `reprompt score "prompt"` | Research-backed 0-100 scoring with 30+ features |
 | `reprompt compare "a" "b"` | Side-by-side prompt analysis (or `--best-worst` for auto-selection) |
 | `reprompt insights` | Personal patterns vs research-optimal benchmarks |
 | `reprompt style` | Prompting fingerprint with `--trends` for evolution tracking |
+| `reprompt agent` | Agent workflow analysis -- error loops, tool patterns, session efficiency |
 
 ### Optimize
 
@@ -108,6 +109,7 @@ $ reprompt compress "请帮我看一下这个代码，就是那个 login 的那
 | Command | Description |
 |---------|-------------|
 | `reprompt privacy` | See what data you sent where -- file paths, errors, PII exposure |
+| `reprompt privacy --deep` | Scan for sensitive content: API keys, tokens, passwords, PII |
 | `reprompt report` | Full analytics: hot phrases, clusters, patterns (`--html` for dashboard) |
 | `reprompt digest` | Weekly summary comparing current vs previous period |
 | `reprompt wrapped` | Prompt DNA report -- persona, scores, shareable card |
@@ -145,6 +147,7 @@ Session type (debugging, feature-dev, exploration, refactoring) is auto-detected
 | Tool | Format | Auto-discovered by `scan` |
 |------|--------|--------------------------|
 | Claude Code | JSONL | Yes |
+| Codex CLI | JSONL | Yes |
 | Cursor | .vscdb | Yes |
 | Aider | Markdown | Yes |
 | Gemini CLI | JSON | Yes |
@@ -176,6 +179,16 @@ reprompt distill --last 1           # distill your most recent conversation
 reprompt install-hook               # adds post-session hook to Claude Code
 ```
 
+### Browser extension
+
+Capture prompts from ChatGPT, Claude.ai, and Gemini directly in your browser:
+
+1. **Install the extension** from [Chrome Web Store](https://chromewebstore.google.com/detail/reprompt/ojdccpagaanchmkninlbgbgemdcjckhn)
+2. **Connect to the CLI:** `reprompt install-extension`
+3. **Verify:** `reprompt extension-status`
+
+Captured prompts sync locally via Native Messaging -- nothing leaves your machine.
+
 ## Privacy
 
 - All analysis runs locally. No prompts leave your machine.
@@ -188,6 +201,7 @@ reprompt install-hook               # adds post-session hook to Claude Code
 ## Links
 
 - **Website:** [getreprompt.dev](https://getreprompt.dev)
+- **Chrome Extension:** [Chrome Web Store](https://chromewebstore.google.com/detail/reprompt/ojdccpagaanchmkninlbgbgemdcjckhn)
 - **PyPI:** [reprompt-cli](https://pypi.org/project/reprompt-cli/)
 - **Changelog:** [CHANGELOG.md](CHANGELOG.md)
 - **Privacy:** [getreprompt.dev/privacy](https://getreprompt.dev/privacy)

{reprompt_cli-1.5.0 → reprompt_cli-1.6.0}/README.md

@@ -5,7 +5,7 @@
 [![PyPI version](https://img.shields.io/pypi/v/reprompt-cli)](https://pypi.org/project/reprompt-cli/)
 [![Python 3.10+](https://img.shields.io/pypi/pyversions/reprompt-cli)](https://pypi.org/project/reprompt-cli/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Tests](https://img.shields.io/badge/tests-1397-brightgreen)](https://github.com/reprompt-dev/reprompt)
+[![Tests](https://img.shields.io/badge/tests-passing-brightgreen)](https://github.com/reprompt-dev/reprompt/actions)
 [![Coverage](https://img.shields.io/badge/coverage-95%25-brightgreen)](https://github.com/reprompt-dev/reprompt)
 
 ---
@@ -43,11 +43,12 @@ $ reprompt compress "请帮我看一下这个代码，就是那个 login 的那
 | Command | Description |
 |---------|-------------|
 | `reprompt` | Instant dashboard -- prompts, sessions, avg score, top categories |
-| `reprompt scan` | Auto-discover prompts from 8 AI tools |
+| `reprompt scan` | Auto-discover prompts from 9 AI tools |
 | `reprompt score "prompt"` | Research-backed 0-100 scoring with 30+ features |
 | `reprompt compare "a" "b"` | Side-by-side prompt analysis (or `--best-worst` for auto-selection) |
 | `reprompt insights` | Personal patterns vs research-optimal benchmarks |
 | `reprompt style` | Prompting fingerprint with `--trends` for evolution tracking |
+| `reprompt agent` | Agent workflow analysis -- error loops, tool patterns, session efficiency |
 
 ### Optimize
 
@@ -63,6 +64,7 @@ $ reprompt compress "请帮我看一下这个代码，就是那个 login 的那
 | Command | Description |
 |---------|-------------|
 | `reprompt privacy` | See what data you sent where -- file paths, errors, PII exposure |
+| `reprompt privacy --deep` | Scan for sensitive content: API keys, tokens, passwords, PII |
 | `reprompt report` | Full analytics: hot phrases, clusters, patterns (`--html` for dashboard) |
 | `reprompt digest` | Weekly summary comparing current vs previous period |
 | `reprompt wrapped` | Prompt DNA report -- persona, scores, shareable card |
@@ -100,6 +102,7 @@ Session type (debugging, feature-dev, exploration, refactoring) is auto-detected
 | Tool | Format | Auto-discovered by `scan` |
 |------|--------|--------------------------|
 | Claude Code | JSONL | Yes |
+| Codex CLI | JSONL | Yes |
 | Cursor | .vscdb | Yes |
 | Aider | Markdown | Yes |
 | Gemini CLI | JSON | Yes |
@@ -131,6 +134,16 @@ reprompt distill --last 1           # distill your most recent conversation
 reprompt install-hook               # adds post-session hook to Claude Code
 ```
 
+### Browser extension
+
+Capture prompts from ChatGPT, Claude.ai, and Gemini directly in your browser:
+
+1. **Install the extension** from [Chrome Web Store](https://chromewebstore.google.com/detail/reprompt/ojdccpagaanchmkninlbgbgemdcjckhn)
+2. **Connect to the CLI:** `reprompt install-extension`
+3. **Verify:** `reprompt extension-status`
+
+Captured prompts sync locally via Native Messaging -- nothing leaves your machine.
+
 ## Privacy
 
 - All analysis runs locally. No prompts leave your machine.
@@ -143,6 +156,7 @@ reprompt install-hook               # adds post-session hook to Claude Code
 ## Links
 
 - **Website:** [getreprompt.dev](https://getreprompt.dev)
+- **Chrome Extension:** [Chrome Web Store](https://chromewebstore.google.com/detail/reprompt/ojdccpagaanchmkninlbgbgemdcjckhn)
 - **PyPI:** [reprompt-cli](https://pypi.org/project/reprompt-cli/)
 - **Changelog:** [CHANGELOG.md](CHANGELOG.md)
 - **Privacy:** [getreprompt.dev/privacy](https://getreprompt.dev/privacy)

reprompt_cli-1.6.0/docs/superpowers/specs/2026-03-28-v1.6-agent-intelligence-design.md

@@ -0,0 +1,479 @@
+# v1.6 Agent Intelligence — Design Spec
+
+## Goal
+
+Add retrospective agent workflow analysis to reprompt. Detect error loops, tool call patterns, and session efficiency from existing session files — zero config, zero instrumentation, zero network.
+
+**What we are NOT building:** An observability platform. We don't instrument code, don't intercept API calls, don't require setup before a session runs. We analyze what already exists on disk.
+
+## Problem Statement
+
+AI coding agents (Claude Code, Codex, Gemini CLI) generate rich session logs locally. Users have no way to answer:
+
+- "How much of that 45-minute session was wasted on error loops?"
+- "Which tools am I triggering most — am I using the agent efficiently?"
+- "Was that session actually productive, or did it just feel busy?"
+
+**Every existing tool (Langfuse, LangSmith, AgentOps) requires SDK instrumentation before the session runs.** No tool does post-hoc analysis of existing local session files. This is our unique angle.
+
+**User stories:**
+- "Show me an agent health report for my last 5 coding sessions."
+- "Did my Claude Code session get stuck in error loops? Where?"
+- "Compare my debugging sessions to my feature-dev sessions — which are more efficient?"
+
+## Principle Revision
+
+Current: "Input not output — analyze human inputs, not LLM outputs"
+
+**Revised:** "Human-centric analysis — analyze the human-AI interaction, not LLM output quality"
+
+Rationale: Agent workflow analysis evaluates *interaction quality* (error loops, tool patterns, session flow), not *output quality* (hallucination, correctness). This is distinct from what Promptfoo/Braintrust do (eval LLM outputs). We stay on the "analyze the developer's experience" side.
+
+## Scope
+
+### In scope (v1.6)
+
+| Item | Rationale |
+|------|-----------|
+| `reprompt agent` command | Core deliverable — agent session health report |
+| Claude Code adapter: extract tool names | Unblock agent analysis for existing users |
+| Codex CLI adapter (new) | Richest data format, fastest-growing agent CLI |
+| Error loop detection (rule-based) | High user value, unique angle |
+| Tool call distribution analysis | Basic but useful |
+| Session efficiency scoring | Builds on existing effectiveness module |
+| `reprompt privacy --deep` | Small scope, high narrative value |
+
+### Out of scope (v1.7+)
+
+| Item | Why deferred |
+|------|-------------|
+| Context window utilization % | Claude Code token data unreliable (75% zeros); Codex has it but we ship Claude Code first |
+| Cross-adapter agent comparison | Only 2 adapters have full data; wait for more |
+| `.reprompt.yml` configurable lint | Independent feature, separate release |
+| Cross-prompt repetition metric | Depends on agent analysis infra, do after |
+| Gemini CLI / Cline agent analysis | Need real session files to verify data availability |
+
+## Architecture
+
+```
+Session file (JSONL/JSON)
+  → Adapter.parse_conversation()      # returns list[ConversationTurn]
+    → now includes tool_names per turn
+  → AgentAnalyzer.analyze(turns)       # NEW: core/agent.py
+    → error_loops: list[ErrorLoop]
+    → tool_distribution: dict[str, int]
+    → efficiency: AgentEfficiency
+  → AgentReport (dataclass)
+  → Output: terminal / JSON
+```
+
+### New modules
+
+```
+src/reprompt/
+  core/
+    agent.py           # AgentAnalyzer: error loop detection, tool distribution, efficiency
+  adapters/
+    codex.py           # NEW: Codex CLI adapter with full conversation parsing
+  output/
+    agent_terminal.py  # Rich terminal rendering for agent report
+```
+
+### Modified modules
+
+```
+  core/
+    conversation.py    # ConversationTurn: add tool_names, error_text fields
+  adapters/
+    claude_code.py     # Extract tool names from tool_use blocks
+  cli.py               # Add `reprompt agent` command
+```
+
+## Data Model Changes
+
+### ConversationTurn (extend, backward-compatible)
+
+```python
+@dataclass
+class ConversationTurn:
+    role: str
+    text: str
+    timestamp: str
+    turn_index: int
+
+    # Existing (unchanged)
+    tool_calls: int = 0
+    has_error: bool = False
+    tool_use_paths: list[str] = field(default_factory=list)
+
+    # NEW for v1.6
+    tool_names: list[str] = field(default_factory=list)   # ["Read", "Edit", "Bash"]
+    error_text: str = ""                                    # Actual error message for fingerprinting
+
+    # Existing enrichment (unchanged)
+    score: float | None = None
+    is_duplicate: bool = False
+    importance: float = 0.0
+    signal_scores: dict[str, float] = field(default_factory=dict)
+```
+
+All new fields default to empty — zero risk of breaking existing code.
+
+### AgentReport (new dataclass)
+
+```python
+@dataclass
+class ErrorLoop:
+    """A detected error loop in the conversation."""
+    start_turn: int          # Turn index where loop starts
+    end_turn: int            # Turn index where loop ends (or session end)
+    loop_count: int          # Number of repetitions
+    fingerprint: str         # What repeated (e.g. "Bash(pytest):error")
+    tool_name: str           # Primary tool involved
+    description: str         # Human-readable: "Bash(pytest tests/) failed 4 times"
+
+@dataclass
+class AgentEfficiency:
+    """Session-level efficiency metrics."""
+    total_turns: int
+    user_turns: int
+    tool_calls: int
+    errors: int
+    error_loops: int
+    turns_in_loops: int          # Turns wasted in error loops
+    productive_ratio: float      # (total - turns_in_loops) / total
+    tools_per_user_turn: float   # tool_calls / user_turns
+    error_recovery_rate: float   # loops_resolved / total_loops
+    duration_seconds: int
+    session_type: str | None     # From existing session_type.py
+
+@dataclass
+class AgentReport:
+    """Full agent analysis for one session."""
+    session_id: str
+    source: str
+    project: str | None
+    efficiency: AgentEfficiency
+    tool_distribution: dict[str, int]   # {"Read": 45, "Edit": 23, ...}
+    error_loops: list[ErrorLoop]
+    top_files: list[str]                # Most-touched files (from tool_use_paths)
+```
+
+## Error Loop Detection Algorithm
+
+### Fingerprinting (rule-based, zero LLM)
+
+```
+For each assistant turn with tool calls:
+  fingerprint = hash(tool_name, target_file_or_command, has_error)
+
+Scan fingerprint sequence for consecutive repeats:
+  [A, B, A, B, A, B] → loop of (A,B) x3
+  [A, A, A, A]       → loop of (A) x4
+
+Minimum loop length: 3 repetitions of the same fingerprint OR 2 repetitions of a 2-step pattern.
+```
+
+### Fingerprint construction
+
+| Adapter | Fingerprint components |
+|---------|----------------------|
+| Claude Code | `tool_name` + first `tool_use_path` (or first 50 chars of input) + `has_error` |
+| Codex CLI | `tool_type` + `command[0]` (or `function_name`) + `exit_code != 0` |
+
+### Example
+
+```
+Turn 10: Bash(pytest tests/test_auth.py) → exit 1
+Turn 11: Edit(src/auth.py)
+Turn 12: Bash(pytest tests/test_auth.py) → exit 1
+Turn 13: Edit(src/auth.py)
+Turn 14: Bash(pytest tests/test_auth.py) → exit 1
+
+→ ErrorLoop(start=10, end=14, count=3, fingerprint="Bash:pytest:fail→Edit:auth.py",
+            description="Bash(pytest tests/test_auth.py) → Edit(src/auth.py) loop x3")
+```
+
+## Codex CLI Adapter
+
+### Session discovery
+
+```python
+class CodexAdapter(BaseAdapter):
+    name = "codex"
+    default_session_path = "~/.codex"
+
+    def discover_sessions(self) -> list[Path]:
+        """Find rollout-*.jsonl under ~/.codex/sessions/."""
+        sessions_dir = self._home / "sessions"
+        return sorted(sessions_dir.rglob("rollout-*.jsonl"))
+```
+
+### JSONL line types to parse
+
+| Line type | payload.type | What we extract |
+|-----------|-------------|-----------------|
+| `event_msg` | `user_message` | User turn: `message` text |
+| `event_msg` | `agent_message` | Assistant turn: `message` text |
+| `response_item` | `local_shell_call` | Tool call: command, status |
+| `response_item` | `function_call` | Tool call: name, arguments |
+| `event_msg` | `exec_command_end` | Tool result: exit_code, output, duration |
+| `event_msg` | `error` | Error: message text |
+| `event_msg` | `token_count` | Token usage (accurate, unlike Claude Code) |
+| `session_meta` | — | Session ID, cwd, git info, model |
+
+### parse_conversation() strategy
+
+Codex interleaves events differently from Claude Code. Key difference:
+
+- Claude Code: one JSONL line = one complete turn (user or assistant with all tool_use blocks)
+- Codex: one JSONL line = one event. An assistant "turn" is: `agent_message` + N x `response_item` + N x `exec_command_end`, terminated by next `user_message` or EOF.
+
+Strategy: accumulate events into turns. When we see a `user_message`, flush the accumulated assistant turn and start a new user turn.
+
+### Token data (Codex-only bonus, deferred display)
+
+Codex provides accurate `total_token_usage` with `model_context_window`. We parse and store it in the adapter but only display it in v1.7 when we add context utilization analysis. This avoids showing token data for Codex but not Claude Code, which would confuse users.
+
+## CLI Command
+
+```
+reprompt agent [OPTIONS]
+
+Options:
+  --last N          Analyze N most recent sessions (default: 5)
+  --source TEXT     Filter by adapter (claude-code, codex)
+  --json            JSON output
+  --copy            Copy to clipboard
+  --loops-only      Show only error loops (skip distribution/efficiency)
+```
+
+### Terminal output (Rich)
+
+```
+╭─ Agent Report ─────────────────────────────────────────────╮
+│  Sessions: 5  │  Source: claude-code  │  Period: 3 days     │
+╰────────────────────────────────────────────────────────────╯
+
+  Efficiency
+  ──────────
+  Avg turns: 28  │  Avg duration: 18min  │  Productive: 82%
+  Tool calls: 847  │  Errors: 23  │  Error loops: 3
+
+  Tool Distribution
+  ─────────────────
+  Read       ████████████████████  312  (37%)
+  Edit       ████████████         198  (23%)
+  Bash       ██████████           156  (18%)
+  Grep       ██████                94  (11%)
+  Write      █████                 87  (10%)
+
+  Error Loops
+  ───────────
+  1. session-abc (14:32, debugging)
+     Bash(pytest tests/test_auth.py) → Edit(src/auth.py) loop x4
+     12 turns wasted, resolved after changing approach
+
+  2. session-def (09:15, implementation)
+     Grep(nonexistent_func) → Read loop x3
+     6 turns wasted, unresolved (session ended)
+
+  Session Breakdown
+  ─────────────────
+  ★★★★★  session-789   8 turns   0 errors  12min  feature-dev
+  ★★★★☆  session-ghi  22 turns   2 errors  20min  implementation
+  ★★★☆☆  session-jkl  35 turns   5 errors  30min  debugging
+  ★★☆☆☆  session-abc  42 turns   8 errors  45min  debugging
+  ★☆☆☆☆  session-def  18 turns  12 errors  15min  debugging
+```
+
+### JSON output structure
+
+```json
+{
+  "sessions_analyzed": 5,
+  "period": {"start": "2026-03-25", "end": "2026-03-28"},
+  "aggregate": {
+    "total_turns": 125,
+    "total_tool_calls": 847,
+    "total_errors": 23,
+    "error_loops": 3,
+    "productive_ratio": 0.82,
+    "avg_turns_per_session": 25,
+    "avg_duration_seconds": 1080
+  },
+  "tool_distribution": {"Read": 312, "Edit": 198, "Bash": 156, "Grep": 94, "Write": 87},
+  "error_loops": [
+    {
+      "session_id": "abc",
+      "start_turn": 10,
+      "end_turn": 22,
+      "loop_count": 4,
+      "fingerprint": "Bash:pytest:fail→Edit:auth.py",
+      "tool_name": "Bash",
+      "description": "Bash(pytest tests/test_auth.py) → Edit(src/auth.py) loop x4"
+    }
+  ],
+  "sessions": [
+    {
+      "session_id": "789",
+      "source": "claude-code",
+      "efficiency": { "...": "..." },
+      "tool_distribution": {},
+      "error_loops": []
+    }
+  ]
+}
+```
+
+## Privacy --deep (Sensitive Content Detection)
+
+Extend existing `reprompt privacy` with `--deep` flag:
+
+```bash
+reprompt privacy --deep        # scan stored prompts for sensitive content
+reprompt privacy --deep --json # structured output
+```
+
+### Detection patterns (regex, zero LLM)
+
+| Category | Pattern | Example |
+|----------|---------|---------|
+| API keys | `(sk-[a-zA-Z0-9]{20,})`, `(AKIA[0-9A-Z]{16})`, `(ghp_[a-zA-Z0-9]{36})` | `sk-proj-abc...`, `AKIAIOSFODNN7EXAMPLE`, `ghp_xxxx` |
+| Tokens | `(eyJ[a-zA-Z0-9_-]{20,}\.[a-zA-Z0-9_-]+)` | JWT tokens |
+| Emails | Standard email regex | `user@company.com` |
+| IP addresses | IPv4 pattern (exclude 127.0.0.1, 0.0.0.0) | `192.168.1.100` |
+| Passwords | `password\s*[=:]\s*["']?\S+` | `password = "secret123"` |
+| Env secrets | `(DATABASE_URL\|SECRET_KEY\|API_KEY\|TOKEN)\s*=\s*\S+` | `DATABASE_URL=postgres://...` |
+| Home paths | `/Users/\w+/`, `/home/\w+/` | Leaks username |
+
+### Output
+
+```
+Sensitive Content Scan (847 prompts analyzed)
+─────────────────────────────────────────────
+  API keys:     2 found (chatgpt, claude-code)
+  JWT tokens:   1 found (claude-code)
+  Home paths:   34 found (claude-code, cursor)
+  Emails:       0
+  IP addresses: 3 found (claude-code)
+
+  Highest risk: session abc123 — contains AWS access key (AKIA...)
+  Run `reprompt privacy --deep --json` for full details.
+```
+
+## Implementation Phases
+
+### Phase 1: Data Model + Claude Code Adapter (Day 1)
+
+**Files:** `core/conversation.py`, `adapters/claude_code.py`
+
+1. Add `tool_names: list[str]` and `error_text: str` to ConversationTurn
+2. In ClaudeCodeAdapter.parse_conversation(), extract `block.get("name")` into `tool_names`
+3. Extract error text (not just boolean) into `error_text`
+
+**Tests:** Existing 1397 tests must pass (backward compat) + 5 new tests for tool name extraction
+
+**Gate:** `uv run pytest tests/ -v` all green before proceeding
+
+### Phase 2: Agent Analysis Engine (Day 1-2)
+
+**Files:** `core/agent.py` (new)
+
+1. `detect_error_loops(turns) -> list[ErrorLoop]` — fingerprint algorithm
+2. `compute_tool_distribution(turns) -> dict[str, int]`
+3. `compute_efficiency(turns, duration, session_type) -> AgentEfficiency`
+4. `analyze_session(conversation) -> AgentReport`
+5. `analyze_sessions(conversations) -> AggregateAgentReport` — multi-session rollup
+
+**Tests:** 20+ unit tests covering:
+- Loop detection: no loops, single loop, nested loops, 2-step patterns
+- Edge cases: empty session, user-only session, single-turn session
+- Tool distribution: multiple tools, single tool, no tools
+- Efficiency: zero errors, all errors, mixed
+
+**Gate:** All Phase 2 tests pass before proceeding
+
+### Phase 3: CLI Command + Terminal Output (Day 2)
+
+**Files:** `cli.py`, `output/agent_terminal.py` (new)
+
+1. `reprompt agent` command with --last, --source, --json, --copy, --loops-only
+2. Rich terminal rendering: efficiency summary, bar chart, error loop list, session breakdown
+3. Suggestion: "-> Try: reprompt agent --loops-only" after distill
+
+**Tests:** 8+ CLI tests (exit codes, json output, empty state, source filter)
+
+**Gate:** CLI tests + manual smoke test
+
+### Phase 4: Codex CLI Adapter (Day 2-3)
+
+**Files:** `adapters/codex.py` (new)
+
+1. `CodexAdapter(BaseAdapter)` with discover_sessions, parse_session, parse_conversation
+2. Session discovery: `~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl`
+3. Full conversation parsing: user messages, agent messages, tool calls, errors
+4. parse_session_meta() with accurate token data (stored but not displayed yet)
+5. Register in scan discovery + CLI adapter list
+
+**Tests:** 15+ tests with fixture JSONL files covering:
+- Session discovery
+- User/assistant turn parsing
+- Tool call extraction (shell + function_call)
+- Error event handling
+- Token data parsing
+- Edge cases: empty session, malformed lines
+
+**Gate:** All adapter tests pass + `reprompt scan` discovers Codex sessions
+
+### Phase 5: Privacy --deep (Day 3)
+
+**Files:** `core/privacy_scan.py` (new), `cli.py` (extend privacy command)
+
+1. Regex-based sensitive content scanner
+2. `--deep` flag on existing privacy command
+3. Per-prompt scanning with category + source attribution
+
+**Tests:** 12+ tests covering each pattern category + false positive avoidance
+
+**Gate:** Tests pass + manual check against real DB
+
+### Phase 6: Integration + Polish (Day 3-4)
+
+1. CHANGELOG entry for v1.6.0
+2. README update: Agent Intelligence section
+3. `reprompt` dashboard: show agent health summary if agent data available
+4. Suggestion wiring: distill -> agent, agent -> privacy --deep
+5. Full test suite run (target: 1500+ tests)
+
+**Gate:** `uv run pytest tests/ -v` all green, `ruff check`, `ruff format --check`, CI green
+
+## Test Plan
+
+| Phase | New tests | Cumulative |
+|-------|-----------|------------|
+| Phase 1 | 5 (conversation model + adapter) | 1402 |
+| Phase 2 | 20 (agent analysis engine) | 1422 |
+| Phase 3 | 8 (CLI + output) | 1430 |
+| Phase 4 | 15 (Codex adapter) | 1445 |
+| Phase 5 | 12 (privacy scan) | 1457 |
+| Phase 6 | 8 (integration + E2E) | 1465 |
+| **Total** | **68 new tests** | **~1465** |
+
+## Risk Mitigations
+
+| Risk | Mitigation |
+|------|-----------|
+| Error loop false positives | Conservative threshold (3+ repeats). Show fingerprint so user can judge. |
+| Codex format changes | Pin to documented event types. Graceful skip for unknown types. |
+| Only 2 adapters have full data | Command output clearly states "Full analysis: claude-code, codex. Basic: others." |
+| Scope creep toward observability | Hard boundary: we read files, we don't instrument code. No SDK, no server. |
+| Breaking existing distill/score | All ConversationTurn changes are additive (new fields with defaults). |
+
+## Success Criteria
+
+1. `reprompt agent` works on real Claude Code sessions with zero config
+2. Error loops detected in >=1 real session (validate with author's own sessions)
+3. Codex adapter discovers and parses real Codex sessions
+4. All tests pass, CI green, no regressions in existing commands
+5. `reprompt privacy --deep` finds at least home paths in real data