agent-recorder 0.1.0__py3-none-any.whl

agent_flight_recorder/adapters/claude.py

@@ -0,0 +1,139 @@
+import json
+import uuid
+from pathlib import Path
+from typing import Iterator
+from ..models import ParsedSession, Run, ToolCall, ShellCommand, FileEvent, Error
+from ..redactor import redact, redact_json
+
+CLAUDE_DIR = Path.home() / ".claude" / "projects"
+
+_FILE_TOOL_MAP = {
+    "Read": "read", "Write": "write", "Edit": "patch",
+    "MultiEdit": "patch", "Glob": "read", "Grep": "read", "Delete": "delete",
+}
+
+
+def parse_session_file(path: Path) -> ParsedSession:
+    path = Path(path)
+    run_id = path.stem
+    lines = [json.loads(l) for l in path.read_text(encoding="utf-8").splitlines() if l.strip()]
+
+    project_path = path.parent.name
+    user_goal = final_summary = started_at = ended_at = ""
+    tokens_in = tokens_out = cache_read = cache_write = 0
+    tool_calls: list[ToolCall] = []
+    shell_commands: list[ShellCommand] = []
+    files: list[FileEvent] = []
+    errors: list[Error] = []
+    pending: dict[str, dict] = {}   # tool_use_id -> tc_data
+    pending_bash: dict[str, ShellCommand] = {}  # tool_use_id -> ShellCommand
+
+    for line in lines:
+        ts = line.get("timestamp", "")
+        if not started_at and ts:
+            started_at = ts
+        if ts:
+            ended_at = ts
+
+        msg_type = line.get("type", "")
+        message = line.get("message", {})
+        content = message.get("content", [])
+        if not isinstance(content, list):
+            content = []
+
+        if msg_type == "user":
+            for block in content:
+                if not isinstance(block, dict):
+                    continue
+                if block.get("type") == "text" and not user_goal:
+                    user_goal = redact(block.get("text", "")[:500])
+                elif block.get("type") == "tool_result":
+                    tu_id = block.get("tool_use_id", "")
+                    is_error = block.get("is_error", False)
+                    raw_output = block.get("content", "")
+                    if isinstance(raw_output, list):
+                        raw_output = " ".join(b.get("text", "") for b in raw_output if isinstance(b, dict))
+                    output = redact(str(raw_output)[:500])
+
+                    if tu_id in pending:
+                        tc_data = pending.pop(tu_id)
+                        tc_data["output_summary"] = output
+                        tc_data["status"] = "error" if is_error else "success"
+                        tool_calls.append(ToolCall(**tc_data))
+
+                        if tu_id in pending_bash:
+                            sc = pending_bash.pop(tu_id)
+                            sc.exit_code = 1 if is_error else 0
+                            if is_error:
+                                sc.stderr_excerpt = output
+                            else:
+                                sc.stdout_excerpt = output
+                            shell_commands.append(sc)
+
+                        if is_error:
+                            errors.append(Error(
+                                id=str(uuid.uuid4()), run_id=run_id, source="tool",
+                                message=output[:300], raw_json=redact_json(block), timestamp=ts,
+                            ))
+
+        elif msg_type == "assistant":
+            usage = message.get("usage", {})
+            tokens_in += usage.get("input_tokens", 0)
+            tokens_out += usage.get("output_tokens", 0)
+            cache_read += usage.get("cache_read_input_tokens", 0)
+            cache_write += usage.get("cache_creation_input_tokens", 0)
+
+            for block in content:
+                if not isinstance(block, dict):
+                    continue
+                if block.get("type") == "text":
+                    txt = block.get("text", "").strip()
+                    if txt:
+                        final_summary = redact(txt[:500])
+                elif block.get("type") == "tool_use":
+                    tu_id = block.get("id", str(uuid.uuid4()))
+                    tool_name = block.get("name", "Unknown")
+                    inp = block.get("input", {})
+                    tc_data = {
+                        "id": str(uuid.uuid4()), "run_id": run_id, "tool_name": tool_name,
+                        "input_summary": redact(json.dumps(inp)[:300]),
+                        "output_summary": "", "status": "success",
+                        "duration_ms": None, "timestamp": ts, "raw_json": redact_json(block),
+                    }
+                    pending[tu_id] = tc_data
+
+                    if tool_name == "Bash":
+                        pending_bash[tu_id] = ShellCommand(
+                            id=str(uuid.uuid4()), run_id=run_id,
+                            command=redact(inp.get("command", "")[:500]), timestamp=ts,
+                        )
+
+                    if tool_name in _FILE_TOOL_MAP:
+                        fpath = inp.get("file_path") or inp.get("path") or inp.get("pattern") or ""
+                        if fpath:
+                            files.append(FileEvent(
+                                id=str(uuid.uuid4()), run_id=run_id,
+                                path=str(fpath), action=_FILE_TOOL_MAP[tool_name],
+                            ))
+
+    for tu_id, tc_data in pending.items():
+        tool_calls.append(ToolCall(**tc_data))
+        if tu_id in pending_bash:
+            shell_commands.append(pending_bash[tu_id])
+
+    return ParsedSession(
+        run=Run(id=run_id, source="claude", project_path=project_path,
+                started_at=started_at, ended_at=ended_at, user_goal=user_goal,
+                final_summary=final_summary, tokens_in=tokens_in, tokens_out=tokens_out,
+                cache_read=cache_read, cache_write=cache_write),
+        tool_calls=tool_calls, shell_commands=shell_commands, files=files, errors=errors,
+    )
+
+
+def iter_sessions(claude_dir: Path = CLAUDE_DIR) -> Iterator[Path]:
+    claude_dir = Path(claude_dir)
+    if not claude_dir.exists():
+        return
+    for project_dir in claude_dir.iterdir():
+        if project_dir.is_dir():
+            yield from project_dir.glob("*.jsonl")

agent_flight_recorder/adapters/codex.py

