codex-skill-report 0.1.0__tar.gz

codex_skill_report-0.1.0/LICENSE

@@ -0,0 +1,12 @@
+Copyright (C) 2026 egornomic
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

codex_skill_report-0.1.0/PKG-INFO

@@ -0,0 +1,72 @@
+Metadata-Version: 2.4
+Name: codex-skill-report
+Version: 0.1.0
+Summary: Analyze inferred skill invocations in retained Codex sessions
+Author: egornomic
+Author-email: egornomic <git@egornomic.xyz>
+License-Expression: 0BSD
+License-File: LICENSE
+Requires-Dist: rich>=15.0.0
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# Codex Skill Report
+
+Analyze retained Codex session transcripts and estimate how often each skill was
+self-invoked, explicitly requested, or ambiguously mentioned.
+
+## Run with `uvx`
+
+From anywhere after publishing to PyPI:
+
+```bash
+uvx codex-skill-report
+```
+
+From a local checkout:
+
+```bash
+uvx --from . codex-skill-report
+```
+
+Useful output modes:
+
+```bash
+uvx codex-skill-report --details
+uvx codex-skill-report --json --output report.json
+uvx codex-skill-report --csv --output report.csv
+uvx codex-skill-report --markdown --output report.md
+```
+
+Use `--codex-home PATH` to scan a non-default Codex data directory. The default
+is `$CODEX_HOME`, falling back to `~/.codex`.
+
+## How counting works
+
+A `SKILL.md` read is the strongest event available in retained transcripts. It
+is counted once per skill, agent, and turn, then classified as:
+
+- **Self**: the active request did not name the skill.
+- **Requested**: the active request explicitly asked Codex to use the skill.
+- **Ambiguous**: the request mentioned the skill without clearly asking to use it.
+
+The report separates self-invocations by root agents and subagents. Deleted,
+ephemeral, compacted-away, or unsynced sessions cannot be recovered. Wildcard
+reads that cannot be attributed to one skill are reported separately. Human
+reports show the most recent invocation as a compact relative age; JSON and CSV
+retain its exact timestamp. In terminal output, red names identify skills that
+previously came from a managed user, system, or plugin root but no longer exist.
+Repository-local skill folders are not scanned and remain uncolored when their
+availability cannot be determined. When forked transcripts replay an earlier
+turn, the report keeps only the earliest occurrence of each skill read.
+
+## Development
+
+```bash
+uv sync --all-groups
+uv run pytest
+uv run ruff format --check .
+uv run ruff check .
+uv run ty check src
+uv build
+```

codex_skill_report-0.1.0/README.md

@@ -0,0 +1,60 @@
+# Codex Skill Report
+
+Analyze retained Codex session transcripts and estimate how often each skill was
+self-invoked, explicitly requested, or ambiguously mentioned.
+
+## Run with `uvx`
+
+From anywhere after publishing to PyPI:
+
+```bash
+uvx codex-skill-report
+```
+
+From a local checkout:
+
+```bash
+uvx --from . codex-skill-report
+```
+
+Useful output modes:
+
+```bash
+uvx codex-skill-report --details
+uvx codex-skill-report --json --output report.json
+uvx codex-skill-report --csv --output report.csv
+uvx codex-skill-report --markdown --output report.md
+```
+
+Use `--codex-home PATH` to scan a non-default Codex data directory. The default
+is `$CODEX_HOME`, falling back to `~/.codex`.
+
+## How counting works
+
+A `SKILL.md` read is the strongest event available in retained transcripts. It
+is counted once per skill, agent, and turn, then classified as:
+
+- **Self**: the active request did not name the skill.
+- **Requested**: the active request explicitly asked Codex to use the skill.
+- **Ambiguous**: the request mentioned the skill without clearly asking to use it.
+
+The report separates self-invocations by root agents and subagents. Deleted,
+ephemeral, compacted-away, or unsynced sessions cannot be recovered. Wildcard
+reads that cannot be attributed to one skill are reported separately. Human
+reports show the most recent invocation as a compact relative age; JSON and CSV
+retain its exact timestamp. In terminal output, red names identify skills that
+previously came from a managed user, system, or plugin root but no longer exist.
+Repository-local skill folders are not scanned and remain uncolored when their
+availability cannot be determined. When forked transcripts replay an earlier
+turn, the report keeps only the earliest occurrence of each skill read.
+
+## Development
+
+```bash
+uv sync --all-groups
+uv run pytest
+uv run ruff format --check .
+uv run ruff check .
+uv run ty check src
+uv build
+```

codex_skill_report-0.1.0/pyproject.toml

