skillrunes 0.1.0__py3-none-any.whl

skillrunes/__init__.py

@@ -0,0 +1,3 @@
+"""SkillRunes — analyze coding-agent transcripts and recursively improve a SKILL.md file."""
+
+__version__ = "0.1.0"

skillrunes/__main__.py

@@ -0,0 +1,11 @@
+"""Entry point for `python -m skillrunes` and the `skillrunes` console script."""
+
+
+def main() -> None:
+    """Invoke the Typer CLI application."""
+    from skillrunes.cli import app
+    app()
+
+
+if __name__ == "__main__":
+    main()

skillrunes/cli.py

@@ -0,0 +1,367 @@
+"""Typer CLI commands for SkillRunes.
+
+Three commands:
+  skillrunes init       — initialise the .skillrunes/ store for this project
+  skillrunes run        — analyse new sessions and update SKILL.md
+  skillrunes visualize  — launch the local observability dashboard
+
+No model calls are made from this module.  Extraction is delegated to
+extract.py and synthesize.py.  All file I/O is delegated to store.py.
+"""
+
+import webbrowser
+from pathlib import Path
+
+import typer
+from dotenv import load_dotenv
+from rich.console import Console
+from rich.panel import Panel
+from rich.progress import BarColumn, Progress, SpinnerColumn, TextColumn
+from rich.rule import Rule
+from rich.syntax import Syntax
+
+import skillrunes.store as store
+from skillrunes.config import DEFAULT_PROVIDER, PROVIDER_ENV_VAR, SUPPORTED_PROVIDERS
+from skillrunes.extract import analyze_session
+from skillrunes.ingest import get_provider
+from skillrunes.ingest.base import ProviderNotImplementedError
+from skillrunes.synthesize import generate_skill_file
+from skillrunes.utils import compute_metrics, render_skill_diff
+
+load_dotenv()
+
+console = Console()
+err_console = Console(stderr=True)
+
+app = typer.Typer(
+    name="skillrunes",
+    help="Analyse coding-agent sessions and recursively improve a SKILL.md file.",
+    no_args_is_help=True,
+)
+
+
+# ---------------------------------------------------------------------------
+# init
+# ---------------------------------------------------------------------------
+
+@app.command()
+def init() -> None:
+    """Initialise the .skillrunes/ store for the current project."""
+    cwd = Path.cwd()
+    store_path = cwd / ".skillrunes"
+
+    store.init_store()
+
+    console.print(
+        Panel(
+            f"[green]Initialised[/green] [bold]{store_path}[/bold]\n\n"
+            "Next steps:\n"
+            "  1. Copy [bold].env.example[/bold] → [bold].env[/bold] and set "
+            "[bold]ANTHROPIC_API_KEY[/bold]\n"
+            "     (or skip this step — SkillRunes will fall back to the Claude CLI)\n"
+            "  2. Run [bold]skillrunes run[/bold] to analyse sessions and generate SKILL.md",
+            title="SkillRunes initialised",
+            border_style="green",
+        )
+    )
+
+
+# ---------------------------------------------------------------------------
+# run
+# ---------------------------------------------------------------------------
+
+@app.command()
+def run(
+    dry_run: bool = typer.Option(
+        False, "--dry-run", help="Show what would change without writing any files."
+    ),
+    provider_name: str | None = typer.Option(
+        None,
+        "--provider",
+        help=(
+            "Transcript provider to use "
+            f"({', '.join(SUPPORTED_PROVIDERS)}). "
+            f"Defaults to ${PROVIDER_ENV_VAR} or {DEFAULT_PROVIDER}."
+        ),
+    ),
+) -> None:
+    """Analyse new sessions and update SKILL.md."""
+
+    # ── 1. Resolve and display cwd immediately ───────────────────────────────
+    cwd = Path.cwd()
+    console.print(Rule(f"[bold]SkillRunes[/bold]  •  {cwd}", style="dim"))
+    try:
+        provider = get_provider(provider_name)
+    except ValueError as exc:
+        err_console.print(f"[red]Error:[/red] {exc}")
+        raise typer.Exit(1) from exc
+
+    console.print(
+        f"[dim]Active provider:[/dim] [bold]{provider.display_name}[/bold] "
+        f"[dim]({provider.name})[/dim]"
+    )
+    if dry_run:
+        console.print("[yellow]Dry run — no files will be written.[/yellow]\n")
+
+    # ── 2. Ensure store is initialised ───────────────────────────────────────
+    store.init_store()
+
+    # ── 3. Find new sessions ─────────────────────────────────────────────────
+    console.print(f"[dim]Scanning sessions for:[/dim] [bold]{cwd}[/bold]")
+    try:
+        new_session_paths = provider.find_new_sessions(cwd)
+    except ProviderNotImplementedError as exc:
+        err_console.print(f"[red]Error:[/red] {exc}")
+        raise typer.Exit(1) from exc
+
+    if not new_session_paths:
+        console.print(
+            "\n[yellow]No new sessions found for this directory.[/yellow]\n"
+            "Are you running [bold]skillrunes run[/bold] from the right project folder?\n"
+            f"Expected transcripts in: [dim]{provider.expected_location(cwd)}[/dim]"
+        )
+        raise typer.Exit(0)
+
+    console.print(
+        f"Found [bold green]{len(new_session_paths)}[/bold green] new "
+        f"{'session' if len(new_session_paths) == 1 else 'sessions'} to analyse.\n"
+    )
+
+    # ── 4. Parse + archive + extract each session ────────────────────────────
+    new_summaries = []
+
+    with Progress(
+        SpinnerColumn(),
+        TextColumn("[progress.description]{task.description}"),
+        BarColumn(),
+        TextColumn("[progress.percentage]{task.percentage:>3.0f}%"),
+        console=console,
+        transient=True,
+    ) as progress:
+        task = progress.add_task("Analysing sessions…", total=len(new_session_paths))
+
+        for path in new_session_paths:
+            sid = provider.session_id_from_path(path)
+            progress.update(task, description=f"Analysing [dim]{sid[:8]}…[/dim]")
+
+            messages, raw_lines = provider.parse_session_file(path)
+
+            if not messages:
+                progress.advance(task)
+                console.print(
+                    f"  [yellow]Skipped[/yellow] {sid[:8]}… — no messages after filtering"
+                )
+                continue
+
+            # Archive raw lines before any model call so originals are preserved
+            # even if the provider later deletes or rotates the transcript.
+            if not dry_run:
+                store.archive_raw_session(sid, raw_lines)
+
+            try:
+                summary = analyze_session(messages, sid, raw_lines)
+            except Exception as exc:
+                err_console.print(
+                    f"  [red]Error[/red] extracting {sid[:8]}…: {exc}"
+                )
+                progress.advance(task)
+                continue
+
+            new_summaries.append(summary)
+
+            # Show a summary panel for each extracted session
+            _print_session_panel(summary)
+            progress.advance(task)
+
+    if not new_summaries:
+        console.print("[yellow]No sessions were successfully extracted.[/yellow]")
+        raise typer.Exit(1)
+
+    # ── 5. Synthesise updated skill file ─────────────────────────────────────
+    console.print()
+    console.print("[dim]Synthesising SKILL.md…[/dim]")
+
+    current_skill_version = store.load_current_skill()
+    current_skill_content = current_skill_version.content if current_skill_version else None
+
+    try:
+        new_skill_content, change_summary = generate_skill_file(
+            new_summaries, current_skill_content
+        )
+    except Exception as exc:
+        err_console.print(f"[red]Error[/red] synthesising SKILL.md: {exc}")
+        raise typer.Exit(1) from exc
+
+    # ── 6. Show diff ─────────────────────────────────────────────────────────
+    _print_skill_diff(current_skill_content, new_skill_content, current_skill_version)
+
+    # ── 7. Persist (skipped on --dry-run) ────────────────────────────────────
+    if dry_run:
+        console.print(
+            "\n[yellow]Dry run — nothing written.[/yellow] "
+            "Remove [bold]--dry-run[/bold] to save."
+        )
+        raise typer.Exit(0)
+
+    # Save session summaries and updated metrics
+    for summary in new_summaries:
+        store.save_session_summary(summary)
+
+    all_summaries = store.load_all_summaries()
+    store.save_metrics(compute_metrics(all_summaries))
+
+    # Save new skill version (archives to .skillrunes/skills/ then writes SKILL.md)
+    skill_version = store.save_skill_version(new_skill_content, change_summary)
+    console.print(
+        f"\n[green]✓[/green] SKILL.md written "
+        f"([bold]v{skill_version.version}[/bold]  •  {len(new_skill_content)} chars)"
+    )
+
+    # ── 8. Auto-copy to provider-specific skill location when supported ──────
+    if provider.name == "claude_code":
+        _sync_to_claude_dir(cwd, new_skill_content, dry_run=False)
+
+
+# ---------------------------------------------------------------------------
+# visualize
+# ---------------------------------------------------------------------------
+
+@app.command()
+def visualize() -> None:
+    """Launch the local observability dashboard on http://localhost:4823."""
+    try:
+        import uvicorn
+    except ImportError:
+        err_console.print(
+            "[red]Error:[/red] uvicorn is not installed. "
+            "Run [bold]pip install skillrunes[/bold] to install all dependencies."
+        )
+        raise typer.Exit(1)
+
+    from skillrunes.config import DASHBOARD_HOST, DASHBOARD_PORT
+
+    store.init_store()
+
+    url = f"http://{DASHBOARD_HOST}:{DASHBOARD_PORT}"
+    console.print(
+        Panel(
+            f"Dashboard starting at [bold cyan]{url}[/bold cyan]\n"
+            "Press [bold]Ctrl+C[/bold] to stop.",
+            title="SkillRunes Dashboard",
+            border_style="cyan",
+        )
+    )
+
+    webbrowser.open(url)
+
+    try:
+        uvicorn.run(
+            "skillrunes.dashboard.server:app",
+            host=DASHBOARD_HOST,
+            port=DASHBOARD_PORT,
+            log_level="warning",
+        )
+    except OSError as exc:
+        if "address already in use" in str(exc).lower():
+            err_console.print(
+                f"[red]Error:[/red] Port {DASHBOARD_PORT} is already in use. "
+                "Kill the existing process or change DASHBOARD_PORT in config.py."
+            )
+            raise typer.Exit(1) from exc
+        raise
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+def _print_session_panel(summary: "SessionSummary") -> None:  # type: ignore[name-defined]
+    lines: list[str] = [
+        f"[dim]Session:[/dim] {summary.session_id[:8]}…",
+        f"[dim]Goal:[/dim]    {summary.goal}",
+        f"[dim]Tokens:[/dim]  {summary.token_count:,}  "
+        f"[dim]Duration:[/dim] {summary.duration_seconds:.0f}s  "
+        f"[dim]Messages:[/dim] {summary.message_count}",
+    ]
+    if summary.what_worked:
+        lines.append(
+            "[green]✓ Worked:[/green] " + "; ".join(summary.what_worked[:2])
+            + ("…" if len(summary.what_worked) > 2 else "")
+        )
+    if summary.what_failed:
+        lines.append(
+            "[red]✗ Failed:[/red] " + "; ".join(summary.what_failed[:2])
+            + ("…" if len(summary.what_failed) > 2 else "")
+        )
+    if summary.patterns:
+        lines.append(
+            "[cyan]◆ Pattern:[/cyan] " + summary.patterns[0]
+            + (f" (+{len(summary.patterns) - 1} more)" if len(summary.patterns) > 1 else "")
+        )
+    console.print(Panel("\n".join(lines), border_style="dim"))
+
+
+def _print_skill_diff(
+    old_content: str | None,
+    new_content: str,
+    current_version: "SkillVersion | None",  # type: ignore[name-defined]
+) -> None:
+    if old_content is None:
+        console.print(
+            Panel(
+                f"[green]New SKILL.md will be created[/green] "
+                f"({len(new_content)} chars)",
+                title="SKILL.md  •  v1 (new)",
+                border_style="green",
+            )
+        )
+        return
+
+    version_num = (current_version.version + 1) if current_version else 1
+    diff_text = render_skill_diff(old_content, new_content, version_num)
+
+    if not diff_text.strip():
+        console.print("[dim]No changes to SKILL.md.[/dim]")
+        return
+
+    # Render unified diff with colour using Rich Syntax
+    syntax = Syntax(diff_text, "diff", theme="monokai", line_numbers=False)
+    console.print(
+        Panel(
+            syntax,
+            title=f"SKILL.md diff  •  v{version_num - 1} → v{version_num}",
+            border_style="blue",
+        )
+    )
+
+
+def _sync_to_claude_dir(cwd: Path, skill_content: str, *, dry_run: bool) -> None:
+    """Copy SKILL.md to .claude/SKILL.md if the .claude/ directory exists.
+
+    This closes the product loop: SKILL.md is generated → Claude Code loads it
+    on the next session automatically without the user having to do anything.
+
+    If .claude/ does not exist, print a tip explaining how to enable this.
+    """
+    claude_dir = cwd / ".claude"
+
+    if not claude_dir.is_dir():
+        console.print(
+            "\n[dim]Tip:[/dim] Create a [bold].claude/[/bold] folder in your project root "
+            "and SkillRunes will automatically place SKILL.md there for Claude Code to load."
+        )
+        return
+
+    if dry_run:
+        console.print(
+            f"\n[dim]Dry run:[/dim] would copy SKILL.md → "
+            f"[bold]{claude_dir / 'SKILL.md'}[/bold]"
+        )
+        return
+
+    dest = claude_dir / "SKILL.md"
+    dest.write_text(skill_content, encoding="utf-8")
+    console.print(
+        f"[green]✓[/green] Copied SKILL.md → [bold]{dest}[/bold]  "
+        f"[dim](Claude Code will load this on the next session)[/dim]"
+    )