@@ -0,0 +1,139 @@
+import json
+import uuid
+from pathlib import Path
+from typing import Iterator
+from ..models import ParsedSession, Run, ToolCall, ShellCommand, FileEvent, Error
+from ..redactor import redact, redact_json
+
+CODEX_DIR = Path.home() / ".codex" / "sessions"
+
+_TOOL_NAME_MAP = {
+    "exec_command": "Bash", "apply_patch": "Edit", "read_file": "Read",
+    "write_file": "Write", "delete_file": "Delete", "list_directory": "Glob",
+}
+_FILE_TOOL_ACTIONS = {
+    "Read": "read", "Write": "write", "Edit": "patch", "Delete": "delete", "Glob": "read",
+}
+
+
+def parse_session_file(path: Path) -> ParsedSession:
+    path = Path(path)
+    lines = [json.loads(l) for l in path.read_text(encoding="utf-8").splitlines() if l.strip()]
+
+    session_id = path.stem
+    project_path = user_goal = final_summary = started_at = ended_at = ""
+    tokens_in = tokens_out = 0
+    tool_calls: list[ToolCall] = []
+    shell_commands: list[ShellCommand] = []
+    files: list[FileEvent] = []
+    errors: list[Error] = []
+    pending: dict[str, dict] = {}
+
+    for line in lines:
+        ts = line.get("timestamp", "")
+        if not started_at and ts:
+            started_at = ts
+        if ts:
+            ended_at = ts
+
+        event_type = line.get("type", "")
+
+        if event_type == "session_meta":
+            session_id = line.get("session_id", session_id)
+            project_path = line.get("project_path", "")
+
+        elif event_type == "message":
+            role = line.get("role", "")
+            content = line.get("content", "")
+            if role == "user" and not user_goal:
+                user_goal = redact(str(content)[:500])
+            elif role == "assistant":
+                final_summary = redact(str(content)[:500])
+
+        elif event_type == "response_item:function_call":
+            call_id = line.get("call_id", str(uuid.uuid4()))
+            raw_name = line.get("name", "")
+            tool_name = _TOOL_NAME_MAP.get(raw_name, raw_name.capitalize() or "Unknown")
+            args = line.get("arguments", {})
+            if isinstance(args, str):
+                try:
+                    args = json.loads(args)
+                except Exception:
+                    args = {"raw": args}
+            inp_summary = redact(json.dumps(args)[:300])
+            pending[call_id] = {
+                "id": str(uuid.uuid4()), "run_id": session_id, "tool_name": tool_name,
+                "input_summary": inp_summary, "output_summary": "", "status": "success",
+                "duration_ms": None, "timestamp": ts, "raw_json": redact_json(line),
+                "_raw_name": raw_name, "_args": args,
+            }
+            if raw_name == "exec_command":
+                pending[call_id]["_shell"] = ShellCommand(
+                    id=str(uuid.uuid4()), run_id=session_id,
+                    command=redact(args.get("command", "")[:500]), timestamp=ts,
+                )
+
+        elif event_type == "function_call_output":
+            call_id = line.get("call_id", "")
+            output = redact(str(line.get("output", ""))[:500])
+            exit_code = line.get("exit_code")
+            is_error = exit_code is not None and exit_code != 0
+
+            if call_id in pending:
+                data = pending.pop(call_id)
+                data["output_summary"] = output
+                data["status"] = "error" if is_error else "success"
+                tool_name = data["tool_name"]
+                args = data.pop("_args", {})
+                sc = data.pop("_shell", None)
+                data.pop("_raw_name", None)
+
+                tool_calls.append(ToolCall(**data))
+
+                if sc is not None:
+                    sc.exit_code = exit_code
+                    if is_error:
+                        sc.stderr_excerpt = output
+                    else:
+                        sc.stdout_excerpt = output
+                    shell_commands.append(sc)
+
+                if is_error:
+                    errors.append(Error(
+                        id=str(uuid.uuid4()), run_id=session_id, source="tool",
+                        message=output[:300], raw_json=redact_json(line), timestamp=ts,
+                    ))
+
+                if tool_name in _FILE_TOOL_ACTIONS:
+                    fpath = args.get("path") or args.get("file_path") or ""
+                    if fpath:
+                        files.append(FileEvent(
+                            id=str(uuid.uuid4()), run_id=session_id,
+                            path=str(fpath), action=_FILE_TOOL_ACTIONS[tool_name],
+                        ))
+
+        elif event_type == "token_count":
+            tokens_in += line.get("input_tokens", 0)
+            tokens_out += line.get("output_tokens", 0)
+
+    for data in pending.values():
+        sc = data.pop("_shell", None)
+        data.pop("_raw_name", None)
+        data.pop("_args", None)
+        tool_calls.append(ToolCall(**data))
+        if sc is not None:
+            shell_commands.append(sc)
+
+    return ParsedSession(
+        run=Run(id=session_id, source="codex", project_path=project_path,
+                started_at=started_at, ended_at=ended_at, user_goal=user_goal,
+                final_summary=final_summary, tokens_in=tokens_in, tokens_out=tokens_out),
+        tool_calls=tool_calls, shell_commands=shell_commands, files=files, errors=errors,
+    )
+
+
+def iter_sessions(codex_dir: Path = CODEX_DIR) -> Iterator[Path]:
+    codex_dir = Path(codex_dir)
+    if not codex_dir.exists():
+        return
+    yield from codex_dir.rglob("*.jsonl")

agent_flight_recorder/analyzers/skill_extractor.py

