@tamng0905/builder-essential-skills 0.1.0

package/skills/orwell-writing/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: orwell-writing
+description: Use when an agent is asked to draft, rewrite, edit, review, polish, copyedit, simplify, humanize, or create written prose, including creative writing, essays, posts, scripts, speeches, emails, documentation, product copy, and other style-sensitive text. Apply George Orwell's six rules from "Politics and the English Language" as a plain-English style discipline while preserving the user's intended meaning, audience, tone, and explicit constraints.
+---
+
+# Orwell Writing
+
+## Overview
+
+Use Orwell's rules as a practical filter for clarity, force, and honesty in English prose. Apply them to both drafting and revision, but do not erase deliberate voice, character, rhythm, humor, or genre when the user clearly wants them.
+
+## Core Rules
+
+Remember these rules from "Politics and the English Language":
+
+1. Never use a metaphor, simile, or other figure of speech which you are used to seeing in print.
+2. Never use a long word where a short one will do.
+3. If it is possible to cut a word out, always cut it out.
+4. Never use the passive where you can use the active.
+5. Never use a foreign phrase, a scientific word, or a jargon word if you can think of an everyday English equivalent.
+6. Break any of these rules sooner than say anything outright barbarous.
+
+## Workflow
+
+When writing from scratch:
+
+1. Identify the audience, purpose, and promised tone from the user's request.
+2. Draft in concrete, direct English.
+3. Remove stock phrases, dead metaphors, filler, pompous diction, needless abstraction, and avoidable jargon.
+4. Prefer active verbs and clear subjects unless passive voice better serves emphasis, tact, suspense, or technical accuracy.
+5. Keep necessary nuance; do not make prose crude, false, or flat just to make it short.
+
+When revising existing text:
+
+1. Preserve the user's meaning and any explicit tone or format constraints.
+2. Cut words, clauses, and sentences that do no work.
+3. Replace stale figures of speech with plain phrasing or a fresh, specific image.
+4. Replace long, foreign, scientific, or jargon terms with everyday English when accuracy permits.
+5. Convert passive constructions to active ones when the actor matters and is known.
+6. Flag any remaining jargon, passive voice, or ornate phrasing that is necessary rather than silently removing important precision.
+
+## Creative Writing
+
+For fiction, poetry, memoir, scripts, and lyrical prose, treat the rules as pressure, not law. Keep intentional ambiguity, cadence, dialogue style, image, and character voice when they create a real effect. Remove only the language that feels inherited, inflated, evasive, or lazy.

package/skills/orwell-writing/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Orwell Writing"
+  short_description: "Plain English rules for clear writing"
+  default_prompt: "Use $orwell-writing to revise this draft into clear, direct English."

package/skills/session-profiler/README.md

@@ -0,0 +1,25 @@
+# Session Profiler
+
+<p align="center">
+  <img src="../../assets/skill-cards/session-profiler.svg" alt="session-profiler skill card" width="100%">
+</p>
+
+Inspect Claude Code and Codex session transcripts, summarize agent activity,
+break down time, tools, tokens, and estimated cost, and export Perfetto traces.
+
+## Install
+
+Install this skill for your user account:
+
+```bash
+npx @tamng0905/builder-essential-skills --skill session-profiler
+```
+
+Install it into the current repository instead:
+
+```bash
+npx @tamng0905/builder-essential-skills --skill session-profiler --project
+```
+
+Restart Claude Code or Codex. Python 3 is required for the profiler's bundled
+tools; see [SKILL.md](SKILL.md) for usage and transcript details.

