cc-session-browser 0.1.0__py3-none-any.whl

cc_session_browser/__init__.py

@@ -0,0 +1,3 @@
+"""Three-pane browser for local Claude Code sessions."""
+
+__version__ = "0.1.0"

cc_session_browser/__main__.py

@@ -0,0 +1,115 @@
+"""Command line entry point."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+import threading
+import webbrowser
+from pathlib import Path
+
+import uvicorn
+
+from . import config as config_mod
+from .app import build_app
+
+
+def parse_args(argv: list[str] | None = None) -> argparse.Namespace:
+    """Parse the command line."""
+    parser = argparse.ArgumentParser(
+        prog="cc-session-browser",
+        description="Three-pane browser for your local Claude Code sessions.",
+        epilog="Run --help-config for the configuration reference.",
+    )
+    parser.add_argument(
+        "--config",
+        type=Path,
+        metavar="PATH",
+        help=f"config file (default: {config_mod.config_path()})",
+    )
+    parser.add_argument(
+        "--projects-dir",
+        type=Path,
+        metavar="PATH",
+        help="where Claude Code keeps its sessions",
+    )
+    parser.add_argument(
+        "--host", help=f"bind address (default {config_mod.DEFAULT_HOST})"
+    )
+    parser.add_argument(
+        "--port", type=int, help=f"port (default {config_mod.DEFAULT_PORT})"
+    )
+    parser.add_argument(
+        "--no-browser", action="store_true", help="do not open a browser"
+    )
+    parser.add_argument(
+        "--write-config",
+        action="store_true",
+        help="write a commented starter config and exit",
+    )
+    parser.add_argument(
+        "--help-config",
+        action="store_true",
+        help="print the documented sample config and exit",
+    )
+    return parser.parse_args(argv)
+
+
+def write_config() -> int:
+    """Write the sample config to the per-user location, refusing to overwrite."""
+    path = config_mod.config_path()
+    if path.exists():
+        print(f"config already exists: {path}", file=sys.stderr)
+        return 1
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(config_mod.example_config())
+    print(f"wrote {path}")
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Run the browser, or handle one of the exit-early flags."""
+    args = parse_args(argv)
+    if args.help_config:
+        print(config_mod.preamble())
+        print(config_mod.example_config())
+        return 0
+    if args.write_config:
+        return write_config()
+
+    try:
+        cfg = config_mod.load(
+            args.config,
+            projects_dir=args.projects_dir,
+            host=args.host,
+            port=args.port,
+            open_browser=False if args.no_browser else None,
+        )
+    except FileNotFoundError as exc:
+        print(f"config file not found: {exc}", file=sys.stderr)
+        return 2
+
+    if not cfg.projects_dir.is_dir():
+        print(
+            f"no Claude Code sessions at {cfg.projects_dir}\n"
+            f"point --projects-dir, or projects_dir in the config, at the right place.",
+            file=sys.stderr,
+        )
+        return 2
+
+    url = f"http://{cfg.host}:{cfg.port}/"
+    print(f"cc-session-browser \N{RIGHTWARDS ARROW} {url}")
+    print(f"  sessions: {cfg.projects_dir}")
+    print(
+        f"  config:   {cfg.source or '(defaults)'} \N{EM DASH} --help-config for options"
+    )
+
+    if cfg.open_browser:
+        threading.Timer(0.6, webbrowser.open, args=(url,)).start()
+
+    uvicorn.run(build_app(cfg), host=cfg.host, port=cfg.port, log_level="warning")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

cc_session_browser/app.py