@@ -0,0 +1,120 @@
+import sqlite3
+from pathlib import Path
+from rapidfuzz import fuzz
+
+_STOPWORDS = {"the", "a", "an", "to", "for", "and", "or", "in", "of", "with", "on", "is", "it", "fix", "debug"}
+
+
+def _keywords(text: str) -> set[str]:
+    return {w.lower() for w in text.split() if w.lower() not in _STOPWORDS and len(w) > 2}
+
+
+def cluster_runs(conn: sqlite3.Connection, min_runs: int = 3) -> list[dict]:
+    runs = conn.execute("SELECT id, user_goal, outcome FROM runs").fetchall()
+    assigned: set[str] = set()
+    clusters = []
+
+    for i, r1 in enumerate(runs):
+        if r1["id"] in assigned:
+            continue
+        cluster = [r1]
+        kw1 = _keywords(r1["user_goal"])
+
+        for j, r2 in enumerate(runs):
+            if i == j or r2["id"] in assigned:
+                continue
+            kw2 = _keywords(r2["user_goal"])
+            if kw1 and kw2:
+                overlap = len(kw1 & kw2) / max(len(kw1), len(kw2))
+            else:
+                overlap = 0.0
+            fuzzy = fuzz.partial_ratio(r1["user_goal"], r2["user_goal"])
+            if overlap >= 0.3 or fuzzy >= 70:
+                cluster.append(r2)
+
+        if len(cluster) < min_runs:
+            continue
+
+        for r in cluster:
+            assigned.add(r["id"])
+
+        run_ids = [r["id"] for r in cluster]
+        ph = ",".join("?" * len(run_ids))
+        top_tools = conn.execute(
+            f"SELECT tool_name, COUNT(*) as cnt FROM tool_calls WHERE run_id IN ({ph}) GROUP BY tool_name ORDER BY cnt DESC LIMIT 5",
+            run_ids,
+        ).fetchall()
+        error_count = conn.execute(
+            f"SELECT COUNT(*) FROM errors WHERE run_id IN ({ph})", run_ids
+        ).fetchone()[0]
+
+        kws = sorted(_keywords(cluster[0]["user_goal"]))[:3]
+        category = "-".join(kws) if kws else "general"
+        has_success = any(r["outcome"] == "shipped" for r in cluster)
+
+        clusters.append({
+            "category": category,
+            "run_count": len(cluster),
+            "run_ids": run_ids,
+            "has_success": has_success,
+            "top_tools": [(r["tool_name"], r["cnt"]) for r in top_tools],
+            "error_count": error_count,
+            "sample_goal": cluster[0]["user_goal"],
+        })
+
+    return clusters
+
+
+def generate_skill_md(category: str, cluster: dict, conn: sqlite3.Connection) -> str:
+    tools_str = ", ".join(f"{n} ({c}×)" for n, c in cluster["top_tools"])
+    shipped = [
+        rid for rid in cluster["run_ids"]
+        if conn.execute("SELECT outcome FROM runs WHERE id=?", (rid,)).fetchone()["outcome"] == "shipped"
+    ]
+    pattern_lines = []
+    if shipped:
+        cmds = conn.execute(
+            "SELECT command FROM shell_commands WHERE run_id=? ORDER BY timestamp LIMIT 10",
+            (shipped[0],),
+        ).fetchall()
+        pattern_lines = [f"  {i + 1}. `{r['command']}`" for i, r in enumerate(cmds)]
+    pattern = "\n".join(pattern_lines) if pattern_lines else "  (no shell commands recorded)"
+    return f"""# {category}
+
+## Problem
+{cluster['sample_goal']}
+
+## Evidence
+- Seen in {cluster['run_count']} sessions
+- Top tools: {tools_str}
+- Errors across sessions: {cluster['error_count']}
+
+## Successful Pattern
+{pattern}
+
+## Notes
+Generated by `afr extract-skills`. Review before using as an agent skill.
+"""
+
+
+def run_extraction(conn: sqlite3.Connection, min_runs: int = 3) -> None:
+    from rich.console import Console
+    from rich.prompt import Confirm
+
+    console = Console()
+    clusters = [c for c in cluster_runs(conn, min_runs) if c["has_success"]]
+
+    if not clusters:
+        console.print(f"[yellow]No clusters with {min_runs}+ runs and a shipped outcome found.[/yellow]")
+        console.print("[dim]Tip: tag sessions with `afr tag <id> shipped` first.[/dim]")
+        return
+
+    for cluster in clusters:
+        console.print(f"\n[bold cyan]Candidate:[/bold cyan] {cluster['category']}")
+        console.print(f"  {cluster['run_count']} sessions | tools: {', '.join(t for t, _ in cluster['top_tools'])} | errors: {cluster['error_count']}")
+        if Confirm.ask("  Generate SKILL.md?"):
+            content = generate_skill_md(cluster["category"], cluster, conn)
+            out = Path("generated_skills") / cluster["category"]
+            out.mkdir(parents=True, exist_ok=True)
+            (out / "SKILL.md").write_text(content, encoding="utf-8")
+            console.print(f"  [green]Written → {out / 'SKILL.md'}[/green]")

agent_flight_recorder/analyzers/stats.py

@@ -0,0 +1,45 @@
+import sqlite3
+from typing import Optional
+
+
+def get_stats(conn: sqlite3.Connection, days: Optional[int] = None) -> dict:
+    where, params = "", []
+    if days:
+        where = "WHERE started_at >= datetime('now', ?)"
+        params = [f'-{days} days']
+
+    runs = conn.execute(f"SELECT * FROM runs {where}", params).fetchall()
+    if not runs:
+        return {}
+
+    outcomes: dict[str, int] = {}
+    for r in runs:
+        outcomes[r["outcome"]] = outcomes.get(r["outcome"], 0) + 1
+
+    run_ids = [r["id"] for r in runs]
+    ph = ",".join("?" * len(run_ids))
+
+    top_tools = conn.execute(
+        f"SELECT tool_name, COUNT(*) as cnt FROM tool_calls WHERE run_id IN ({ph}) GROUP BY tool_name ORDER BY cnt DESC LIMIT 10",
+        run_ids,
+    ).fetchall()
+
+    error_count = conn.execute(
+        f"SELECT COUNT(*) FROM errors WHERE run_id IN ({ph})", run_ids
+    ).fetchone()[0]
+
+    shell_failures = conn.execute(
+        f"SELECT COUNT(*) FROM shell_commands WHERE run_id IN ({ph}) AND exit_code IS NOT NULL AND exit_code != 0",
+        run_ids,
+    ).fetchone()[0]
+
+    return {
+        "total_runs": len(runs),
+        "outcomes": outcomes,
+        "total_cost_usd": sum(r["cost_usd"] for r in runs),
+        "total_tokens_in": sum(r["tokens_in"] for r in runs),
+        "total_tokens_out": sum(r["tokens_out"] for r in runs),
+        "top_tools": [(r["tool_name"], r["cnt"]) for r in top_tools],
+        "error_count": error_count,
+        "shell_failures": shell_failures,
+    }