package/skills/session-profiler/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: session-profiler
+description: Profile and debug Claude Code and OpenAI Codex sessions from their JSONL transcripts. Find a session and its subagents, build a queryable event table, summarize the work as a hierarchical table of contents, break down wall time, inference, tools, tokens, and estimated cost per agent, identify errors and improvement opportunities, and export a shareable Perfetto trace. Use when a user wants to inspect what a Claude or Codex session did, debug agent or subagent activity, understand session cost or latency, create a session timeline, generate a trace, or learn how to improve the next agent run.
+---
+
+# Session Profiler
+
+Turn one Claude Code or Codex main transcript plus its subagent transcripts into analysis artifacts. Route every operation through the bundled wrapper so it uses a consistent environment and remembers the latest parsed work directory.
+
+```bash
+SP="$SKILL/scripts/sp"
+```
+
+Resolve `SKILL` to this skill's directory. If it is unavailable, use the absolute path to `scripts/sp` beside this file.
+
+## Workflow
+
+1. Find and inspect the session.
+
+```bash
+$SP projects
+$SP list [--provider claude|codex] [--n 20]
+$SP list --project-dir ~/.claude/projects/<munged-cwd>
+$SP find <session-id-prefix>
+$SP info <session-id-or-path>
+```
+
+Claude Code stores main transcripts at `~/.claude/projects/<munged-cwd>/<session-id>.jsonl`; its subagents normally live at `<session-id>/subagents/agent-*.jsonl`. Codex stores rollouts under `${CODEX_HOME:-~/.codex}/sessions/YYYY/MM/DD/rollout-*.jsonl` and archived rollouts under `archived_sessions/`. Codex subagent rollouts identify their parent thread recursively in `session_meta`.
+
+2. Parse the session before analyzing it. Re-run this for a session that is still active.
+
+```bash
+$SP parse <session-id-or-main-jsonl-path>
+```
+
+The command prints and remembers its work directory. It writes `events.parquet`, `events.csv`, and `agents.json`. Override the remembered directory with global `--data-dir <dir>` or `SESSION_DATA_DIR`.
+
+3. Start with a readable profile, then narrow the investigation.
+
+```bash
+$SP brief
+$SP agent-summary
+$SP costs
+$SP slowest-tools --n 20 [--agent <id-or-name>]
+$SP tool-breakdown [--agent <id-or-name>]
+$SP inference-vs-tool
+$SP errors
+$SP turns
+$SP timeline 2026-07-08T19:14:00Z --window 120
+$SP events [--agent main] [--tool Bash] [--grep rebase] [--since 2026-07-08] [--n 30] [--long]
+```
+
+Use `brief` first when explaining a session to a person. It writes `brief.md`
+with the session's headline metrics, standout slow paths or failures, prompt
+trail or TOC storyline, and an agent scoreboard. Use the table commands for
+specific questions after the brief identifies the interesting region.
+
+For ad hoc pandas analysis, set `SESSION_DATA_DIR`, add `scripts/` to `PYTHONPATH`, and use `from session_profiler.dataset import load; df = load()` inside the wrapper's venv.
+
+4. Summarize the session and preserve lessons for the next run.
+
+```bash
+$SP toc --dry-run
+$SP toc                       # auto-selects claude or codex from the parsed provider
+$SP toc --engine codex        # optional override; --model is also supported
+$SP review
+```
+
+Use `toc --dry-run` to inspect the sanitized, junk-free digest without calling another model. `toc` automatically calls `claude -p` for Claude data or an ephemeral, read-only `codex exec` for Codex data, then writes `toc.json` plus `toc.md`. Show `toc.md` to orient the user. `review` writes `review.md` with deterministic observations about failed calls, slow paths, active-time mix, delegation, and estimated cost. Turn those observations into concrete changes to prompts, tool batching, preflight checks, or subagent assignments; do not claim the profiler automatically changes agent behavior.
+
+5. Build and open the trace.
+
+```bash
+$SP trace
+$SP open
+```
+
+Load the emitted `trace.json.gz` in [Perfetto](https://ui.perfetto.dev). Read
+it top-down: `Session overview` gives the whole run, `Table of contents` shows
+the story when `toc.json` exists, each agent's `work timeline` shows inference
+and tools, `prompt trail` marks user turns, and `usage tokens + cost` shows
+cumulative counters. Click a slice to inspect sanitized input/output previews,
+duration, concurrency, failure state, token count, and estimated cost.
+
+## Interpretation Rules
+
+Trust these derivations instead of recomputing them from raw rows:
+
+- For Claude, deduplicate usage per API `message.id`: content-block records repeat a growing usage snapshot, so keep only the final snapshot once. For Codex, consume `last_token_usage` once per `token_count` event and treat `cached_input_tokens` as a subset of input tokens.
+- Sum tokens across agents. Subagent token usage lives in the subagent transcript, not the parent transcript.
+- Measure a tool from `tool_use` to its matching `tool_result` within the same transcript. Treat multiple tool uses sharing one assistant message as concurrent.
+- Measure inference from the first to last assistant record for one message ID. Do not treat human idle time as inference.
+- Measure each subagent's wall runtime from the first to last timestamp in its own transcript, not from the parent's spawn tool span.
+- Treat active-time totals as sums of spans, not wall time. Concurrent tools and agents can make summed active time exceed elapsed wall time.
+- Label all dollar values as estimates. Claude uses the source specification's Opus-tier reference rates. Codex uses model-specific public OpenAI API rates when the model is known, including long-context multipliers recorded by the pricing docs. Codex subscriptions, credits, priority processing, tool fees, and negotiated rates can differ; an unknown model is marked unavailable instead of guessed.
+
+## Privacy And Failure Handling
+
+- Treat transcripts and traces as sensitive. Previews redact long opaque tokens and common auth/cookie headers, but can still contain source code, prompts, paths, personal data, or secrets. Review before sharing and share only where the session owner would.
+- Expect UTC timestamps throughout.
+- If parsing a growing transcript, rerun `parse` immediately before final analysis.
+- If dependency bootstrap fails, report the `uv` or `pip` error and let the user fix local network/package configuration. Do not add machine-specific proxy settings to this skill.
+- If `toc` fails because the matching `claude` or `codex` CLI is missing or unauthenticated, keep the parsed data and analyses; use `toc --dry-run` as a digest and explain the missing prerequisite.

package/skills/session-profiler/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Session Profiler"
+  short_description: "Profile Claude and Codex agent sessions"
+  default_prompt: "Use $session-profiler to profile this Claude Code or Codex session, explain where time and tokens went, and identify improvements for the next run."

package/skills/session-profiler/scripts/requirements.txt

@@ -0,0 +1,2 @@
+pandas>=2.1
+pyarrow>=14

package/skills/session-profiler/scripts/session_profiler/__init__.py

@@ -0,0 +1,5 @@
+"""Claude Code JSONL session profiler."""
+
+from .dataset import load
+
+__all__ = ["load"]

package/skills/session-profiler/scripts/session_profiler/analyses.py

@@ -0,0 +1,246 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+import pandas as pd
+
+from .dataset import _price, load, load_agents, work_dir
+
+
+def _duration(seconds: float) -> str:
+    seconds = max(0.0, float(seconds or 0))
+    if seconds < 60:
+        return f"{seconds:.1f}s"
+    minutes, sec = divmod(seconds, 60)
+    if minutes < 60:
+        return f"{int(minutes)}m {int(sec)}s"
+    hours, minutes = divmod(minutes, 60)
+    return f"{int(hours)}h {int(minutes)}m"
+
+
+def _markdown_table(headers: list[str], rows: list[list[object]]) -> str:
+    if not rows:
+        return ""
+    def cell(value: object) -> str:
+        return str(value).replace("|", "\\|")
+
+    lines = [
+        "| " + " | ".join(cell(header) for header in headers) + " |",
+        "| " + " | ".join("---" for _ in headers) + " |",
+    ]
+    for row in rows:
+        lines.append("| " + " | ".join(cell(value) for value in row) + " |")
+    return "\n".join(lines)
+
+
+def _fmt(df: pd.DataFrame) -> str:
+    if df.empty:
+        return "No matching events."
+    return df.to_string(index=False, max_colwidth=80)
+
+
+def agent_summary(data_dir: str | Path | None = None) -> str:
+    df = load(data_dir)
+    agents = load_agents(data_dir)["agents"]
+    rows = []
+    for agent in agents:
+        part = df[df.agent_id == agent["id"]]
+        inf = part[part.event_type == "inference"]
+        tools = part[part.event_type == "tool"]
+        start = pd.to_datetime(agent.get("start_ts"), utc=True)
+        end = pd.to_datetime(agent.get("end_ts"), utc=True)
+        priced = all(_price(row.provider, row.model) for row in inf.itertuples()) if not inf.empty else True
+        rows.append({
+            "agent": agent["name"], "id": agent["id"], "depth": agent["spawn_depth"],
+            "wall_s": round((end - start).total_seconds(), 2) if not pd.isna(start) and not pd.isna(end) else 0,
+            "inference_s": round(inf.duration_ms.sum() / 1000, 2), "tool_s": round(tools.duration_ms.sum() / 1000, 2),
+            "tokens": int(inf[["input_tokens", "cache_read_input_tokens", "cache_creation_input_tokens", "output_tokens"]].sum().sum()),
+            "est_cost_usd": round(inf.estimated_cost_usd.sum(), 4), "pricing": "reference" if priced else "partial/unavailable",
+        })
+    return "Estimated cost (public price table; not billing data)\n" + _fmt(pd.DataFrame(rows))
+
+
+def costs(data_dir=None) -> str:
+    df = load(data_dir)
+    inf = df[df.event_type == "inference"]
+    cols = ["input_tokens", "cache_read_input_tokens", "cache_creation_input_tokens", "output_tokens", "estimated_cost_usd"]
+    result = inf.groupby(["provider", "agent_name", "model"], dropna=False)[cols].sum().reset_index()
+    result["pricing"] = result.apply(lambda row: "reference" if _price(row.provider, row.model) else "unavailable", axis=1)
+    result["estimated_cost_usd"] = result.estimated_cost_usd.round(5)
+    return "ESTIMATES from public rates; not invoice/billing data.\n" + _fmt(result)
+
+
+def slowest_tools(data_dir=None, n=20, agent=None) -> str:
+    df = load(data_dir)
+    part = df[df.event_type == "tool"]
+    if agent:
+        part = part[(part.agent_id == agent) | (part.agent_name == agent)]
+    return _fmt(part.nlargest(n, "duration_ms")[["ts", "agent_name", "tool_name", "duration_ms", "is_error", "input_preview"]])
+
+
+def tool_breakdown(data_dir=None, agent=None) -> str:
+    df = load(data_dir)
+    part = df[df.event_type == "tool"]
+    if agent:
+        part = part[(part.agent_id == agent) | (part.agent_name == agent)]
+    out = part.groupby(["agent_name", "tool_name"]).agg(calls=("tool_name", "size"), errors=("is_error", "sum"), total_s=("duration_ms", lambda x: round(x.sum()/1000, 2)), mean_ms=("duration_ms", lambda x: round(x.mean(), 1)), max_ms=("duration_ms", lambda x: round(x.max(), 1))).reset_index()
+    return _fmt(out.sort_values("total_s", ascending=False))
+
+
+def inference_vs_tool(data_dir=None) -> str:
+    df = load(data_dir)
+    part = df[df.event_type.isin(["inference", "tool"])]
+    out = part.groupby(["agent_name", "event_type"]).duration_ms.sum().unstack(fill_value=0) / 1000
+    return _fmt(out.round(2).reset_index())
+
+
+def errors(data_dir=None) -> str:
+    df = load(data_dir)
+    return _fmt(df[(df.event_type == "tool") & df.is_error][["ts", "agent_name", "tool_name", "duration_ms", "input_preview", "output_preview"]])
+
+
+def turns(data_dir=None) -> str:
+    df = load(data_dir)
+    prompts = df[(df.agent_id == "main") & (df.event_type == "user_prompt")].sort_values("ts").copy()
+    prompts["time_to_next_prompt_s"] = (prompts.ts.shift(-1) - prompts.ts).dt.total_seconds()
+    prompts["prompt"] = prompts.text.str.replace(r"\s+", " ", regex=True).str[:160]
+    return _fmt(prompts[["ts", "time_to_next_prompt_s", "prompt"]])
+
+
+def brief(data_dir=None) -> str:
+    out = work_dir(data_dir)
+    df = load(out)
+    metadata = load_agents(out)
+    agents = metadata["agents"]
+    inf = df[df.event_type == "inference"]
+    tools = df[df.event_type == "tool"]
+    prompts = df[(df.agent_id == "main") & (df.event_type == "user_prompt")]
+    start, end = df.ts.min(), df.end_ts.max()
+    wall_s = (end - start).total_seconds() if not df.empty else 0
+    token_cols = ["input_tokens", "cache_read_input_tokens", "cache_creation_input_tokens", "output_tokens"]
+    total_tokens = int(inf[token_cols].sum().sum()) if not inf.empty else 0
+    total_cost = float(inf.estimated_cost_usd.sum()) if not inf.empty else 0.0
+    lines = [
+        "# Session profile",
+        "",
+        f"Provider: `{metadata.get('provider', 'unknown')}`",
+        f"Session: `{metadata.get('session_id', 'unknown')}`",
+        "",
+        "## At a glance",
+        "",
+        _markdown_table(
+            ["Wall", "Agents", "Prompts", "Tool calls", "Errors", "Tokens", "Est. cost"],
+            [[_duration(wall_s), len(agents), len(prompts), len(tools), int(tools.is_error.sum()) if not tools.empty else 0, f"{total_tokens:,}", f"${total_cost:.4f}"]],
+        ),
+        "",
+    ]
+
+    highlights = []
+    if not tools.empty:
+        slow = tools.nlargest(1, "duration_ms").iloc[0]
+        highlights.append(f"Longest tool call: `{slow.tool_name}` on `{slow.agent_name}` took {_duration(slow.duration_ms / 1000)}.")
+    if not inf.empty:
+        by_agent = inf.groupby("agent_name").estimated_cost_usd.sum().sort_values(ascending=False)
+        if not by_agent.empty:
+            highlights.append(f"Highest estimated cost: `{by_agent.index[0]}` at ${by_agent.iloc[0]:.4f}.")
+    if not tools.empty and tools.is_error.any():
+        failed = tools[tools.is_error].groupby("tool_name").size().sort_values(ascending=False)
+        highlights.append(f"Tool failures: {int(tools.is_error.sum())}, led by `{failed.index[0]}`.")
+    if not highlights:
+        highlights.append("No failed tool calls were recorded.")
+    lines.extend(["## What stands out", "", *[f"- {item}" for item in highlights], ""])
+
+    toc_path = out / "toc.json"
+    if toc_path.exists():
+        import json
+
+        toc = json.loads(toc_path.read_text())
+        rows = []
+        for phase in toc.get("phases", []):
+            try:
+                phase_start = pd.to_datetime(phase["start_ts"], utc=True)
+                phase_end = pd.to_datetime(phase["end_ts"], utc=True)
+            except (KeyError, ValueError):
+                continue
+            rows.append([
+                phase.get("title", "Phase"),
+                _duration((phase_end - phase_start).total_seconds()),
+                phase.get("summary", ""),
+            ])
+        if rows:
+            lines.extend(["## Storyline", "", _markdown_table(["Phase", "Duration", "Summary"], rows), ""])
+    elif not prompts.empty:
+        prompt_rows = []
+        for _, row in prompts.sort_values("ts").head(6).iterrows():
+            prompt_rows.append([row.ts.isoformat(), " ".join(str(row.text).split())[:120]])
+        lines.extend(["## Prompt trail", "", _markdown_table(["Time", "Prompt"], prompt_rows), ""])
+
+    score_rows = []
+    for agent in agents:
+        part = df[df.agent_id == agent["id"]]
+        agent_inf = part[part.event_type == "inference"]
+        agent_tools = part[part.event_type == "tool"]
+        start = pd.to_datetime(agent.get("start_ts"), utc=True)
+        end = pd.to_datetime(agent.get("end_ts"), utc=True)
+        agent_wall_s = (end - start).total_seconds() if not pd.isna(start) and not pd.isna(end) else 0
+        score_rows.append([
+            agent["name"],
+            agent["agent_type"],
+            _duration(agent_wall_s),
+            _duration(agent_inf.duration_ms.sum() / 1000),
+            _duration(agent_tools.duration_ms.sum() / 1000),
+            f"{int(agent_inf[token_cols].sum().sum()):,}" if not agent_inf.empty else "0",
+            f"${agent_inf.estimated_cost_usd.sum():.4f}" if not agent_inf.empty else "$0.0000",
+        ])
+    lines.extend(["## Agent scoreboard", "", _markdown_table(["Agent", "Role", "Wall", "Inference", "Tools", "Tokens", "Est. cost"], score_rows), ""])
+    lines.append("Costs are estimates from public reference rates, not billing data.")
+    result = "\n".join(lines) + "\n"
+    (out / "brief.md").write_text(result)
+    return result
+
+
+def timeline(moment, window=120, data_dir=None) -> str:
+    df = load(data_dir)
+    center = pd.to_datetime(moment, utc=True)
+    start, end = center - pd.Timedelta(seconds=window), center + pd.Timedelta(seconds=window)
+    part = df[(df.ts <= end) & (df.end_ts >= start) & df.event_type.isin(["user_prompt", "inference", "tool"])]
+    return _fmt(part[["ts", "end_ts", "agent_name", "event_type", "tool_name", "duration_ms", "is_error", "input_preview"]])
+
+
+def events_query(data_dir=None, agent=None, tool=None, grep=None, since=None, n=30, long=False) -> str:
+    df = load(data_dir)
+    if agent:
+        df = df[(df.agent_id == agent) | (df.agent_name == agent)]
+    if tool:
+        df = df[df.tool_name == tool]
+    if since:
+        df = df[df.ts >= pd.to_datetime(since, utc=True)]
+    if grep:
+        searchable = df[["text", "input_preview", "output_preview", "tool_name"]].fillna("").agg(" ".join, axis=1)
+        df = df[searchable.str.contains(grep, case=False, regex=False)]
+    cols = ["ts", "agent_name", "event_type", "tool_name", "duration_ms", "is_error", "text", "input_preview", "output_preview"] if long else ["ts", "agent_name", "event_type", "tool_name", "duration_ms", "is_error", "text"]
+    return _fmt(df.head(n)[cols])
+
+
+def review(data_dir=None) -> str:
+    df = load(data_dir)
+    tools = df[df.event_type == "tool"]
+    inf = df[df.event_type == "inference"]
+    total_s = (tools.duration_ms.sum() + inf.duration_ms.sum()) / 1000
+    lines = ["# Session improvement review", "", "Use these observations to adjust the next agent run:", ""]
+    if tools.is_error.any():
+        lines.append(f"- Investigate {int(tools.is_error.sum())} failed tool calls; repeated failures usually indicate missing preflight checks.")
+    if not tools.empty:
+        slow = tools.nlargest(3, "duration_ms")
+        for _, row in slow.iterrows():
+            lines.append(f"- Slow path: {row.tool_name} on {row.agent_name} took {row.duration_ms/1000:.1f}s. Consider batching, narrowing, or running independent work concurrently.")
+    tool_share = tools.duration_ms.sum() / (tools.duration_ms.sum() + inf.duration_ms.sum()) if total_s else 0
+    lines.append(f"- Observed summed active time was {total_s:.1f}s ({tool_share:.0%} tools, {1-tool_share:.0%} inference). Overlapping spans make this larger than wall time.")
+    lines.append(f"- Estimated cost was ${inf.estimated_cost_usd.sum():.4f}; this uses provider-specific public API reference rates, not subscription or billing data.")
+    if len(load_agents(data_dir)["agents"]) == 1:
+        lines.append("- No subagents were recorded. For separable research or verification work, delegation may reduce wall time.")
+    else:
+        lines.append("- Compare subagent outputs and runtimes before reusing the same delegation shape; keep assignments bounded and independently verifiable.")
+    result = "\n".join(lines) + "\n"
+    (work_dir(data_dir) / "review.md").write_text(result)
+    return result

package/skills/session-profiler/scripts/session_profiler/cli.py

@@ -0,0 +1,77 @@
+from __future__ import annotations
+
+import argparse
+import json
+from datetime import datetime
+from pathlib import Path
+
+from . import analyses
+from .dataset import parse, work_dir
+from .discover import codex_transcripts, find_sessions, is_codex_subagent, main_transcripts, project_dirs, resolve_session, session_info
+from .toc import create as create_toc
+from .trace import create as create_trace, open_ui
+
+
+def parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(prog="sp", description="Profile Claude Code and Codex JSONL sessions")
+    p.add_argument("--data-dir", help="Parsed work directory (also SESSION_DATA_DIR)")
+    sub = p.add_subparsers(dest="command", required=True)
+    sub.add_parser("projects")
+    x = sub.add_parser("list"); x.add_argument("--project-dir", type=Path); x.add_argument("--provider", choices=["claude", "codex"]); x.add_argument("--n", type=int, default=20)
+    x = sub.add_parser("find"); x.add_argument("prefix")
+    x = sub.add_parser("info"); x.add_argument("session")
+    x = sub.add_parser("parse"); x.add_argument("session"); x.add_argument("--out", type=Path)
+    sub.add_parser("agent-summary"); sub.add_parser("costs")
+    x = sub.add_parser("slowest-tools"); x.add_argument("--n", type=int, default=20); x.add_argument("--agent")
+    x = sub.add_parser("tool-breakdown"); x.add_argument("--agent")
+    sub.add_parser("inference-vs-tool"); sub.add_parser("errors"); sub.add_parser("turns"); sub.add_parser("brief"); sub.add_parser("review")
+    x = sub.add_parser("timeline"); x.add_argument("moment"); x.add_argument("--window", type=int, default=120)
+    x = sub.add_parser("events"); x.add_argument("--agent"); x.add_argument("--tool"); x.add_argument("--grep"); x.add_argument("--since"); x.add_argument("--n", type=int, default=30); x.add_argument("--long", action="store_true")
+    x = sub.add_parser("toc"); x.add_argument("--dry-run", action="store_true"); x.add_argument("--engine", choices=["auto", "claude", "codex"], default="auto"); x.add_argument("--model")
+    sub.add_parser("trace"); sub.add_parser("open"); sub.add_parser("where")
+    return p
+
+
+def main() -> None:
+    args = parser().parse_args(); data = args.data_dir
+    if args.command == "projects":
+        for path in project_dirs(): print(datetime.fromtimestamp(path.stat().st_mtime).isoformat(timespec="seconds"), path)
+    elif args.command == "list":
+        if args.project_dir:
+            paths = main_transcripts(args.project_dir.expanduser())
+        else:
+            paths = []
+            if args.provider != "codex":
+                for d in project_dirs():
+                    if ".claude/projects" in str(d): paths.extend(main_transcripts(d))
+            if args.provider != "claude": paths.extend(p for p in codex_transcripts() if not is_codex_subagent(p))
+            paths = sorted(paths, key=lambda path: path.stat().st_mtime, reverse=True)
+        shown = 0
+        for path in paths:
+            info = session_info(path)
+            span = f"{info['span_seconds']:.0f}s" if info["span_seconds"] is not None else "?s"; print(f"{info['provider']:<6} {info['session_id']}  {info['bytes']/1024:.1f} KiB  {len(info['subagents'])} subagents  {span}  {info['first_prompt']}")
+            shown += 1
+            if shown >= args.n: break
+    elif args.command == "find":
+        for path in find_sessions(args.prefix): print(path)
+    elif args.command == "info": print(json.dumps(session_info(resolve_session(args.session)), indent=2))
+    elif args.command == "parse": print(parse(args.session, args.out))
+    elif args.command == "agent-summary": print(analyses.agent_summary(data))
+    elif args.command == "costs": print(analyses.costs(data))
+    elif args.command == "slowest-tools": print(analyses.slowest_tools(data, args.n, args.agent))
+    elif args.command == "tool-breakdown": print(analyses.tool_breakdown(data, args.agent))
+    elif args.command == "inference-vs-tool": print(analyses.inference_vs_tool(data))
+    elif args.command == "errors": print(analyses.errors(data))
+    elif args.command == "turns": print(analyses.turns(data))
+    elif args.command == "brief": print(analyses.brief(data))
+    elif args.command == "timeline": print(analyses.timeline(args.moment, args.window, data))
+    elif args.command == "events": print(analyses.events_query(data, args.agent, args.tool, args.grep, args.since, args.n, args.long))
+    elif args.command == "review": print(analyses.review(data))
+    elif args.command == "toc": print(create_toc(data, args.dry_run, args.model, args.engine))
+    elif args.command == "trace": print(create_trace(data))
+    elif args.command == "open": print(open_ui())
+    elif args.command == "where": print(work_dir(data))
+
+
+if __name__ == "__main__":
+    main()