skillrunes/client.py

@@ -0,0 +1,283 @@
+"""Unified model client abstraction for SkillRunes.
+
+Two execution paths, selected at call time based on environment:
+
+  SDK path (ANTHROPIC_API_KEY present in environment):
+    Uses anthropic.Anthropic() directly.
+    extract_structured() → tool_use with forced tool_choice.
+    generate_text()      → messages.create, returns text content.
+
+  Subprocess path (no ANTHROPIC_API_KEY):
+    Invokes `claude --print` using Claude Code's own authentication
+    (OAuth / keychain — whatever Claude Code is logged in as).
+    extract_structured() → --json-schema flag for structured output.
+    generate_text()      → plain text output.
+    Both paths show a Rich spinner since output is not streamed.
+
+All modules that need model calls must call get_client() from here and use the
+returned ModelClient.  Never instantiate anthropic.Anthropic() or subprocess.run
+(['claude', ...]) directly from extract.py or synthesize.py.
+"""
+
+import json
+import os
+import shutil
+import subprocess
+from typing import Any
+
+import anthropic
+from anthropic.types import TextBlock, ToolParam
+from dotenv import load_dotenv
+
+from skillrunes.config import MODEL
+
+load_dotenv()
+
+_SUBPROCESS_INSTALL_HINT = (
+    "Claude Code not found in PATH. "
+    "Install it via: npm install -g @anthropic-ai/claude-code"
+)
+
+# Subprocess timeout in seconds — generous for large sessions
+_SUBPROCESS_TIMEOUT = 120
+
+
+class ModelClient:
+    """Wraps SDK or subprocess path behind a single interface.
+
+    Instantiate via get_client() rather than directly, so callers are
+    decoupled from the selection logic.
+    """
+
+    def __init__(self, *, sdk_client: anthropic.Anthropic | None = None) -> None:
+        self._sdk = sdk_client
+
+    @property
+    def mode(self) -> str:
+        return "sdk" if self._sdk is not None else "subprocess"
+
+    # ------------------------------------------------------------------
+    # Structured extraction — used by extract.py
+    # ------------------------------------------------------------------
+
+    def extract_structured(
+        self,
+        system: str,
+        user: str,
+        tool_schema: ToolParam,
+    ) -> dict[str, Any]:
+        """Return a dict matching tool_schema by forcing structured output.
+
+        SDK path:  uses tool_use with tool_choice={"type":"tool","name":"..."}.
+        Subprocess: uses --json-schema with the schema's input_schema section.
+        """
+        if self._sdk is not None:
+            return self._sdk_extract(system, user, tool_schema)
+        return self._subprocess_extract(system, user, tool_schema)
+
+    # ------------------------------------------------------------------
+    # Free-form text generation — used by synthesize.py
+    # ------------------------------------------------------------------
+
+    def generate_text(self, system: str, user: str) -> str:
+        """Return a plain text response.
+
+        SDK path:  messages.create, joins text content blocks.
+        Subprocess: --print with default text output format.
+        """
+        if self._sdk is not None:
+            return self._sdk_generate(system, user)
+        return self._subprocess_generate(system, user)
+
+    # ------------------------------------------------------------------
+    # SDK implementations
+    # ------------------------------------------------------------------
+
+    def _sdk_extract(
+        self,
+        system: str,
+        user: str,
+        tool_schema: ToolParam,
+    ) -> dict[str, Any]:
+        assert self._sdk is not None
+        tool_name: str = tool_schema["name"]  # type: ignore[index]
+        response = self._sdk.messages.create(
+            model=MODEL,
+            max_tokens=2048,
+            system=system,
+            tools=[tool_schema],
+            tool_choice={"type": "tool", "name": tool_name},
+            messages=[{"role": "user", "content": user}],
+        )
+        for block in response.content:
+            if block.type == "tool_use" and block.name == tool_name:
+                return block.input  # type: ignore[return-value]
+        raise ValueError(
+            f"Model did not return a {tool_name!r} tool call. "
+            f"stop_reason={response.stop_reason!r}"
+        )
+
+    def _sdk_generate(self, system: str, user: str) -> str:
+        assert self._sdk is not None
+        response = self._sdk.messages.create(
+            model=MODEL,
+            max_tokens=4096,
+            system=system,
+            messages=[{"role": "user", "content": user}],
+        )
+        parts = [
+            block.text
+            for block in response.content
+            if isinstance(block, TextBlock)
+        ]
+        return "\n".join(parts)
+
+    # ------------------------------------------------------------------
+    # Subprocess implementations
+    # ------------------------------------------------------------------
+
+    def _subprocess_extract(
+        self,
+        system: str,
+        user: str,
+        tool_schema: ToolParam,
+    ) -> dict[str, Any]:
+        """Call claude CLI for structured JSON extraction.
+
+        --system-prompt combined with --json-schema silently returns empty output
+        in some environments.  Instead we embed the system instructions and schema
+        directly into the user message so only the base --print flag is needed.
+        The model is instructed to respond with ONLY a raw JSON object.
+        """
+        input_schema = tool_schema.get("input_schema", {})  # type: ignore[union-attr]
+        schema_str = json.dumps(input_schema, indent=2)
+        combined_input = (
+            f"<instructions>\n{system}\n</instructions>\n\n"
+            f"<json_schema>\n{schema_str}\n</json_schema>\n\n"
+            "IMPORTANT: Respond ONLY with a valid JSON object matching the schema "
+            "above. No prose, no markdown fences, no explanation.\n\n"
+            f"<session_transcript>\n{user}\n</session_transcript>"
+        )
+
+        cmd = ["claude", "--print", "--no-session-persistence"]
+        raw = self._run_subprocess(cmd, stdin_input=combined_input)
+        raw = _strip_markdown_fences(raw)
+
+        try:
+            return json.loads(raw)
+        except json.JSONDecodeError as exc:
+            raise ValueError(
+                f"claude subprocess returned non-JSON output for extraction: {exc}\n"
+                f"Output was: {raw[:300]}"
+            ) from exc
+
+    def _subprocess_generate(self, system: str, user: str) -> str:
+        """Call claude CLI for free-form text generation.
+
+        --system-prompt works reliably here because we do NOT combine it with
+        --json-schema (that combination produces empty output).  The user message
+        is passed via stdin rather than as a positional argument.
+        """
+        cmd = ["claude", "--print", "--no-session-persistence", "--system-prompt", system]
+        return self._run_subprocess(cmd, stdin_input=user)
+
+    def _run_subprocess(
+        self, cmd: list[str], stdin_input: str | None = None
+    ) -> str:
+        """Run a claude CLI command and return stdout text.
+
+        User input is passed via stdin rather than as a positional argument —
+        the claude CLI silently returns empty output when --system-prompt is long
+        and the prompt is a positional argument; stdin always works.
+
+        Claude Code injects CLAUDECODE=1 and related env vars that cause child
+        claude processes to detect nesting and return empty output.  We strip
+        those vars so the subprocess runs as a fresh non-nested call.
+        """
+        _require_claude_in_path()
+
+        clean_env = _subprocess_env()
+
+        try:
+            result = subprocess.run(
+                cmd,
+                input=stdin_input or "",
+                capture_output=True,
+                text=True,
+                timeout=_SUBPROCESS_TIMEOUT,
+                env=clean_env,
+            )
+        except subprocess.TimeoutExpired as exc:
+            raise RuntimeError(
+                f"claude subprocess timed out after {_SUBPROCESS_TIMEOUT}s"
+            ) from exc
+
+        if result.returncode != 0:
+            raise RuntimeError(
+                f"claude subprocess exited with code {result.returncode}.\n"
+                f"stderr: {result.stderr.strip()[:500]}"
+            )
+
+        return result.stdout.strip()
+
+
+# ------------------------------------------------------------------
+# Module-level helpers
+# ------------------------------------------------------------------
+
+def _require_claude_in_path() -> None:
+    if shutil.which("claude") is None:
+        raise EnvironmentError(_SUBPROCESS_INSTALL_HINT)
+
+
+_CLAUDE_CODE_ENV_PREFIXES = (
+    "CLAUDECODE",
+    "CLAUDE_CODE_",
+    "CLAUDE_EFFORT",
+    "AI_AGENT",
+)
+
+
+def _subprocess_env() -> dict[str, str]:
+    """Return os.environ with Claude Code nesting-detection vars stripped.
+
+    When skillrunes is run from inside Claude Code, CLAUDECODE=1 and related
+    vars cause a child `claude --print` process to detect nesting and return
+    empty output.  Clearing them lets the subprocess run as a fresh session.
+    """
+    return {
+        k: v
+        for k, v in os.environ.items()
+        if not any(k.startswith(prefix) for prefix in _CLAUDE_CODE_ENV_PREFIXES)
+    }
+
+
+def _strip_markdown_fences(text: str) -> str:
+    """Remove ```json ... ``` or ``` ... ``` wrappers from model output."""
+    stripped = text.strip()
+    if stripped.startswith("```"):
+        lines = stripped.splitlines()
+        # Drop first line (``` or ```json) and last line (```)
+        inner = lines[1:-1] if lines[-1].strip() == "```" else lines[1:]
+        return "\n".join(inner).strip()
+    return stripped
+
+
+def get_client() -> ModelClient:
+    """Return a ModelClient using the best available auth method.
+
+    Prefers the SDK (ANTHROPIC_API_KEY) for reliability and full feature
+    support.  Falls back to the claude CLI subprocess if no key is set.
+    """
+    api_key = os.environ.get("ANTHROPIC_API_KEY", "").strip()
+    if api_key:
+        sdk = anthropic.Anthropic(api_key=api_key)
+        return ModelClient(sdk_client=sdk)
+
+    # No API key — fall back to Claude Code CLI subprocess
+    _require_claude_in_path()  # fail fast with a clear message
+    return ModelClient(sdk_client=None)
+
+
+# Convenience alias for callers that prefer the product-specific name.
+SkillRunesClient = ModelClient