agent_flight_recorder/cli.py

@@ -0,0 +1,117 @@
+import sys
+if sys.platform == "win32":
+    import ctypes
+    ctypes.windll.kernel32.SetConsoleOutputCP(65001)
+    sys.stdout.reconfigure(encoding="utf-8")
+    sys.stderr.reconfigure(encoding="utf-8")
+
+from typing import Optional
+import typer
+from .db import get_connection, init_db, DB_PATH, list_runs, get_run, get_run_events, search_runs, set_outcome
+from .ingester import ingest_claude, ingest_codex
+from .analyzers.stats import get_stats
+from .analyzers.skill_extractor import run_extraction
+from .render.terminal import console, print_run_list, print_run_detail, print_stats
+
+app = typer.Typer(name="afr", help="Agent Flight Recorder — local AI session observability", add_completion=False)
+
+_VALID_OUTCOMES = {"shipped", "blocked", "abandoned", "exploratory"}
+
+
+@app.command()
+def ingest(source: str = typer.Argument(..., help="claude or codex")):
+    """Ingest sessions from Claude Code or Codex."""
+    if source == "claude":
+        new, skipped = ingest_claude()
+    elif source == "codex":
+        new, skipped = ingest_codex()
+    else:
+        console.print(f"[red]Unknown source '{source}'. Use 'claude' or 'codex'.[/red]")
+        raise typer.Exit(1)
+    console.print(f"[green]Done.[/green] {new} new, {skipped} skipped.")
+
+
+@app.command("list")
+def list_cmd(days: Optional[int] = typer.Option(None, "--days", "-d", help="Last N days")):
+    """List all recorded runs."""
+    conn = get_connection()
+    init_db(conn)
+    runs = list_runs(conn, days)
+    conn.close()
+    if not runs:
+        console.print("[yellow]No runs. Try `afr ingest claude`.[/yellow]")
+    else:
+        print_run_list(runs)
+
+
+@app.command()
+def show(run_id: str = typer.Argument(..., help="Run ID or prefix")):
+    """Show full detail for a run."""
+    conn = get_connection()
+    init_db(conn)
+    row = conn.execute("SELECT * FROM runs WHERE id LIKE ?", (f"{run_id}%",)).fetchone()
+    if not row:
+        console.print(f"[red]Run not found: {run_id}[/red]")
+        conn.close()
+        raise typer.Exit(1)
+    events = get_run_events(conn, row["id"])
+    conn.close()
+    print_run_detail(row, events)
+
+
+@app.command()
+def search(
+    query: str = typer.Argument(..., help="Search query"),
+    days: Optional[int] = typer.Option(None, "--days", "-d"),
+):
+    """Full-text search across run goals and summaries."""
+    conn = get_connection()
+    init_db(conn)
+    runs = search_runs(conn, query, days)
+    conn.close()
+    if not runs:
+        console.print(f"[yellow]No results for: {query}[/yellow]")
+    else:
+        print_run_list(runs)
+
+
+@app.command()
+def stats(days: Optional[int] = typer.Option(None, "--days", "-d")):
+    """Show session statistics."""
+    conn = get_connection()
+    init_db(conn)
+    s = get_stats(conn, days)
+    conn.close()
+    print_stats(s)
+
+
+@app.command()
+def tag(
+    run_id: str = typer.Argument(...),
+    outcome: str = typer.Argument(..., help="shipped | blocked | abandoned | exploratory"),
+):
+    """Tag a run with an outcome."""
+    if outcome not in _VALID_OUTCOMES:
+        console.print(f"[red]Invalid outcome. Choose: {', '.join(sorted(_VALID_OUTCOMES))}[/red]")
+        raise typer.Exit(1)
+    conn = get_connection()
+    init_db(conn)
+    row = conn.execute("SELECT id FROM runs WHERE id LIKE ?", (f"{run_id}%",)).fetchone()
+    if not row:
+        console.print(f"[red]Run not found: {run_id}[/red]")
+        conn.close()
+        raise typer.Exit(1)
+    set_outcome(conn, row["id"], outcome)
+    conn.close()
+    console.print(f"[green]Tagged {row['id'][:8]} as {outcome}.[/green]")
+
+
+@app.command("extract-skills")
+def extract_skills(
+    min_runs: int = typer.Option(3, "--min-runs", help="Minimum sessions per cluster"),
+):
+    """Cluster sessions and propose SKILL.md candidates."""
+    conn = get_connection()
+    init_db(conn)
+    run_extraction(conn, min_runs)
+    conn.close()

agent_flight_recorder/db.py