@@ -0,0 +1,357 @@
+"""Starlette app: three panes, server-rendered fragments, no client framework."""
+
+from __future__ import annotations
+
+import base64
+import secrets
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from starlette.applications import Starlette
+from starlette.exceptions import HTTPException
+from starlette.responses import JSONResponse, PlainTextResponse, Response
+from starlette.routing import Mount, Route
+from starlette.staticfiles import StaticFiles
+from starlette.templating import Jinja2Templates
+
+from . import config as config_mod
+from . import index, launcher, render, transcript
+
+if TYPE_CHECKING:
+    import sqlite3
+
+    from starlette.requests import Request
+
+    from .config import Config
+
+HERE = Path(__file__).parent
+
+# Entries rendered per request. A long session is several megabytes of HTML if
+# emitted in one go, so the transcript streams in as you scroll.
+CHUNK = 40
+
+# Thresholds for the relative-age filter, in their own units.
+JUST_NOW_SECONDS = 45
+MINUTES_PER_HOUR = 60
+HOURS_PER_DAY = 24
+DAYS_PER_WEEK = 7
+DAYS_BEFORE_MONTHS = 35
+DAYS_PER_YEAR = 365
+MEAN_DAYS_PER_MONTH = 30.44
+MEAN_DAYS_PER_YEAR = 365.25
+
+
+def humanise(value: str | None) -> str:
+    """Short, scannable timestamps: time today, weekday this week, else a date."""
+    if not value:
+        return ""
+    try:
+        when = datetime.fromisoformat(value).astimezone()
+    except ValueError:
+        return value[:16]
+    delta = datetime.now(UTC).astimezone() - when
+    if delta.days == 0:
+        return when.strftime("%H:%M")
+    if delta.days < DAYS_PER_WEEK:
+        return when.strftime("%a %H:%M")
+    return when.strftime("%d %b %Y")
+
+
+def _parse(value: str | None) -> datetime | None:
+    if not value:
+        return None
+    try:
+        return datetime.fromisoformat(value).astimezone()
+    except ValueError:
+        return None
+
+
+def ago(value: str | None) -> str:
+    """Coarse relative age: how long since, at one unit of precision."""
+    when = _parse(value)
+    if when is None:
+        return ""
+    seconds = (datetime.now(UTC).astimezone() - when).total_seconds()
+    if seconds < JUST_NOW_SECONDS:
+        return "just now"
+    minutes = seconds / 60
+    if minutes < MINUTES_PER_HOUR:
+        return f"{minutes:.0f}m ago"
+    hours = minutes / 60
+    if hours < HOURS_PER_DAY:
+        return f"{hours:.0f}h ago"
+    days = hours / 24
+    if days < DAYS_PER_WEEK:
+        return f"{days:.0f}d ago"
+    if days < DAYS_BEFORE_MONTHS:
+        return f"{days / 7:.0f}w ago"
+    if days < DAYS_PER_YEAR:
+        return f"{days / MEAN_DAYS_PER_MONTH:.0f}mo ago"
+    return f"{days / MEAN_DAYS_PER_YEAR:.0f}y ago"
+
+
+def full(value: str | None) -> str:
+    """The exact timestamp, for a title attribute."""
+    when = _parse(value)
+    return when.strftime("%a %d %b %Y, %H:%M") if when else ""
+
+
+def tilde(path: str | None) -> str:
+    """Collapse the home directory, which is the same on every row."""
+    if not path:
+        return ""
+    home = str(Path.home())
+    return "~" + path[len(home) :] if path.startswith(home) else path
+
+
+def build_app(cfg: Config) -> Starlette:
+    """Build the ASGI app: open the index, register routes and filters."""
+    conn = index.connect(cfg)
+    index.refresh(conn, cfg)
+    token = secrets.token_urlsafe(24)
+
+    templates = Jinja2Templates(directory=HERE / "templates")
+    templates.env.globals.update(
+        md=render.markdown,
+        tool_input=render.tool_input,
+        tool_args=render.tool_args,
+        code=render.code,
+        token=token,
+        cfg_example=config_mod.example_config,
+        cfg_intro=config_mod.INTRO,
+        cfg_lookup_intro=config_mod.LOOKUP_INTRO,
+        cfg_lookup=config_mod.lookup_paths,
+        cfg_file=config_mod.user_config_file,
+    )
+    templates.env.filters["when"] = humanise
+    templates.env.filters["ago"] = ago
+    templates.env.filters["full"] = full
+    templates.env.filters["tilde"] = tilde
+
+    def page(request: Request, fragment: str, ctx: dict) -> Response:
+        """Return just the fragment for htmx, or the whole shell for a deep link."""
+        ctx = {"request": request, "cfg": cfg, **ctx}
+        if request.headers.get("HX-Request"):
+            return templates.TemplateResponse(request, fragment, ctx)
+        ctx.setdefault("projects", index.projects(conn))
+        ctx["initial"] = fragment
+        return templates.TemplateResponse(request, "layout.html", ctx)
+
+    async def home(request: Request) -> Response:
+        index.refresh(conn, cfg)
+        return templates.TemplateResponse(
+            request,
+            "layout.html",
+            {
+                "request": request,
+                "cfg": cfg,
+                "projects": index.projects(conn),
+                "initial": None,
+            },
+        )
+
+    def _project_row(slug: str) -> sqlite3.Row:
+        meta = conn.execute("SELECT * FROM projects WHERE slug=?", (slug,)).fetchone()
+        if meta is None:
+            raise HTTPException(404, "unknown project")
+        return meta
+
+    def _sessions_view(request: Request, slug: str, query: str) -> Response:
+        """A project's sessions, or that project's slice of an active search."""
+        meta = _project_row(slug)
+        if query:
+            return page(
+                request,
+                "_results.html",
+                {
+                    "results": index.search(conn, query, slug=slug),
+                    "q": query,
+                    "scope": slug,
+                    "scope_name": meta["path"].rsplit("/", 1)[-1],
+                    "active_slug": slug,
+                },
+            )
+        return page(
+            request,
+            "_sessions.html",
+            {
+                "sessions": index.sessions(conn, slug),
+                "project": meta,
+                "active_slug": slug,
+            },
+        )
+
+    async def project(request: Request) -> Response:
+        return _sessions_view(
+            request,
+            request.path_params["slug"],
+            (request.query_params.get("q") or "").strip(),
+        )
+
+    def _transcript(session_id: str) -> tuple[Path, list, int]:
+        row = index.session(conn, session_id)
+        if row is None:
+            raise HTTPException(404, "unknown session")
+        path = Path(row["file"])
+        if not path.is_file():
+            raise HTTPException(410, "transcript file is gone")
+        entries, _ = transcript.load(path)
+        return row, entries, len(entries)
+
+    async def session(request: Request) -> Response:
+        session_id = request.path_params["session_id"]
+        row, entries, total = _transcript(session_id)
+
+        # A search hit opens the window that contains it rather than the top,
+        # so jumping to entry 600 does not mean loading the first 600.
+        raw_seq = request.query_params.get("seq", "")
+        start = (int(raw_seq) // CHUNK) * CHUNK if raw_seq.isdigit() else 0
+        start = max(0, min(start, max(0, total - 1)))
+        end = min(total, start + CHUNK)
+
+        subagents = conn.execute(
+            "SELECT * FROM sessions WHERE parent_id=? ORDER BY started_at",
+            (session_id,),
+        ).fetchall()
+        ctx = {
+            "session": row,
+            "entries": entries[start:end],
+            "start": start,
+            "end": end,
+            "total": total,
+            "chunk": CHUNK,
+            "subagents": subagents,
+            "active_slug": row["slug"],
+            "active_id": session_id,
+        }
+        if not request.headers.get("HX-Request"):
+            ctx["sessions"] = index.sessions(conn, row["slug"])
+            ctx["project"] = conn.execute(
+                "SELECT * FROM projects WHERE slug=?", (row["slug"],)
+            ).fetchone()
+        return page(request, "_transcript.html", ctx)
+
+    async def chunk(request: Request) -> Response:
+        session_id = request.path_params["session_id"]
+        _, entries, total = _transcript(session_id)
+        raw = request.query_params.get("start", "0")
+        start = max(0, min(int(raw) if raw.isdigit() else 0, total))
+        end = min(total, start + CHUNK)
+        return templates.TemplateResponse(
+            request,
+            "_chunk.html",
+            {
+                "request": request,
+                "cfg": cfg,
+                "sid": session_id,
+                "entries": entries[start:end],
+                "start": start,
+                "end": end,
+                "total": total,
+                "chunk": CHUNK,
+                "dir": "up" if request.query_params.get("dir") == "up" else "down",
+            },
+        )
+
+    async def subagent(request: Request) -> Response:
+        row = index.session(conn, request.path_params["session_id"])
+        if row is None or not Path(row["file"]).is_file():  # noqa: ASYNC240 - local stat
+            raise HTTPException(404, "unknown subagent transcript")
+        return templates.TemplateResponse(
+            request,
+            "_subagent.html",
+            {
+                "request": request,
+                "cfg": cfg,
+                "session": row,
+                "entries": transcript.parse(Path(row["file"])),
+            },
+        )
+
+    def _known_directories() -> set[str]:
+        rows = conn.execute(
+            "SELECT path FROM projects UNION SELECT cwd FROM sessions WHERE cwd IS NOT NULL"
+        )
+        return {r[0] for r in rows}
+
+    async def launch(request: Request) -> Response:
+        # This endpoint starts a process, so it is not reachable by a drive-by
+        # POST from another origin: same-origin token, issued per run.
+        if request.headers.get("X-CSB-Token") != token:
+            raise HTTPException(403, "bad or missing token")
+        body = await request.json()
+        mode = body.get("mode", "resume")
+        session_id = body.get("session_id")
+        row = index.session(conn, session_id) if session_id else None
+        cwd = body.get("cwd") or (row["cwd"] if row else None)
+        if not cwd:
+            raise HTTPException(400, "no working directory for this session")
+        # The directory arrives in the request body, so it is only honoured when
+        # the index already knows it: this endpoint can start claude in a real
+        # project, and nowhere else.
+        if cwd not in _known_directories():
+            raise HTTPException(400, "not a known project directory")
+        try:
+            argv = launcher.launch(cfg, cwd, session_id, mode)
+        except launcher.LaunchError as exc:
+            return JSONResponse({"ok": False, "error": str(exc)}, status_code=400)
+        return JSONResponse({"ok": True, "mode": mode, "argv": argv})
+
+    async def find(request: Request) -> Response:
+        query = (request.query_params.get("q") or "").strip()
+        slug = (request.query_params.get("slug") or "").strip()
+        if slug:
+            # Emptying the box inside a project returns to its session list
+            # rather than dumping the user back into every project.
+            return _sessions_view(request, slug, query)
+        if not query:
+            return page(
+                request, "_recent.html", {"recent": index.recent(conn), "q": ""}
+            )
+        return page(
+            request, "_results.html", {"results": index.search(conn, query), "q": query}
+        )
+
+    async def image(request: Request) -> Response:
+        """
+        Serve one image from a transcript.
+
+        Images are real URLs rather than data: URIs, so the page stays small
+        and a click can open one full size in a new tab.
+        """
+        row = index.session(conn, request.path_params["session_id"])
+        if row is None or not Path(row["file"]).is_file():  # noqa: ASYNC240 - local stat
+            raise HTTPException(404, "unknown session")
+        shots = transcript.images(Path(row["file"]))
+        idx = request.path_params["idx"]
+        if not 0 <= idx < len(shots):
+            raise HTTPException(404, "no such image")
+        media_type, data = shots[idx]
+        return Response(
+            base64.b64decode(data),
+            media_type=media_type,
+            headers={"Cache-Control": "max-age=3600"},
+        )
+
+    async def pygments_css(_: Request) -> Response:
+        return PlainTextResponse(
+            render.pygments_css(),
+            media_type="text/css",
+            headers={"Cache-Control": "max-age=86400"},
+        )
+
+    return Starlette(
+        routes=[
+            Route("/", home),
+            Route("/p/{slug}", project),
+            Route("/s/{session_id}", session),
+            Route("/a/{session_id}", subagent),
+            Route("/chunk/{session_id}", chunk),
+            Route("/search", find),
+            Route("/img/{session_id}/{idx:int}", image),
+            Route("/launch", launch, methods=["POST"]),
+            Route("/pygments.css", pygments_css),
+            Mount("/static", StaticFiles(directory=HERE / "static"), name="static"),
+        ]
+    )