@@ -0,0 +1,50 @@
+[project]
+name = "codex-skill-report"
+version = "0.1.0"
+description = "Analyze inferred skill invocations in retained Codex sessions"
+readme = "README.md"
+license = "0BSD"
+license-files = ["LICENSE"]
+authors = [
+    { name = "egornomic", email = "git@egornomic.xyz" }
+]
+requires-python = ">=3.11"
+dependencies = [
+    "rich>=15.0.0",
+]
+
+[project.scripts]
+codex-skill-report = "codex_skill_report.cli:main"
+
+[build-system]
+requires = ["uv_build>=0.11.30,<0.12.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.1.1",
+    "ruff>=0.16.0",
+    "ty>=0.0.64",
+]
+
+[tool.pytest.ini_options]
+addopts = "-q"
+pythonpath = ["src"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["ALL"]
+ignore = ["COM812", "CPY001", "D", "ISC001"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**/*.py" = ["PLR2004", "S101"]
+
+[tool.ty.environment]
+python-version = "3.11"
+
+[tool.ty.rules]
+possibly-unresolved-reference = "error"
+unused-ignore-comment = "warn"

codex_skill_report-0.1.0/src/codex_skill_report/__init__.py

@@ -0,0 +1,5 @@
+"""Inspect retained Codex sessions for inferred skill invocations."""
+
+from codex_skill_report.cli import main
+
+__all__ = ["main"]

codex_skill_report-0.1.0/src/codex_skill_report/cli.py

@@ -0,0 +1,198 @@
+"""Command-line interface for codex-skill-report."""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+from importlib.metadata import PackageNotFoundError, version
+from pathlib import Path
+from typing import TYPE_CHECKING, TextIO
+
+from rich.console import Console
+
+from codex_skill_report.reporting import (
+    render_csv,
+    render_json,
+    render_markdown,
+    render_terminal,
+)
+from codex_skill_report.scanner import CodexHomeNotFoundError, scan_codex_home
+
+if TYPE_CHECKING:
+    from codex_skill_report.models import ScanReport
+
+PACKAGE_NAME = "codex-skill-report"
+MIN_TERMINAL_WIDTH = 60
+
+
+def package_version() -> str:
+    """Return the installed distribution version."""
+    try:
+        return version(PACKAGE_NAME)
+    except PackageNotFoundError:
+        return "0.1.0"
+
+
+def positive_width(value: str) -> int:
+    """Parse and validate a useful terminal width."""
+    width = int(value)
+    if width < MIN_TERMINAL_WIDTH:
+        message = f"width must be at least {MIN_TERMINAL_WIDTH} columns"
+        raise argparse.ArgumentTypeError(message)
+    return width
+
+
+def parse_args(argv: list[str] | None = None) -> argparse.Namespace:
+    """Parse the public command-line interface."""
+    default_home = Path(os.environ.get("CODEX_HOME", Path.home() / ".codex"))
+    parser = argparse.ArgumentParser(
+        prog=PACKAGE_NAME,
+        description=(
+            "Infer self-selected and requested skill invocations from retained "
+            "Codex session transcripts."
+        ),
+        epilog=(
+            "examples:\n"
+            "  codex-skill-report\n"
+            "  codex-skill-report --details\n"
+            "  codex-skill-report --json --output report.json\n"
+            "  codex-skill-report --markdown > report.md"
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument(
+        "--codex-home",
+        type=Path,
+        default=default_home,
+        metavar="PATH",
+        help=f"Codex data directory (default: {default_home})",
+    )
+
+    format_group = parser.add_mutually_exclusive_group()
+    format_group.add_argument(
+        "--json",
+        dest="output_format",
+        action="store_const",
+        const="json",
+        help="write the complete report as JSON",
+    )
+    format_group.add_argument(
+        "--csv",
+        dest="output_format",
+        action="store_const",
+        const="csv",
+        help="write aggregate skill counts as CSV",
+    )
+    format_group.add_argument(
+        "--markdown",
+        dest="output_format",
+        action="store_const",
+        const="markdown",
+        help="write a Markdown report",
+    )
+    parser.set_defaults(output_format="terminal")
+
+    parser.add_argument(
+        "--details",
+        action="store_true",
+        help="include individual invocation evidence in human-readable output",
+    )
+    parser.add_argument(
+        "-o",
+        "--output",
+        default="-",
+        metavar="PATH",
+        help="write output to PATH; use - for stdout (default: -)",
+    )
+    parser.add_argument(
+        "--width",
+        type=positive_width,
+        metavar="COLUMNS",
+        help="override terminal table width (minimum: 60)",
+    )
+    parser.add_argument(
+        "--no-color",
+        action="store_true",
+        help="disable terminal colors",
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"%(prog)s {package_version()}",
+    )
+    return parser.parse_args(argv)
+
+
+def color_is_disabled(args: argparse.Namespace) -> bool:
+    """Honor explicit and conventional terminal color controls."""
+    return bool(
+        args.no_color or "NO_COLOR" in os.environ or os.environ.get("TERM", "").casefold() == "dumb"
+    )
+
+
+def scan_with_feedback(args: argparse.Namespace) -> ScanReport:
+    """Scan with transient progress feedback only in an interactive terminal."""
+    show_status = (
+        args.output_format == "terminal"
+        and args.output == "-"
+        and sys.stdout.isatty()
+        and sys.stderr.isatty()
+    )
+    if not show_status:
+        return scan_codex_home(args.codex_home)
+
+    error_console = Console(stderr=True, no_color=color_is_disabled(args))
+    with error_console.status("Scanning retained Codex sessions…", spinner="dots"):
+        return scan_codex_home(args.codex_home)
+
+
+def open_output(path: str) -> tuple[TextIO, bool]:
+    """Open the primary output destination and report ownership."""
+    if path == "-":
+        return sys.stdout, False
+    return Path(path).expanduser().open("w", encoding="utf-8", newline=""), True
+
+
+def write_report(args: argparse.Namespace, stream: TextIO, report: ScanReport) -> None:
+    """Render the selected output contract to a text stream."""
+    if args.output_format == "terminal":
+        output_is_terminal = stream is sys.stdout and sys.stdout.isatty()
+        console = Console(
+            file=stream,
+            force_terminal=output_is_terminal,
+            no_color=color_is_disabled(args) or not output_is_terminal,
+            width=args.width,
+        )
+        render_terminal(report, console, details=args.details)
+    elif args.output_format == "json":
+        stream.write(render_json(report))
+    elif args.output_format == "csv":
+        stream.write(render_csv(report))
+    else:
+        stream.write(render_markdown(report, details=args.details))
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Run the CLI and map expected failures to stable exit codes."""
+    args = parse_args(argv)
+    error_console = Console(stderr=True, no_color=color_is_disabled(args))
+
+    try:
+        report = scan_with_feedback(args)
+        stream, should_close = open_output(args.output)
+        try:
+            write_report(args, stream, report)
+        finally:
+            if should_close:
+                stream.close()
+    except CodexHomeNotFoundError as error:
+        error_console.print(f"[red]error:[/red] {error}")
+        return 2
+    except OSError as error:
+        error_console.print(f"[red]error:[/red] {error}")
+        return 1
+    except KeyboardInterrupt:
+        error_console.print("[yellow]Interrupted.[/yellow]")
+        return 130
+    return 0

codex_skill_report-0.1.0/src/codex_skill_report/models.py

@@ -0,0 +1,60 @@
+"""Data models for Codex skill invocation reports."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal
+
+Classification = Literal["self", "requested", "ambiguous"]
+AgentKind = Literal["root", "subagent"]
+Availability = Literal["installed", "removed", "unknown"]
+
+
+@dataclass(frozen=True, slots=True)
+class Invocation:
+    """One inferred skill invocation in a Codex turn."""
+
+    skill: str
+    classification: Classification
+    agent: AgentKind
+    session_id: str
+    turn_id: str
+    timestamp: str
+    transcript: str
+    evidence: str
+
+
+@dataclass(slots=True)
+class ScanStats:
+    """Observable results and recoverable errors from a transcript scan."""
+
+    sessions_scanned: int = 0
+    malformed_lines: int = 0
+    unreadable_sessions: int = 0
+    unattributed_skill_reads: int = 0
+    replayed_invocations_deduplicated: int = 0
+
+
+@dataclass(frozen=True, slots=True)
+class SkillSummary:
+    """Aggregated invocation counts for one canonical skill name."""
+
+    skill: str
+    self_invocations: int
+    requested_invocations: int
+    ambiguous_invocations: int
+    root_self_invocations: int
+    subagent_self_invocations: int
+    sessions: int
+    last_used: str
+    availability: Availability
+
+
+@dataclass(frozen=True, slots=True)
+class ScanReport:
+    """Complete report produced from all discovered transcripts."""
+
+    codex_home: str
+    stats: ScanStats
+    skills: tuple[SkillSummary, ...]
+    invocations: tuple[Invocation, ...]

codex_skill_report-0.1.0/src/codex_skill_report/reporting.py

@@ -0,0 +1,295 @@
+"""Human and machine renderers for skill invocation reports."""
+
+from __future__ import annotations
+
+import csv
+import json
+from dataclasses import asdict
+from datetime import UTC, datetime
+from io import StringIO
+from typing import TYPE_CHECKING
+
+from rich import box
+from rich.table import Table
+from rich.text import Text
+
+if TYPE_CHECKING:
+    from rich.console import Console
+
+    from codex_skill_report.models import ScanReport
+
+DAYS_PER_YEAR = 365
+FULL_TABLE_MIN_WIDTH = 120
+
+
+def render_terminal(report: ScanReport, console: Console, *, details: bool) -> None:
+    """Render a width-aware terminal report with a real Unicode table."""
+    stats = report.stats
+    console.print()
+    console.print("[bold]Codex skill invocation report[/bold]")
+
+    summary = Text(style="dim")
+    summary.append(f"{stats.sessions_scanned:,} sessions")
+    summary.append("  •  ")
+    summary.append(f"{len(report.invocations):,} invocation events")
+    if stats.unattributed_skill_reads:
+        summary.append("  •  ")
+        summary.append(
+            f"{stats.unattributed_skill_reads:,} unattributed wildcard reads",
+            style="yellow",
+        )
+    if stats.replayed_invocations_deduplicated:
+        summary.append("  •  ")
+        summary.append(f"{stats.replayed_invocations_deduplicated:,} replayed events deduplicated")
+    console.print(summary)
+    console.print()
+
+    if not report.skills:
+        console.print("[yellow]No skill instruction reads were found.[/yellow]")
+        return
+
+    table, compact = build_skill_table(report, console.width)
+    console.print(table)
+    if compact:
+        console.print(
+            f"[dim]Compact view hides Root self and Subagent self. "
+            f"Use --width {FULL_TABLE_MIN_WIDTH} for the full table.[/dim]"
+        )
+
+    recoverable_errors = stats.malformed_lines + stats.unreadable_sessions
+    if recoverable_errors:
+        console.print(
+            f"[yellow]Skipped {stats.malformed_lines:,} malformed lines and "
+            f"{stats.unreadable_sessions:,} unreadable sessions.[/yellow]"
+        )
+
+    legend = Table.grid(padding=(0, 1))
+    legend.add_column(style="bold dim", no_wrap=True)
+    legend.add_column(style="dim")
+    legend.add_row(
+        "Self",
+        "SKILL.md read without an explicit request for that skill in the active turn.",
+    )
+    legend.add_row(
+        "Requested",
+        "SKILL.md read after the active request explicitly asks to use that skill.",
+    )
+    legend.add_row(
+        "Ambiguous",
+        "SKILL.md read when the active request mentions the skill but does not "
+        "clearly ask to use it.",
+    )
+    legend.add_row("Root self", "Self invocation by the primary Codex agent.")
+    legend.add_row("Subagent self", "Self invocation by a child agent.")
+    legend.add_row(
+        "Sessions",
+        "Unique sessions containing at least one detected invocation of that skill.",
+    )
+    legend.add_row(
+        "Last used",
+        "Elapsed time since the most recent detected invocation of that skill.",
+    )
+    legend.add_row(
+        Text("Red skill", style="bold red"),
+        "Previously managed skill no longer found. Project skills are not checked.",
+    )
+    console.print(legend)
+    console.print(
+        "[dim]Repeated reads count once per skill, agent, and turn. "
+        "Self = Root self + Subagent self.[/dim]"
+    )
+
+    if details:
+        render_terminal_details(report, console)
+
+
+def build_skill_table(report: ScanReport, width: int) -> tuple[Table, bool]:
+    """Build the full or compact aggregate table for the available width."""
+    table = Table(
+        box=box.ROUNDED,
+        header_style="bold",
+        highlight=True,
+        expand=True,
+    )
+    compact = width < FULL_TABLE_MIN_WIDTH
+    table.add_column("Skill", ratio=4 if compact else 3, overflow="fold")
+    table.add_column("Self", justify="right", style="bold cyan", no_wrap=True)
+    table.add_column("Req" if compact else "Requested", justify="right", no_wrap=True)
+    table.add_column("Amb" if compact else "Ambiguous", justify="right", no_wrap=True)
+    if not compact:
+        table.add_column("Root self", justify="right", no_wrap=True)
+        table.add_column("Subagent self", justify="right", no_wrap=True)
+    table.add_column("Sess" if compact else "Sessions", justify="right", no_wrap=True)
+    table.add_column("Last" if compact else "Last used", justify="right", no_wrap=True)
+
+    now = datetime.now(UTC)
+    for row in report.skills:
+        values = (
+            Text(row.skill, style="bold red" if row.availability == "removed" else ""),
+            f"{row.self_invocations:,}",
+            f"{row.requested_invocations:,}",
+            f"{row.ambiguous_invocations:,}",
+            f"{row.root_self_invocations:,}",
+            f"{row.subagent_self_invocations:,}",
+            f"{row.sessions:,}",
+            format_relative_age(row.last_used, now=now),
+        )
+        if compact:
+            table.add_row(values[0], values[1], values[2], values[3], values[6], values[7])
+        else:
+            table.add_row(*values)
+    return table, compact
+
+
+def render_terminal_details(report: ScanReport, console: Console) -> None:
+    """Render individual invocation evidence after the aggregate table."""
+    console.print()
+    detail_table = Table(
+        title="Invocation evidence",
+        box=box.SIMPLE_HEAVY,
+        header_style="bold",
+        expand=True,
+    )
+    detail_table.add_column("Timestamp", no_wrap=True)
+    detail_table.add_column("Skill", ratio=2, overflow="fold")
+    detail_table.add_column("Kind", no_wrap=True)
+    detail_table.add_column("Agent", no_wrap=True)
+    detail_table.add_column("Session", ratio=2, overflow="ellipsis")
+    detail_table.add_column("Evidence", ratio=3, overflow="fold")
+
+    styles = {"self": "cyan", "requested": "yellow", "ambiguous": "magenta"}
+    for invocation in sorted(report.invocations, key=lambda item: item.timestamp):
+        detail_table.add_row(
+            invocation.timestamp,
+            invocation.skill,
+            Text(invocation.classification, style=styles[invocation.classification]),
+            invocation.agent,
+            invocation.session_id,
+            invocation.evidence,
+        )
+    console.print(detail_table)
+
+
+def render_markdown(report: ScanReport, *, details: bool) -> str:
+    """Return a portable Markdown report."""
+    stats = report.stats
+    lines = [
+        "# Codex skill invocation report",
+        "",
+        f"- Sessions scanned: {stats.sessions_scanned}",
+        f"- Unique invocation events: {len(report.invocations)}",
+        f"- Malformed transcript lines skipped: {stats.malformed_lines}",
+        f"- Unreadable sessions skipped: {stats.unreadable_sessions}",
+        f"- Wildcard reads that could not be attributed: {stats.unattributed_skill_reads}",
+        f"- Replayed invocation events deduplicated: {stats.replayed_invocations_deduplicated}",
+        "",
+        (
+            "A self-invocation is a `SKILL.md` read without an explicit request for "
+            "that skill in the active turn. Repeated reads are counted once per "
+            "skill, agent, and turn."
+        ),
+        "",
+    ]
+
+    if not report.skills:
+        lines.append("No skill instruction reads were found.")
+        return "\n".join(lines) + "\n"
+
+    lines.extend(
+        (
+            (
+                "| Skill | Self | Requested | Ambiguous | Root self | "
+                "Subagent self | Sessions | Last used |"
+            ),
+            "|---|---:|---:|---:|---:|---:|---:|---:|",
+        )
+    )
+    now = datetime.now(UTC)
+    lines.extend(
+        (
+            f"| {markdown_escape(row.skill)} | {row.self_invocations} | "
+            f"{row.requested_invocations} | {row.ambiguous_invocations} | "
+            f"{row.root_self_invocations} | {row.subagent_self_invocations} | "
+            f"{row.sessions} | {format_relative_age(row.last_used, now=now)} |"
+        )
+        for row in report.skills
+    )
+
+    if details:
+        lines.extend(
+            (
+                "",
+                "## Invocation evidence",
+                "",
+                "| Timestamp | Skill | Classification | Agent | Session | Evidence |",
+                "|---|---|---|---|---|---|",
+            )
+        )
+        lines.extend(
+            (
+                f"| {markdown_escape(invocation.timestamp)} | "
+                f"{markdown_escape(invocation.skill)} | {invocation.classification} | "
+                f"{invocation.agent} | {markdown_escape(invocation.session_id)} | "
+                f"{markdown_escape(invocation.evidence)} |"
+            )
+            for invocation in sorted(report.invocations, key=lambda item: item.timestamp)
+        )
+    return "\n".join(lines) + "\n"
+
+
+def render_json(report: ScanReport) -> str:
+    """Return the complete report as structured JSON."""
+    return (
+        json.dumps(
+            {
+                "codex_home": report.codex_home,
+                "stats": asdict(report.stats),
+                "skills": [asdict(skill) for skill in report.skills],
+                "invocations": [asdict(invocation) for invocation in report.invocations],
+            },
+            indent=2,
+            ensure_ascii=False,
+        )
+        + "\n"
+    )
+
+
+def render_csv(report: ScanReport) -> str:
+    """Return aggregate skill counts as CSV."""
+    output = StringIO(newline="")
+    fieldnames = (
+        "skill",
+        "self_invocations",
+        "requested_invocations",
+        "ambiguous_invocations",
+        "root_self_invocations",
+        "subagent_self_invocations",
+        "sessions",
+        "last_used",
+        "availability",
+    )
+    writer = csv.DictWriter(output, fieldnames=fieldnames)
+    writer.writeheader()
+    writer.writerows(asdict(skill) for skill in report.skills)
+    return output.getvalue()
+
+
+def markdown_escape(value: str) -> str:
+    """Escape cell delimiters and newlines for Markdown tables."""
+    return value.replace("|", "\\|").replace("\n", " ")
+
+
+def format_relative_age(timestamp: str, *, now: datetime) -> str:
+    """Format an RFC 3339 timestamp as a compact age in days or years."""
+    if not timestamp:
+        return "—"
+
+    used_at = datetime.fromisoformat(timestamp)
+    if used_at.tzinfo is None:
+        used_at = used_at.replace(tzinfo=UTC)
+    days = max(0, (now - used_at).days)
+    if days < 1:
+        return "<1d"
+    if days < DAYS_PER_YEAR:
+        return f"{days}d"
+    return f"{days // DAYS_PER_YEAR}y"

codex_skill_report-0.1.0/src/codex_skill_report/scanner.py

@@ -0,0 +1,526 @@
+"""Discover Codex transcripts and infer skill invocations."""
+
+from __future__ import annotations
+
+import json
+import re
+import sqlite3
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+from codex_skill_report.models import (
+    AgentKind,
+    Availability,
+    Classification,
+    Invocation,
+    ScanReport,
+    ScanStats,
+    SkillSummary,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable, Iterator
+
+SKILL_REFERENCE_RE = re.compile(
+    r"(?:skill|file)://[^\s\"'`]+(?:/|\\)SKILL\.md"
+    r"|(?:[A-Za-z]:[\\/]|/|~[\\/]|\.{1,2}[\\/])"
+    r"(?:[^\"'\r\n;|&<>])*?(?:/|\\)SKILL\.md",
+    re.IGNORECASE,
+)
+READ_COMMAND_RE = re.compile(
+    r"\b(?:cat|sed|head|tail|less|more|bat|awk|perl|rg|grep|"
+    r"get-content|read_file|read_text_file|open_text_file)\b",
+    re.IGNORECASE,
+)
+CONTENT_READ_API_RE = re.compile(
+    r"(?:\.read_text\s*\(|\bFile\.read\s*\(|\breadFile(?:Sync)?\s*\()",
+    re.IGNORECASE,
+)
+EXPLICIT_VERB_RE = re.compile(
+    r"\b(?:use|using|invoke|invoking|run|running|apply|applying|load|loading|"
+    r"activate|activating)\b",
+    re.IGNORECASE,
+)
+EXPLICIT_VERB_DISTANCE = 35
+
+
+class CodexHomeNotFoundError(FileNotFoundError):
+    """Raised when the selected Codex home directory does not exist."""
+
+
+@dataclass(slots=True)
+class _TranscriptState:
+    session_id: str
+    agent: AgentKind = "root"
+    current_turn: str = "unknown"
+    current_user_text: str = ""
+    pending_user_messages: list[str] = field(default_factory=list)
+    seen: set[tuple[str, str]] = field(default_factory=set)
+
+
+@dataclass(slots=True)
+class _SummaryAccumulator:
+    display_name: str
+    self_invocations: int = 0
+    requested_invocations: int = 0
+    ambiguous_invocations: int = 0
+    root_self_invocations: int = 0
+    subagent_self_invocations: int = 0
+    sessions: set[str] = field(default_factory=set)
+    last_used: str = ""
+    managed_source: bool = False
+
+
+def discover_transcripts(codex_home: Path) -> list[Path]:
+    """Find retained active, archived, and catalogued transcript files."""
+    paths: set[Path] = set()
+    for directory_name in ("sessions", "archived_sessions"):
+        directory = codex_home / directory_name
+        if directory.is_dir():
+            paths.update(path.resolve() for path in directory.rglob("*.jsonl"))
+
+    sqlite_dir = codex_home / "sqlite"
+    if sqlite_dir.is_dir():
+        for database in sqlite_dir.glob("state_*.sqlite"):
+            try:
+                uri = f"{database.resolve().as_uri()}?mode=ro"
+                with sqlite3.connect(uri, uri=True) as connection:
+                    rows = connection.execute("SELECT rollout_path FROM threads").fetchall()
+            except (sqlite3.Error, OSError):
+                continue
+            for (raw_path,) in rows:
+                if not raw_path:
+                    continue
+                path = Path(raw_path).expanduser()
+                if not path.is_absolute():
+                    path = codex_home / path
+                if path.is_file():
+                    paths.add(path.resolve())
+
+    return sorted(paths)
+
+
+def managed_skill_roots(
+    codex_home: Path,
+    *,
+    user_home: Path | None = None,
+) -> tuple[Path, ...]:
+    """Return roots managed by the user or Codex, excluding project folders."""
+    home = user_home or Path.home()
+    return (
+        home / ".agents" / "skills",
+        codex_home / "skills",
+        codex_home / "plugins" / "cache",
+    )
+
+
+def discover_installed_skills(roots: Iterable[Path]) -> set[str]:
+    """Return canonical skill names installed under managed roots."""
+    return {
+        canonical_skill_name(str(skill_file)).casefold()
+        for root in roots
+        if root.is_dir()
+        for skill_file in root.rglob("SKILL.md")
+    }
+
+
+def reference_is_managed(reference: str, roots: Iterable[Path]) -> bool:
+    """Return whether historical evidence points inside a managed skill root."""
+    normalized = reference.removeprefix("file://").replace("\\", "/")
+    return any(normalized.startswith(f"{root.as_posix().rstrip('/')}/") for root in roots)
+
+
+def text_from_message(payload: dict[str, Any]) -> str:
+    content = payload.get("content")
+    if isinstance(content, str):
+        return content
+    if not isinstance(content, list):
+        return ""
+
+    parts: list[str] = []
+    for item in content:
+        if isinstance(item, str):
+            parts.append(item)
+        elif isinstance(item, dict):
+            text = item.get("text")
+            if isinstance(text, str):
+                parts.append(text)
+    return "\n".join(parts)
+
+
+def stringify_call_input(payload: dict[str, Any]) -> str:
+    value = payload.get("arguments")
+    if value is None:
+        value = payload.get("input")
+    if isinstance(value, str):
+        return value
+    if value is None:
+        return ""
+    try:
+        return json.dumps(value, ensure_ascii=False)
+    except (TypeError, ValueError):
+        return str(value)
+
+
+def is_read_call(tool_name: str, call_input: str) -> bool:
+    name = tool_name.casefold()
+    input_lower = call_input.casefold()
+    if "apply_patch" in name or "apply_patch" in input_lower or name.endswith("write_file"):
+        return False
+    if "skill" in name and any(word in name for word in ("read", "fetch", "load")):
+        return True
+    if any(word in name for word in ("read_file", "read_text", "open_file")):
+        return True
+    return bool(READ_COMMAND_RE.search(call_input) or CONTENT_READ_API_RE.search(call_input))
+
+
+def extract_skill_references(call_input: str) -> set[str]:
+    references: set[str] = set()
+    for match in SKILL_REFERENCE_RE.finditer(call_input.replace("\\/", "/")):
+        reference = match.group(0).strip()
+        reference = re.sub(r"^.*?((?:skill|file)://)", r"\1", reference)
+        references.add(reference)
+    return references
+
+
+def canonical_skill_name(reference: str) -> str:
+    normalized = reference.replace("\\", "/").rstrip("/ ")
+
+    plugin_match = re.search(
+        r"/plugins/cache/[^/]+/([^/]+)/[^/]+/skills/([^/]+)/SKILL\.md$",
+        normalized,
+        re.IGNORECASE,
+    )
+    if plugin_match:
+        return f"{plugin_match.group(1)}:{plugin_match.group(2)}"
+
+    plugin_match = re.search(
+        r"/plugins/([^/]+)/skills/([^/]+)/SKILL\.md$",
+        normalized,
+        re.IGNORECASE,
+    )
+    if plugin_match:
+        return f"{plugin_match.group(1)}:{plugin_match.group(2)}"
+
+    skill_match = re.search(
+        r"/(?:\.agents|\.codex|vendor_imports)/skills/(?:\.system/)?([^/]+)/SKILL\.md$",
+        normalized,
+        re.IGNORECASE,
+    )
+    if skill_match:
+        return skill_match.group(1)
+
+    generic_match = re.search(r"/skills/([^/]+)/SKILL\.md$", normalized, re.IGNORECASE)
+    if generic_match:
+        return generic_match.group(1)
+
+    return normalized.rsplit("/", maxsplit=2)[-2]
+
+
+def expand_skill_reference(reference: str) -> list[str]:
+    brace_match = re.search(r"/\{([^{}]+)\}/SKILL\.md$", reference, re.IGNORECASE)
+    if brace_match:
+        alternatives = [item.strip() for item in brace_match.group(1).split(",")]
+        return [
+            reference[: brace_match.start(1) - 1]
+            + alternative
+            + reference[brace_match.end(1) + 1 :]
+            for alternative in alternatives
+            if alternative
+        ]
+    if any(character in reference for character in ("*", "?", "[")):
+        return []
+    return [reference]
+
+
+def alias_pattern(alias: str) -> re.Pattern[str]:
+    return re.compile(rf"(?<![\w-]){re.escape(alias)}(?![\w-])", re.IGNORECASE)
+
+
+def classify_invocation(user_text: str, skill: str) -> Classification:
+    aliases = {skill, skill.rsplit(":", 1)[-1]}
+    text = user_text.casefold()
+    mentioned = False
+
+    for alias in aliases:
+        alias_lower = alias.casefold()
+        if re.search(rf"(?:\$|/skills?:){re.escape(alias_lower)}(?![\w-])", text):
+            return "requested"
+
+        for match in alias_pattern(alias_lower).finditer(text):
+            mentioned = True
+            before = text[max(0, match.start() - 80) : match.start()]
+            after = text[match.end() : match.end() + 24]
+            last_verb = None
+            for verb_match in EXPLICIT_VERB_RE.finditer(before):
+                last_verb = verb_match
+            if last_verb and len(before) - last_verb.end() <= EXPLICIT_VERB_DISTANCE:
+                return "requested"
+            if re.match(r"\s+skill\b", after) and EXPLICIT_VERB_RE.search(before[-60:]):
+                return "requested"
+
+    return "ambiguous" if mentioned else "self"
+
+
+def session_is_subagent(payload: dict[str, Any]) -> bool:
+    if payload.get("thread_source") == "subagent" or payload.get("parent_thread_id"):
+        return True
+    source = payload.get("source")
+    return isinstance(source, dict) and "subagent" in source
+
+
+def joined_user_messages(messages: Iterable[str]) -> str:
+    unique: list[str] = []
+    for message in messages:
+        if message and message not in unique:
+            unique.append(message)
+    return "\n".join(unique)
+
+
+def transcript_records(path: Path, stats: ScanStats) -> Iterator[tuple[int, dict[str, Any]]]:
+    try:
+        lines = path.open(encoding="utf-8")
+    except OSError:
+        stats.unreadable_sessions += 1
+        return
+
+    with lines:
+        for line_number, line in enumerate(lines, start=1):
+            try:
+                record = json.loads(line)
+            except (json.JSONDecodeError, UnicodeDecodeError):
+                stats.malformed_lines += 1
+                continue
+            if isinstance(record, dict):
+                yield line_number, record
+
+
+def apply_context_event(
+    record: dict[str, Any],
+    payload: dict[str, Any],
+    state: _TranscriptState,
+    line_number: int,
+) -> bool:
+    record_type = record.get("type")
+    payload_type = payload.get("type")
+
+    if record_type == "session_meta":
+        state.session_id = str(payload.get("id") or payload.get("session_id") or state.session_id)
+        state.agent = "subagent" if session_is_subagent(payload) else "root"
+        return True
+
+    if record_type == "response_item" and payload_type == "message":
+        if payload.get("role") == "user":
+            message = text_from_message(payload)
+            if message:
+                state.pending_user_messages.append(message)
+        return True
+
+    if record_type == "event_msg" and payload_type == "user_message":
+        message = payload.get("message")
+        if isinstance(message, str) and message:
+            state.pending_user_messages.append(message)
+        return True
+
+    if record_type == "event_msg" and payload_type == "task_started":
+        state.current_turn = str(payload.get("turn_id") or f"line-{line_number}")
+        state.current_user_text = joined_user_messages(state.pending_user_messages)
+        state.pending_user_messages.clear()
+        return True
+
+    if record_type == "turn_context":
+        state.current_turn = str(payload.get("turn_id") or state.current_turn)
+        if state.pending_user_messages:
+            state.current_user_text = joined_user_messages(state.pending_user_messages)
+            state.pending_user_messages.clear()
+        return True
+
+    return False
+
+
+def invocations_from_tool_call(
+    record: dict[str, Any],
+    payload: dict[str, Any],
+    state: _TranscriptState,
+    path: Path,
+    stats: ScanStats,
+) -> list[Invocation]:
+    if record.get("type") != "response_item" or payload.get("type") not in {
+        "function_call",
+        "custom_tool_call",
+    }:
+        return []
+
+    call_input = stringify_call_input(payload)
+    if not is_read_call(str(payload.get("name") or ""), call_input):
+        return []
+
+    if state.pending_user_messages:
+        state.current_user_text = joined_user_messages(state.pending_user_messages)
+        state.pending_user_messages.clear()
+
+    invocations: list[Invocation] = []
+    for raw_reference in extract_skill_references(call_input):
+        references = expand_skill_reference(raw_reference)
+        if not references:
+            stats.unattributed_skill_reads += 1
+            continue
+        for reference in references:
+            skill = canonical_skill_name(reference)
+            dedupe_key = (state.current_turn, skill.casefold())
+            if dedupe_key in state.seen:
+                continue
+            state.seen.add(dedupe_key)
+            invocations.append(
+                Invocation(
+                    skill=skill,
+                    classification=classify_invocation(state.current_user_text, skill),
+                    agent=state.agent,
+                    session_id=state.session_id,
+                    turn_id=state.current_turn,
+                    timestamp=str(record.get("timestamp") or ""),
+                    transcript=str(path),
+                    evidence=raw_reference,
+                )
+            )
+    return invocations
+
+
+def scan_transcript(path: Path, stats: ScanStats) -> list[Invocation]:
+    """Scan one JSONL transcript and return deduplicated skill invocations."""
+    stats.sessions_scanned += 1
+    state = _TranscriptState(session_id=path.stem)
+    invocations: list[Invocation] = []
+
+    for line_number, record in transcript_records(path, stats):
+        payload = record.get("payload")
+        if not isinstance(payload, dict):
+            continue
+        if apply_context_event(record, payload, state, line_number):
+            continue
+        invocations.extend(invocations_from_tool_call(record, payload, state, path, stats))
+
+    return invocations
+
+
+def deduplicate_replayed_invocations(
+    invocations: Iterable[Invocation],
+) -> tuple[tuple[Invocation, ...], int]:
+    """Collapse forked transcript replays of the same session turn and skill."""
+    unique: dict[tuple[str, str, str], Invocation] = {}
+    duplicates = 0
+
+    for invocation in invocations:
+        key = (
+            invocation.session_id,
+            invocation.turn_id.casefold(),
+            invocation.skill.casefold(),
+        )
+        existing = unique.get(key)
+        if existing is None:
+            unique[key] = invocation
+            continue
+
+        duplicates += 1
+        if invocation.timestamp and (
+            not existing.timestamp or invocation.timestamp < existing.timestamp
+        ):
+            unique[key] = invocation
+
+    return tuple(unique.values()), duplicates
+
+
+def aggregate(
+    invocations: Iterable[Invocation],
+    installed_skills: set[str],
+    roots: tuple[Path, ...],
+) -> tuple[SkillSummary, ...]:
+    """Aggregate invocation events by case-insensitive canonical skill name."""
+    rows: dict[str, _SummaryAccumulator] = {}
+
+    for invocation in invocations:
+        key = invocation.skill.casefold()
+        row = rows.setdefault(key, _SummaryAccumulator(display_name=invocation.skill))
+        if invocation.classification == "self":
+            row.self_invocations += 1
+            if invocation.agent == "root":
+                row.root_self_invocations += 1
+            else:
+                row.subagent_self_invocations += 1
+        elif invocation.classification == "requested":
+            row.requested_invocations += 1
+        else:
+            row.ambiguous_invocations += 1
+        row.sessions.add(invocation.session_id)
+        row.last_used = max(row.last_used, invocation.timestamp)
+        row.managed_source = row.managed_source or reference_is_managed(
+            invocation.evidence,
+            roots,
+        )
+
+    result = [
+        SkillSummary(
+            skill=row.display_name,
+            self_invocations=row.self_invocations,
+            requested_invocations=row.requested_invocations,
+            ambiguous_invocations=row.ambiguous_invocations,
+            root_self_invocations=row.root_self_invocations,
+            subagent_self_invocations=row.subagent_self_invocations,
+            sessions=len(row.sessions),
+            last_used=row.last_used,
+            availability=skill_availability(
+                row.display_name,
+                installed_skills,
+                managed_source=row.managed_source,
+            ),
+        )
+        for row in rows.values()
+    ]
+
+    return tuple(
+        sorted(
+            result,
+            key=lambda row: (
+                -row.self_invocations,
+                -row.requested_invocations,
+                -row.ambiguous_invocations,
+                row.skill.casefold(),
+            ),
+        )
+    )
+
+
+def skill_availability(
+    skill: str,
+    installed_skills: set[str],
+    *,
+    managed_source: bool,
+) -> Availability:
+    """Classify availability without inspecting repository-local folders."""
+    if skill.casefold() in installed_skills:
+        return "installed"
+    return "removed" if managed_source else "unknown"
+
+
+def scan_codex_home(codex_home: Path, *, user_home: Path | None = None) -> ScanReport:
+    """Scan every retained transcript reachable from a Codex home directory."""
+    resolved_home = codex_home.expanduser().resolve()
+    if not resolved_home.is_dir():
+        message = f"Codex home does not exist: {resolved_home}"
+        raise CodexHomeNotFoundError(message)
+
+    stats = ScanStats()
+    invocations: list[Invocation] = []
+    for transcript in discover_transcripts(resolved_home):
+        invocations.extend(scan_transcript(transcript, stats))
+
+    unique_invocations, duplicates = deduplicate_replayed_invocations(invocations)
+    stats.replayed_invocations_deduplicated = duplicates
+    roots = managed_skill_roots(resolved_home, user_home=user_home)
+    return ScanReport(
+        codex_home=str(resolved_home),
+        stats=stats,
+        skills=aggregate(unique_invocations, discover_installed_skills(roots), roots),
+        invocations=unique_invocations,
+    )