@@ -0,0 +1,163 @@
+import sqlite3
+from pathlib import Path
+from typing import Optional
+from .models import ParsedSession
+
+DB_PATH = Path.home() / ".afr" / "afr.db"
+
+
+def get_connection(path: Path = DB_PATH) -> sqlite3.Connection:
+    path = Path(path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    conn = sqlite3.connect(str(path))
+    conn.row_factory = sqlite3.Row
+    conn.execute("PRAGMA journal_mode=WAL")
+    conn.execute("PRAGMA foreign_keys=ON")
+    return conn
+
+
+def init_db(conn: sqlite3.Connection) -> None:
+    conn.executescript("""
+        CREATE TABLE IF NOT EXISTS runs (
+            id TEXT PRIMARY KEY,
+            source TEXT NOT NULL,
+            project_path TEXT DEFAULT '',
+            started_at TEXT DEFAULT '',
+            ended_at TEXT DEFAULT '',
+            user_goal TEXT DEFAULT '',
+            final_summary TEXT DEFAULT '',
+            outcome TEXT DEFAULT 'untagged',
+            cost_usd REAL DEFAULT 0.0,
+            tokens_in INTEGER DEFAULT 0,
+            tokens_out INTEGER DEFAULT 0,
+            cache_read INTEGER DEFAULT 0,
+            cache_write INTEGER DEFAULT 0
+        );
+        CREATE TABLE IF NOT EXISTS tool_calls (
+            id TEXT,
+            run_id TEXT NOT NULL REFERENCES runs(id),
+            tool_name TEXT DEFAULT '',
+            input_summary TEXT DEFAULT '',
+            output_summary TEXT DEFAULT '',
+            status TEXT DEFAULT 'success',
+            duration_ms INTEGER,
+            timestamp TEXT DEFAULT '',
+            raw_json TEXT DEFAULT '',
+            PRIMARY KEY (run_id, id)
+        );
+        CREATE TABLE IF NOT EXISTS shell_commands (
+            id TEXT,
+            run_id TEXT NOT NULL REFERENCES runs(id),
+            command TEXT DEFAULT '',
+            exit_code INTEGER,
+            duration_ms INTEGER,
+            stdout_excerpt TEXT DEFAULT '',
+            stderr_excerpt TEXT DEFAULT '',
+            timestamp TEXT DEFAULT '',
+            PRIMARY KEY (run_id, id)
+        );
+        CREATE TABLE IF NOT EXISTS files (
+            id TEXT,
+            run_id TEXT NOT NULL REFERENCES runs(id),
+            path TEXT DEFAULT '',
+            action TEXT DEFAULT '',
+            PRIMARY KEY (run_id, id)
+        );
+        CREATE TABLE IF NOT EXISTS errors (
+            id TEXT,
+            run_id TEXT NOT NULL REFERENCES runs(id),
+            source TEXT DEFAULT '',
+            message TEXT DEFAULT '',
+            raw_json TEXT DEFAULT '',
+            timestamp TEXT DEFAULT '',
+            PRIMARY KEY (run_id, id)
+        );
+        CREATE TABLE IF NOT EXISTS lessons (
+            id TEXT PRIMARY KEY,
+            run_id TEXT NOT NULL REFERENCES runs(id),
+            lesson TEXT DEFAULT '',
+            category TEXT DEFAULT '',
+            confidence REAL DEFAULT 0.0,
+            approved INTEGER DEFAULT 0
+        );
+        CREATE VIRTUAL TABLE IF NOT EXISTS runs_fts USING fts5(
+            id UNINDEXED,
+            user_goal,
+            final_summary,
+            content='runs',
+            content_rowid='rowid'
+        );
+        CREATE TRIGGER IF NOT EXISTS runs_ai AFTER INSERT ON runs BEGIN
+            INSERT INTO runs_fts(rowid, id, user_goal, final_summary)
+            VALUES (new.rowid, new.id, new.user_goal, new.final_summary);
+        END;
+    """)
+    conn.commit()
+
+
+def upsert_session(conn: sqlite3.Connection, session: ParsedSession) -> bool:
+    existing = conn.execute("SELECT id FROM runs WHERE id = ?", (session.run.id,)).fetchone()
+    if existing:
+        return False
+    r = session.run
+    conn.execute(
+        "INSERT INTO runs VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?)",
+        (r.id, r.source, r.project_path, r.started_at, r.ended_at, r.user_goal,
+         r.final_summary, r.outcome, r.cost_usd, r.tokens_in, r.tokens_out, r.cache_read, r.cache_write)
+    )
+    for tc in session.tool_calls:
+        conn.execute(
+            "INSERT INTO tool_calls VALUES (?,?,?,?,?,?,?,?,?)",
+            (tc.id, tc.run_id, tc.tool_name, tc.input_summary, tc.output_summary,
+             tc.status, tc.duration_ms, tc.timestamp, tc.raw_json)
+        )
+    for sc in session.shell_commands:
+        conn.execute(
+            "INSERT INTO shell_commands VALUES (?,?,?,?,?,?,?,?)",
+            (sc.id, sc.run_id, sc.command, sc.exit_code, sc.duration_ms,
+             sc.stdout_excerpt, sc.stderr_excerpt, sc.timestamp)
+        )
+    for fe in session.files:
+        conn.execute("INSERT INTO files VALUES (?,?,?,?)", (fe.id, fe.run_id, fe.path, fe.action))
+    for err in session.errors:
+        conn.execute(
+            "INSERT INTO errors VALUES (?,?,?,?,?,?)",
+            (err.id, err.run_id, err.source, err.message, err.raw_json, err.timestamp)
+        )
+    conn.commit()
+    return True
+
+
+def list_runs(conn: sqlite3.Connection, days: Optional[int] = None) -> list:
+    sql, params = "SELECT * FROM runs", []
+    if days:
+        sql += " WHERE started_at >= datetime('now', ?)"
+        params = [f'-{days} days']
+    return conn.execute(sql + " ORDER BY started_at DESC", params).fetchall()
+
+
+def search_runs(conn: sqlite3.Connection, query: str, days: Optional[int] = None) -> list:
+    sql = "SELECT runs.* FROM runs_fts JOIN runs ON runs_fts.id = runs.id WHERE runs_fts MATCH ?"
+    params: list = [query]
+    if days:
+        sql += " AND runs.started_at >= datetime('now', ?)"
+        params.append(f'-{days} days')
+    return conn.execute(sql, params).fetchall()
+
+
+def get_run(conn: sqlite3.Connection, run_id: str):
+    return conn.execute("SELECT * FROM runs WHERE id LIKE ?", (f"{run_id}%",)).fetchone()
+
+
+def get_run_events(conn: sqlite3.Connection, run_id: str) -> dict:
+    return {
+        "tool_calls": conn.execute("SELECT * FROM tool_calls WHERE run_id=? ORDER BY timestamp", (run_id,)).fetchall(),
+        "shell_commands": conn.execute("SELECT * FROM shell_commands WHERE run_id=? ORDER BY timestamp", (run_id,)).fetchall(),
+        "files": conn.execute("SELECT * FROM files WHERE run_id=?", (run_id,)).fetchall(),
+        "errors": conn.execute("SELECT * FROM errors WHERE run_id=? ORDER BY timestamp", (run_id,)).fetchall(),
+    }
+
+
+def set_outcome(conn: sqlite3.Connection, run_id: str, outcome: str) -> None:
+    conn.execute("UPDATE runs SET outcome=? WHERE id=?", (outcome, run_id))
+    conn.commit()

agent_flight_recorder/ingester.py

@@ -0,0 +1,42 @@
+from pathlib import Path
+from typing import Literal
+import sqlite3
+from .db import get_connection, init_db, upsert_session, DB_PATH
+from .adapters import claude, codex
+
+
+def ingest_from_paths(
+    paths: list[Path],
+    source: Literal["claude", "codex"],
+    conn: sqlite3.Connection,
+) -> tuple[int, int]:
+    new, skipped = 0, 0
+    parser = claude.parse_session_file if source == "claude" else codex.parse_session_file
+    for p in paths:
+        try:
+            session = parser(Path(p))
+            if upsert_session(conn, session):
+                new += 1
+            else:
+                skipped += 1
+        except Exception:
+            skipped += 1
+    return new, skipped
+
+
+def ingest_claude(db_path: Path = DB_PATH) -> tuple[int, int]:
+    conn = get_connection(db_path)
+    init_db(conn)
+    paths = list(claude.iter_sessions())
+    result = ingest_from_paths(paths, "claude", conn)
+    conn.close()
+    return result
+
+
+def ingest_codex(db_path: Path = DB_PATH) -> tuple[int, int]:
+    conn = get_connection(db_path)
+    init_db(conn)
+    paths = list(codex.iter_sessions())
+    result = ingest_from_paths(paths, "codex", conn)
+    conn.close()
+    return result

agent_flight_recorder/models.py

@@ -0,0 +1,65 @@
+from pydantic import BaseModel
+from typing import Literal, Optional
+
+
+class ToolCall(BaseModel):
+    id: str
+    run_id: str
+    tool_name: str = "Unknown"
+    input_summary: str = ""
+    output_summary: str = ""
+    status: Literal["success", "error"] = "success"
+    duration_ms: Optional[int] = None
+    timestamp: str = ""
+    raw_json: str = ""
+
+
+class ShellCommand(BaseModel):
+    id: str
+    run_id: str
+    command: str = ""
+    exit_code: Optional[int] = None
+    duration_ms: Optional[int] = None
+    stdout_excerpt: str = ""
+    stderr_excerpt: str = ""
+    timestamp: str = ""
+
+
+class FileEvent(BaseModel):
+    id: str
+    run_id: str
+    path: str = ""
+    action: Literal["read", "write", "patch", "delete"]
+
+
+class Error(BaseModel):
+    id: str
+    run_id: str
+    source: Literal["tool", "shell", "agent"]
+    message: str = ""
+    raw_json: str = ""
+    timestamp: str = ""
+
+
+class Run(BaseModel):
+    id: str
+    source: Literal["claude", "codex"]
+    project_path: str = ""
+    started_at: str = ""
+    ended_at: str = ""
+    user_goal: str = ""
+    final_summary: str = ""
+    outcome: str = "untagged"
+    cost_usd: float = 0.0
+    tokens_in: int = 0
+    tokens_out: int = 0
+    cache_read: int = 0
+    cache_write: int = 0
+
+
+class ParsedSession(BaseModel):
+    run: Run
+    tool_calls: list[ToolCall] = []
+    shell_commands: list[ShellCommand] = []
+    files: list[FileEvent] = []
+    errors: list[Error] = []

agent_flight_recorder/redactor.py

@@ -0,0 +1,20 @@
+import re
+import json
+
+_PATTERNS = [
+    re.compile(r'(?i)(api[_-]?key|secret|password|token)\s*[:=]\s*\S+'),
+    re.compile(r'sk-[a-zA-Z0-9-]{12,}'),
+    re.compile(r'ghp_[a-zA-Z0-9]{20,}'),
+    re.compile(r'(?i)bearer\s+[a-zA-Z0-9\-._~+/]+=*'),
+    re.compile(r'-----BEGIN [A-Z ]+ KEY-----[\s\S]*?-----END [A-Z ]+ KEY-----', re.DOTALL),
+]
+
+
+def redact(text: str) -> str:
+    for pattern in _PATTERNS:
+        text = pattern.sub('[REDACTED]', text)
+    return text
+
+
+def redact_json(obj: dict) -> str:
+    return redact(json.dumps(obj))

agent_flight_recorder/render/terminal.py

@@ -0,0 +1,88 @@
+import sqlite3
+from rich.console import Console
+from rich.table import Table
+from rich.panel import Panel
+
+console = Console()
+
+_OUTCOME_COLORS = {
+    "shipped": "green", "blocked": "red",
+    "abandoned": "yellow", "exploratory": "blue", "untagged": "dim",
+}
+
+
+def _fmt_tokens(n: int) -> str:
+    if n >= 1_000_000:
+        return f"{n/1_000_000:.1f}M"
+    if n >= 1_000:
+        return f"{n/1_000:.1f}K"
+    return str(n)
+
+
+def print_run_list(runs: list) -> None:
+    table = Table(show_header=True, header_style="bold magenta")
+    table.add_column("ID", style="dim", no_wrap=True, min_width=8)
+    table.add_column("Source", no_wrap=True, min_width=6)
+    table.add_column("Goal", min_width=30)
+    table.add_column("Outcome", no_wrap=True, min_width=11)
+    table.add_column("In", justify="right", no_wrap=True, min_width=6)
+    table.add_column("Out", justify="right", no_wrap=True, min_width=7)
+    table.add_column("Date", no_wrap=True, min_width=13)
+    for r in runs:
+        color = _OUTCOME_COLORS.get(r["outcome"], "dim")
+        goal = r["user_goal"] or ""
+        goal_cell = goal[:40] + ".." if len(goal) > 42 else goal
+        table.add_row(
+            r["id"][:8],
+            r["source"],
+            goal_cell,
+            f"[{color}]{r['outcome']}[/{color}]",
+            _fmt_tokens(r["tokens_in"]),
+            _fmt_tokens(r["tokens_out"]),
+            r["started_at"][:16] if r["started_at"] else "",
+        )
+    console.print(table)
+
+
+def print_run_detail(run, events: dict) -> None:
+    console.print(Panel(
+        f"[bold]{run['user_goal']}[/bold]\n"
+        f"[dim]{run['source']} | {run['started_at'][:16]} → {run['ended_at'][:16]} | {run['outcome']}[/dim]"
+    ))
+    if events["tool_calls"]:
+        console.print("\n[bold]Tool Calls[/bold]")
+        for tc in events["tool_calls"]:
+            icon = "[green]✓[/green]" if tc["status"] == "success" else "[red]✗[/red]"
+            console.print(f"  {icon} [cyan]{tc['tool_name']}[/cyan]  {tc['input_summary'][:60]}")
+    if events["shell_commands"]:
+        console.print("\n[bold]Shell Commands[/bold]")
+        for sc in events["shell_commands"]:
+            ec = sc["exit_code"]
+            code_fmt = f"[green]{ec}[/green]" if ec == 0 else f"[red]{ec}[/red]"
+            console.print(f"  [{code_fmt}] [yellow]{sc['command'][:70]}[/yellow]")
+    if events["errors"]:
+        console.print("\n[bold red]Errors[/bold red]")
+        for err in events["errors"]:
+            console.print(f"  [red]•[/red] {err['message'][:80]}")
+    console.print(
+        f"\n[dim]Tokens: {run['tokens_in']} in / {run['tokens_out']} out"
+        f" | Cache read: {run['cache_read']} | Cost: ${run['cost_usd']:.4f}[/dim]"
+    )
+
+
+def print_stats(stats: dict) -> None:
+    if not stats:
+        console.print("[yellow]No runs found. Run `afr ingest claude` first.[/yellow]")
+        return
+    console.print(Panel("[bold]Agent Flight Recorder — Stats[/bold]"))
+    console.print(f"Total runs: [bold]{stats['total_runs']}[/bold]")
+    console.print("\n[bold]Outcomes[/bold]")
+    for outcome, count in stats["outcomes"].items():
+        color = _OUTCOME_COLORS.get(outcome, "dim")
+        console.print(f"  [{color}]{outcome}[/{color}]: {count}")
+    console.print(f"\n[bold]Tokens[/bold]  {stats['total_tokens_in']:,} in / {stats['total_tokens_out']:,} out")
+    console.print(f"[bold]Errors[/bold]  {stats['error_count']} tool | {stats['shell_failures']} shell")
+    if stats["top_tools"]:
+        console.print("\n[bold]Top Tools[/bold]")
+        for tool, count in stats["top_tools"]:
+            console.print(f"  {tool}: {count}")

agent_recorder-0.1.0.dist-info/METADATA

@@ -0,0 +1,237 @@
+Metadata-Version: 2.4
+Name: agent-recorder
+Version: 0.1.0
+Summary: Local-first CLI that records every Claude Code and Codex session into a searchable SQLite database
+Project-URL: Homepage, https://github.com/AravindKurapati/agent-flight-recorder
+Project-URL: Repository, https://github.com/AravindKurapati/agent-flight-recorder
+Project-URL: Issues, https://github.com/AravindKurapati/agent-flight-recorder/issues
+Author-email: Aravind Kurapati <arvind.kurapati@gmail.com>
+License: MIT
+Keywords: agents,ai,claude,cli,codex,devtools,llm,observability,session-recording
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Requires-Dist: pydantic>=2
+Requires-Dist: rapidfuzz>=3
+Requires-Dist: typer[all]>=0.12
+Description-Content-Type: text/markdown
+
+# agent-flight-recorder
+
+> **Every agent session you run disappears the moment it ends. This one doesn't.**
+
+A local-first CLI that records every Claude Code and Codex session — prompts, tool calls, shell commands, file changes, errors, and token costs — into a searchable SQLite database. Find what you worked on, see what failed, and extract reusable workflow patterns.
+
+---
+
+## The problem this solves
+
+AI coding sessions are opaque and ephemeral. When a session ends, all you have is changed files and a vague memory of what the agent tried. There's no way to answer:
+
+- What tools did the agent call, and in what order?
+- Which shell commands failed, and what was the error?
+- How much did that session actually cost in tokens?
+- Why does this same class of problem keep taking 3 sessions to fix?
+
+`afr` records all of that and keeps it queryable — locally, permanently, without sending anything to a server.
+
+---
+
+## Install
+
+```bash
+git clone https://github.com/AravindKurapati/agent-flight-recorder
+cd agent-flight-recorder
+pip install -e .
+```
+
+**Requirements:** Python 3.11+ — no API keys, no accounts, everything stays on your machine.
+
+---
+
+## Usage
+
+### Ingest your sessions
+
+```bash
+afr ingest claude     # reads ~/.claude/projects/**/*.jsonl
+afr ingest codex      # reads ~/.codex/sessions/**/*.jsonl
+```
+
+Or wire a Claude Code hook to ingest automatically after every session (add to `~/.claude/settings.json`):
+
+```json
+{
+  "hooks": {
+    "Stop": [{ "matcher": "", "hooks": [{ "type": "command", "command": "afr ingest claude" }] }]
+  }
+}
+```
+
+### Browse recent runs
+
+```bash
+afr list --days 7
+```
+
+```
+ ID       Source  Goal                                    Outcome    Tokens↑  Date
+ 50c3f2a1 claude  Fix the Modal deployment error          untagged   1,842    2026-05-08
+ 903b12cd claude  Add React component for dashboard       untagged     311    2026-05-08
+ ad7e9f21 claude  Debug the authentication middleware     untagged     250    2026-05-07
+```
+
+### Inspect a session
+
+```bash
+afr show 50c3f2a1
+```
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│ Fix the Modal deployment error                                  │
+│ claude | 2026-05-08 10:00 → 10:14 | untagged                   │
+└─────────────────────────────────────────────────────────────────┘
+
+Tool Calls
+  ✓ Read      {"file_path": "finsight.py"}
+  ✗ Bash      {"command": "modal run finsight.py"}
+  ✓ Edit      {"file_path": "finsight.py"}
+  ✓ Bash      {"command": "modal deploy finsight.py"}
+
+Shell Commands
+  [1] modal run finsight.py
+  [0] modal deploy finsight.py
+
+Errors
+  • Error: missing secret huggingface-secret
+
+Tokens: 1,842 in / 4,201 out | Cache read: 920 | Cost: $0.0000
+```
+
+### Search across all sessions
+
+```bash
+afr search "authentication"
+afr search "modal" --days 30
+```
+
+### See patterns across sessions
+
+```bash
+afr stats --days 30
+```
+
+```
+Total runs: 74
+
+Outcomes
+  shipped: 12
+  blocked: 8
+  untagged: 54
+
+Tokens  126,450 in / 4,091,200 out
+Errors  187 tool | 62 shell
+
+Top Tools
+  Bash: 891
+  Read: 412
+  Edit: 308
+  Write: 201
+  Glob: 94
+  mcp__exa__web_search_exa: 87
+```
+
+### Tag a run with its outcome
+
+```bash
+afr tag 50c3f2a1 shipped
+afr tag 903b12cd blocked
+```
+
+Valid outcomes: `shipped`, `blocked`, `abandoned`, `exploratory`
+
+### Extract reusable workflow skills
+
+After a few sessions solving the same class of problem, run:
+
+```bash
+afr extract-skills --min-runs 3
+```
+
+```
+Candidate: deployment-modal-debug
+  4 sessions | tools: Bash, Read | errors: 6
+  Generate SKILL.md? [y/n]: y
+  Written → generated_skills/deployment-modal-debug/SKILL.md
+```
+
+It clusters sessions by keyword similarity, finds ones that ended in `shipped`, and drafts a `SKILL.md` from the successful tool sequence. You approve before anything is written.
+
+---
+
+## All commands
+
+| Command | What it does |
+|---------|-------------|
+| `afr ingest claude` | Parse `~/.claude/` sessions into the database |
+| `afr ingest codex` | Parse `~/.codex/` sessions into the database |
+| `afr list [--days N]` | Table of recent runs with outcome and token count |
+| `afr show <id>` | Full detail: tool calls, shell commands, errors, cost |
+| `afr search <query>` | Full-text search across run goals and summaries |
+| `afr stats [--days N]` | Outcome distribution, top tools, error counts |
+| `afr tag <id> <outcome>` | Label a run: shipped / blocked / abandoned / exploratory |
+| `afr extract-skills` | Cluster sessions, propose SKILL.md candidates |
+
+`<id>` accepts the first 8 characters from `afr list` output.
+
+---
+
+## What gets recorded
+
+For each session:
+
+- **Goal** — first user message
+- **Tool calls** — every tool fired, input summary, success or error
+- **Shell commands** — command, exit code, stdout/stderr excerpt
+- **File events** — every read, write, patch, or delete
+- **Errors** — failed tool calls and non-zero shell exits
+- **Token counts** — input, output, cache read, cache write
+- **Outcome** — you tag this: `shipped`, `blocked`, `abandoned`, `exploratory`
+
+Secrets are redacted before anything is written to the database (API keys, bearer tokens, private keys, `.env` contents).
+
+---
+
+## How data is stored
+
+Everything lives at `~/.afr/afr.db` — a single SQLite file on your machine. No data leaves your machine. No telemetry. No accounts.
+
+You can query it directly with any SQLite client:
+
+```bash
+sqlite3 ~/.afr/afr.db "SELECT user_goal, outcome, tokens_in FROM runs ORDER BY started_at DESC LIMIT 10"
+```
+
+---
+
+## Supported agents
+
+| Agent | Source | Adapter |
+|-------|--------|---------|
+| Claude Code | `~/.claude/projects/**/*.jsonl` | Full — tool calls, tokens, errors |
+| Codex (OpenAI) | `~/.codex/sessions/**/*.jsonl` | Full — tool name mapping, tokens, errors |
+
+---
+
+## License
+
+MIT

agent_recorder-0.1.0.dist-info/RECORD

@@ -0,0 +1,18 @@
+agent_flight_recorder/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+agent_flight_recorder/cli.py,sha256=RxSqFz5D29paQI1wD4NAb8lrzNtbGj95-ThizD7UqQ8,3950
+agent_flight_recorder/db.py,sha256=Um5YB-fmNyogTmmj4UffvrDRkQk8saAYOZZ6NNo7Vjo,6410
+agent_flight_recorder/ingester.py,sha256=AS-F7FCzY_G9xTWOBo61BCw261_TGL6ZvrLMeL3kijc,1222
+agent_flight_recorder/models.py,sha256=MNEjG5m__3n6TBsnEh1Yu0ojyc3XeQ5ZyiRLEvaVsWU,1498
+agent_flight_recorder/redactor.py,sha256=meF0emcbayNKzgVLlkJ15mwS_TitGkroShXkVJfYqL0,558
+agent_flight_recorder/adapters/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+agent_flight_recorder/adapters/claude.py,sha256=ht6zt8-tKv-JqZom5M2wP0dJZCmp5VM3attT9Qx3MaI,6157
+agent_flight_recorder/adapters/codex.py,sha256=QEganAMGtjOqZtgBZgSyfHy8J5kBg9USTEPefUw8fuc,5601
+agent_flight_recorder/analyzers/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+agent_flight_recorder/analyzers/skill_extractor.py,sha256=5jHY9zkMEIFhVyEToJ6MLKlzZvwQdKKSuV1SSqknQfs,4533
+agent_flight_recorder/analyzers/stats.py,sha256=LG8Q8Hsj-cMV8lMoflnEYvr_3lavlrqdISo2OfZx6XE,1533
+agent_flight_recorder/render/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+agent_flight_recorder/render/terminal.py,sha256=r6xA4QsSQ6FJ2gaX2_grJWtgtQInoY3a8e5YTa3X008,3704
+agent_recorder-0.1.0.dist-info/METADATA,sha256=pttLZbJzbFb7GTHlEOgMx_dqotOgaQoRwjxcd5OKmQw,7247
+agent_recorder-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+agent_recorder-0.1.0.dist-info/entry_points.txt,sha256=m9k2aNb_6qpYetSwInlkpjWUgHGBpHWibVU9JdP9xDs,54
+agent_recorder-0.1.0.dist-info/RECORD,,

agent_recorder-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

agent_recorder-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+afr = agent_flight_recorder.cli:app