skillrunes/config.py

@@ -0,0 +1,31 @@
+"""Central configuration constants for SkillRunes.
+
+Provider names, model names, paths, and tuneable thresholds live here so
+nothing is hardcoded elsewhere in the codebase.
+"""
+
+# Transcript provider selection
+PROVIDER_ENV_VAR = "SKILLRUNES_PROVIDER"
+DEFAULT_PROVIDER = "claude_code"
+SUPPORTED_PROVIDERS = ("claude_code", "codex")
+
+# Claude model used for all API calls.  Update here to change globally.
+MODEL = "claude-sonnet-4-20250514"
+
+# Local dashboard server settings
+DASHBOARD_HOST = "127.0.0.1"
+DASHBOARD_PORT = 4823
+
+# Hidden state directory written inside the current project
+STORE_DIR_NAME = ".skillrunes"
+
+# Sessions with more messages than this are split into chunks before analysis
+MAX_MESSAGES_PER_CHUNK = 200
+
+# Root folder where Claude Code writes session transcripts
+CLAUDE_PROJECTS_ROOT = "~/.claude/projects"
+
+# Known local Codex transcript roots.  The directory may exist before a stable
+# JSONL transcript format is available, so CodexProvider still raises a clear
+# not-implemented error until parsing support is added.
+CODEX_SESSION_ROOTS = ("~/.codex/sessions", "~/.Codex/sessions", "~/.Codex/projects")