claude-scrollback 0.1.0__tar.gz

claude_scrollback-0.1.0/PKG-INFO

@@ -0,0 +1,202 @@
+Metadata-Version: 2.4
+Name: claude-scrollback
+Version: 0.1.0
+Summary: Lightweight viewer for Claude Code session transcripts
+License-Expression: MIT
+Keywords: claude,anthropic,claude-code,ai,transcript,viewer
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Environment :: Web Environment
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Utilities
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Provides-Extra: build
+Requires-Dist: build; extra == "build"
+Requires-Dist: twine; extra == "build"
+
+# claude-scrollback
+
+A lightweight viewer for [Claude Code](https://claude.ai/claude-code) session transcripts. Converts `.jsonl` session files into readable, interactive HTML — with a built-in server for browsing and a static site generator for archiving.
+
+Pure python, no dependencies to install.
+
+**[Live demo →](https://alexdej.github.io/claude-scrollback/)**
+
+## Install
+
+pip (recommended)
+```bash
+pip install claude-scrollback
+```
+
+from source:
+
+```bash
+git clone https://github.com/alexdej/claude-scrollback
+pip install -e claude-scrollback/
+```
+
+Or use `generator.py` standalone:
+
+```bash
+git clone https://github.com/alexdej/claude-scrollback
+python claude-scrollback/claude_scrollback/generator.py <dir>
+```
+
+## Usage
+
+### Quick start
+
+Installation installs a `claude-scrollback` command.
+
+```bash
+# Browse all your Claude Code sessions (uses ~/.claude/projects/ automatically)
+claude-scrollback view
+
+# Browse sessions for the current Claude Code project directory
+claude-scrollback view .
+
+# Browse sessions for a specific project
+claude-scrollback view ~/projects/myapp
+
+# View a single session file
+claude-scrollback view path/to/session.jsonl
+```
+
+All directory modes start a local server and open your browser automatically.
+
+`claude-scrollback` is the command installed by `pip install claude-scrollback`. If you're running from a clone without installing, use `python -m claude_scrollback` in place of `claude-scrollback` throughout. Add a shell alias if you want something shorter:
+
+```bash
+alias sb='claude-scrollback'
+```
+
+### Subcommands
+
+```
+claude-scrollback view [path] [-p PORT] [-n]
+claude-scrollback show [uuid]
+claude-scrollback generate [path] [-o OUTDIR]
+
+view      start a local server and open the session browser
+show      find and open a session by UUID
+generate  generate static HTML from session files
+```
+
+### view
+
+```bash
+claude-scrollback view                        # all projects, port 8080, opens browser
+claude-scrollback view . -p 9000             # current project, custom port
+claude-scrollback view . -n                  # start server without opening browser
+claude-scrollback view session.jsonl         # convert single file, open in browser
+```
+
+Options: `-p/--port PORT` (default: 8080), `-n/--no-open`
+
+### show
+
+Find a session by UUID and open it in the browser. Searches `~/.claude/projects/` automatically.
+
+```bash
+claude-scrollback show abc123de-f456-7890-abcd-ef1234567890
+
+# Pipe in any text containing UUIDs — all matching sessions are opened
+git log --format="%B" | claude-scrollback show
+git show HEAD | claude-scrollback show
+```
+
+### generate
+
+Generate a static HTML site from session files.
+
+```bash
+claude-scrollback generate                        # all projects -> ./_site/
+claude-scrollback generate . -o ~/my-archive/    # current project, custom output dir
+claude-scrollback generate session.jsonl          # single file -> session.html
+```
+
+Options: `-o/--out-dir DIR` (default: `_site/`)
+
+### Path resolution
+
+When you pass a project directory (like `.`), scrollback maps it to the corresponding Claude Code sessions folder automatically. Claude Code stores sessions under `~/.claude/projects/` with the project path encoded as the directory name (colons, slashes, and backslashes replaced with `-`):
+
+```
+~/projects/myapp        ->  ~/.claude/projects/-home-you-projects-myapp/
+~/work/another-project  ->  ~/.claude/projects/-home-you-work-another-project/
+```
+
+If the path you give already contains `.jsonl` files (directly or in subdirectories), it's used as-is.
+
+## What it renders
+
+Each session page shows:
+
+- **Human messages** and **Claude responses** in distinct styled bubbles
+- **Tool calls** (Read, Edit, Bash, Glob, Write, etc.) collapsible with full inputs
+- **Tool results** collapsible, truncated for large outputs
+- **Thinking blocks** collapsible when present
+- **Context compaction markers** when Claude Code summarised the context mid-session
+- **API errors** (rate limits, auth failures) surfaced inline
+- **Token usage** per response
+- **Session metadata**: working directory, git branch, start/end time, message and tool call counts
+- **Resume command** — one click copies `cd <project>` and `claude --resume <session-id>` to clipboard
+
+The index page lists all sessions sorted newest-first with a live filter box and per-session metadata pills.
+
+> **Note:** Session transcripts include everything shown to Claude during the conversation — file contents, command output, environment details, and more. Review before sharing or publishing.
+
+## Linking sessions to commits
+
+Include the session ID as a git trailer when committing AI-assisted work:
+
+```
+Fix authentication token refresh race condition
+
+Claude-Session: abc123de-f456-7890-abcd-ef1234567890
+```
+
+The session ID is shown in the metadata card on each session page with a copy button. The resume command (also one-click copyable) lets you pick up the conversation right where it left off.
+
+To find and open sessions referenced in your git log:
+
+```bash
+# Open all Claude-sessions from recent history
+git log --format="%B" | claude-scrollback show
+
+# Open the session from a specific commit
+git show <commit> | claude-scrollback show
+
+# Or open a session directly by UUID
+claude-scrollback show <uuid>
+```
+
+## Session directory layout
+
+Claude Code organises sessions by project under `~/.claude/projects/`:
+
+```
+~/.claude/projects/
+  -home-you-projects-myapp/
+    abc123.jsonl
+    def456.jsonl
+  -home-you-work-another-project/
+    ...
+```
+
+`scrollback` handles both flat directories (one project) and nested trees (all projects).
+
+## Example sessions
+
+The `example/projects/` directory contains synthetic sessions demonstrating the viewer across different scenarios. To browse them:
+
+```bash
+claude-scrollback view example/projects/
+```
+
+## Requirements
+
+Python 3.8+, standard library only.

claude_scrollback-0.1.0/README.md

@@ -0,0 +1,184 @@
+# claude-scrollback
+
+A lightweight viewer for [Claude Code](https://claude.ai/claude-code) session transcripts. Converts `.jsonl` session files into readable, interactive HTML — with a built-in server for browsing and a static site generator for archiving.
+
+Pure python, no dependencies to install.
+
+**[Live demo →](https://alexdej.github.io/claude-scrollback/)**
+
+## Install
+
+pip (recommended)
+```bash
+pip install claude-scrollback
+```
+
+from source:
+
+```bash
+git clone https://github.com/alexdej/claude-scrollback
+pip install -e claude-scrollback/
+```
+
+Or use `generator.py` standalone:
+
+```bash
+git clone https://github.com/alexdej/claude-scrollback
+python claude-scrollback/claude_scrollback/generator.py <dir>
+```
+
+## Usage
+
+### Quick start
+
+Installation installs a `claude-scrollback` command.
+
+```bash
+# Browse all your Claude Code sessions (uses ~/.claude/projects/ automatically)
+claude-scrollback view
+
+# Browse sessions for the current Claude Code project directory
+claude-scrollback view .
+
+# Browse sessions for a specific project
+claude-scrollback view ~/projects/myapp
+
+# View a single session file
+claude-scrollback view path/to/session.jsonl
+```
+
+All directory modes start a local server and open your browser automatically.
+
+`claude-scrollback` is the command installed by `pip install claude-scrollback`. If you're running from a clone without installing, use `python -m claude_scrollback` in place of `claude-scrollback` throughout. Add a shell alias if you want something shorter:
+
+```bash
+alias sb='claude-scrollback'
+```
+
+### Subcommands
+
+```
+claude-scrollback view [path] [-p PORT] [-n]
+claude-scrollback show [uuid]
+claude-scrollback generate [path] [-o OUTDIR]
+
+view      start a local server and open the session browser
+show      find and open a session by UUID
+generate  generate static HTML from session files
+```
+
+### view
+
+```bash
+claude-scrollback view                        # all projects, port 8080, opens browser
+claude-scrollback view . -p 9000             # current project, custom port
+claude-scrollback view . -n                  # start server without opening browser
+claude-scrollback view session.jsonl         # convert single file, open in browser
+```
+
+Options: `-p/--port PORT` (default: 8080), `-n/--no-open`
+
+### show
+
+Find a session by UUID and open it in the browser. Searches `~/.claude/projects/` automatically.
+
+```bash
+claude-scrollback show abc123de-f456-7890-abcd-ef1234567890
+
+# Pipe in any text containing UUIDs — all matching sessions are opened
+git log --format="%B" | claude-scrollback show
+git show HEAD | claude-scrollback show
+```
+
+### generate
+
+Generate a static HTML site from session files.
+
+```bash
+claude-scrollback generate                        # all projects -> ./_site/
+claude-scrollback generate . -o ~/my-archive/    # current project, custom output dir
+claude-scrollback generate session.jsonl          # single file -> session.html
+```
+
+Options: `-o/--out-dir DIR` (default: `_site/`)
+
+### Path resolution
+
+When you pass a project directory (like `.`), scrollback maps it to the corresponding Claude Code sessions folder automatically. Claude Code stores sessions under `~/.claude/projects/` with the project path encoded as the directory name (colons, slashes, and backslashes replaced with `-`):
+
+```
+~/projects/myapp        ->  ~/.claude/projects/-home-you-projects-myapp/
+~/work/another-project  ->  ~/.claude/projects/-home-you-work-another-project/
+```
+
+If the path you give already contains `.jsonl` files (directly or in subdirectories), it's used as-is.
+
+## What it renders
+
+Each session page shows:
+
+- **Human messages** and **Claude responses** in distinct styled bubbles
+- **Tool calls** (Read, Edit, Bash, Glob, Write, etc.) collapsible with full inputs
+- **Tool results** collapsible, truncated for large outputs
+- **Thinking blocks** collapsible when present
+- **Context compaction markers** when Claude Code summarised the context mid-session
+- **API errors** (rate limits, auth failures) surfaced inline
+- **Token usage** per response
+- **Session metadata**: working directory, git branch, start/end time, message and tool call counts
+- **Resume command** — one click copies `cd <project>` and `claude --resume <session-id>` to clipboard
+
+The index page lists all sessions sorted newest-first with a live filter box and per-session metadata pills.
+
+> **Note:** Session transcripts include everything shown to Claude during the conversation — file contents, command output, environment details, and more. Review before sharing or publishing.
+
+## Linking sessions to commits
+
+Include the session ID as a git trailer when committing AI-assisted work:
+
+```
+Fix authentication token refresh race condition
+
+Claude-Session: abc123de-f456-7890-abcd-ef1234567890
+```
+
+The session ID is shown in the metadata card on each session page with a copy button. The resume command (also one-click copyable) lets you pick up the conversation right where it left off.
+
+To find and open sessions referenced in your git log:
+
+```bash
+# Open all Claude-sessions from recent history
+git log --format="%B" | claude-scrollback show
+
+# Open the session from a specific commit
+git show <commit> | claude-scrollback show
+
+# Or open a session directly by UUID
+claude-scrollback show <uuid>
+```
+
+## Session directory layout
+
+Claude Code organises sessions by project under `~/.claude/projects/`:
+
+```
+~/.claude/projects/
+  -home-you-projects-myapp/
+    abc123.jsonl
+    def456.jsonl
+  -home-you-work-another-project/
+    ...
+```
+
+`scrollback` handles both flat directories (one project) and nested trees (all projects).
+
+## Example sessions
+
+The `example/projects/` directory contains synthetic sessions demonstrating the viewer across different scenarios. To browse them:
+
+```bash
+claude-scrollback view example/projects/
+```
+
+## Requirements
+
+Python 3.8+, standard library only.

claude_scrollback-0.1.0/claude_scrollback/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

claude_scrollback-0.1.0/claude_scrollback/__main__.py

@@ -0,0 +1,248 @@
+#!/usr/bin/env python3
+"""
+claude-scrollback CLI
+Usage: claude-scrollback <command> [path] [options]
+       python -m claude_scrollback <command> [path] [options]
+"""
+
+import re
+import sys
+import argparse
+import tempfile
+import webbrowser
+import threading
+import time
+from pathlib import Path
+
+from .generator import generate_html, process_directory
+from .server import run as run_server
+
+
+# ── Path resolution ────────────────────────────────────────────────────────
+
+def map_project_to_sessions(project_path: Path) -> Path:
+    """
+    Map a project directory to its ~/.claude/projects/ entry.
+    Claude Code encodes the path by replacing : / \\ with -.
+    e.g. C:\\Users\\alex\\Projects\\myapp -> C--Users-alex-Projects-myapp
+    """
+    path_str = str(project_path.resolve())
+    mapped = path_str.replace("\\", "-").replace("/", "-").replace(":", "-")
+    return Path.home() / ".claude" / "projects" / mapped
+
+
+def find_sessions_dir(path_str: str) -> Path:
+    """
+    Given a path string, return the sessions directory to use.
+
+    Resolution order:
+      1. Path has .jsonl files directly or recursively -> use as-is
+      2. Otherwise -> map to ~/.claude/projects/<encoded>/
+    """
+    path = Path(path_str).resolve()
+    if not path.exists():
+        raise FileNotFoundError(f"Path not found: {path}")
+
+    if any(path.glob("*.jsonl")) or any(path.rglob("*.jsonl")):
+        return path
+
+    mapped = map_project_to_sessions(path)
+    if mapped.exists() and any(mapped.rglob("*.jsonl")):
+        print(f"Using sessions from {mapped}")
+        return mapped
+
+    raise FileNotFoundError(
+        f"No Claude Code sessions found.\n"
+        f"  Checked: {path}\n"
+        f"  Checked: {mapped}\n"
+        f"Run from a Claude Code project directory, or pass the sessions path directly."
+    )
+
+
+def default_sessions_dir() -> Path:
+    """Return ~/.claude/projects/ if it exists and has sessions."""
+    default = Path.home() / ".claude" / "projects"
+    if default.exists() and any(default.rglob("*.jsonl")):
+        return default
+    raise FileNotFoundError(
+        "~/.claude/projects/ not found or empty.\n"
+        "Pass a path: claude-scrollback view <project-or-sessions-dir>"
+    )
+
+
+def resolve(path_arg):
+    """Resolve optional path arg to a sessions directory."""
+    if path_arg:
+        return find_sessions_dir(path_arg)
+    return default_sessions_dir()
+
+
+def open_browser(url: str, delay: float = 0.4):
+    """Open browser after a short delay (gives server time to start)."""
+    def _open():
+        time.sleep(delay)
+        try:
+            webbrowser.open(url)
+        except Exception:
+            pass
+    threading.Thread(target=_open, daemon=True).start()
+
+
+# ── Subcommands ────────────────────────────────────────────────────────────
+
+def cmd_view(args):
+    # Single file
+    if args.path and Path(args.path).is_file():
+        src = Path(args.path)
+        if src.suffix != ".jsonl":
+            print(f"Error: {src} is not a .jsonl file")
+            sys.exit(1)
+        out = src.with_suffix(".html")
+        print(f"Generating {out} ...")
+        generate_html(src, out)
+        url = out.resolve().as_uri()
+        if not args.no_open:
+            webbrowser.open(url)
+        else:
+            print(f"Open: {url}")
+        return
+
+    try:
+        sessions_dir = resolve(args.path)
+    except FileNotFoundError as e:
+        print(f"Error: {e}")
+        sys.exit(1)
+
+    url = f"http://localhost:{args.port}"
+    if not args.no_open:
+        open_browser(url)
+    run_server(sessions_dir, args.port)
+
+
+
+UUID_RE = re.compile(
+    r"[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}",
+    re.IGNORECASE,
+)
+
+def cmd_show(args):
+    # Collect UUIDs from positional arg and/or piped stdin
+    uuids = []
+    if args.uuid:
+        if UUID_RE.fullmatch(args.uuid):
+            uuids.append(args.uuid.lower())
+        else:
+            print(f"Error: '{args.uuid}' is not a valid UUID")
+            sys.exit(1)
+
+    if not sys.stdin.isatty():
+        text = sys.stdin.read()
+        for m in UUID_RE.finditer(text):
+            u = m.group(0).lower()
+            if u not in uuids:
+                uuids.append(u)
+
+    if not uuids:
+        print("Error: provide a UUID argument or pipe text containing UUIDs")
+        sys.exit(1)
+
+    projects = Path.home() / ".claude" / "projects"
+    opened = 0
+    for uuid in uuids:
+        matches = list(projects.rglob(f"{uuid}.jsonl"))
+        if not matches:
+            print(f"Warning: no session found for {uuid}")
+            continue
+        for src in matches:
+            out = Path(tempfile.mkdtemp()) / (src.stem + ".html")
+            generate_html(src, out)
+            webbrowser.open(out.resolve().as_uri())
+            print(f"Opened: {src.name}")
+            opened += 1
+
+    if opened == 0:
+        sys.exit(1)
+
+
+def cmd_generate(args):
+    if args.path and Path(args.path).is_file():
+        src = Path(args.path)
+        if src.suffix != ".jsonl":
+            print(f"Error: {src} is not a .jsonl file")
+            sys.exit(1)
+        out = src.with_suffix(".html")
+        generate_html(src, out)
+        print(f"Written to {out}")
+        return
+
+    try:
+        sessions_dir = resolve(args.path)
+    except FileNotFoundError as e:
+        print(f"Error: {e}")
+        sys.exit(1)
+
+    out_dir = Path(args.out_dir)
+    print(f"Generating static site from {sessions_dir} -> {out_dir} ...")
+    process_directory(sessions_dir, out_dir)
+
+
+# ── Main ───────────────────────────────────────────────────────────────────
+
+def main():
+    parser = argparse.ArgumentParser(
+        prog="claude-scrollback",
+        description="Lightweight viewer for Claude Code session transcripts.",
+    )
+    sub = parser.add_subparsers(dest="command", metavar="command")
+    sub.required = True
+
+    # view
+    p_view = sub.add_parser(
+        "view",
+        help="start a local server and open the session browser",
+    )
+    p_view.add_argument(
+        "path", nargs="?",
+        help="session file (.jsonl), sessions dir, or project dir "
+             "(default: ~/.claude/projects/)",
+    )
+    p_view.add_argument("-p", "--port", type=int, default=8080, help="port (default: 8080)")
+    p_view.add_argument("-n", "--no-open", action="store_true", help="don't open browser")
+
+    # show
+    p_show = sub.add_parser(
+        "show",
+        help="find and open a session by UUID (also accepts piped text)",
+    )
+    p_show.add_argument(
+        "uuid", nargs="?",
+        help="session UUID (or omit and pipe text containing UUIDs)",
+    )
+
+    # generate
+    p_gen = sub.add_parser(
+        "generate",
+        help="generate static HTML from session files",
+    )
+    p_gen.add_argument(
+        "path", nargs="?",
+        help="session file (.jsonl), sessions dir, or project dir "
+             "(default: ~/.claude/projects/)",
+    )
+    p_gen.add_argument(
+        "-o", "--out-dir", default="_site", metavar="DIR",
+        help="output directory (default: _site/)",
+    )
+
+    args = parser.parse_args()
+
+    if args.command == "view":
+        cmd_view(args)
+    elif args.command == "show":
+        cmd_show(args)
+    elif args.command == "generate":
+        cmd_generate(args)
+
+
+if __name__ == "__main__":
+    main()