cc-session-browser 0.1.0__tar.gz

cc_session_browser-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+__pycache__/
+*.py[cod]
+dist/
+.venv/
+.pytest_cache/
+.ruff_cache/

cc_session_browser-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Martin Mahner
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

cc_session_browser-0.1.0/PKG-INFO

@@ -0,0 +1,143 @@
+Metadata-Version: 2.5
+Name: cc-session-browser
+Version: 0.1.0
+Summary: Three-pane browser for your local Claude Code sessions
+Project-URL: Homepage, https://github.com/bartTC/cc-session-browser
+Project-URL: Issues, https://github.com/bartTC/cc-session-browser/issues
+Author-email: Martin Mahner <martin@elephant.house>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: browser,claude,claude-code,sessions,transcript
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Environment :: Web Environment
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Documentation
+Requires-Python: >=3.11
+Requires-Dist: jinja2>=3.1
+Requires-Dist: markdown-it-py>=3.0
+Requires-Dist: pygments>=2.18
+Requires-Dist: starlette>=0.40
+Requires-Dist: uvicorn>=0.30
+Description-Content-Type: text/markdown
+
+# cc-session-browser
+
+A browser for your Claude Code sessions.
+
+```sh
+uvx cc-session-browser
+```
+
+No install, no configuration. It indexes `~/.claude/projects` and opens a
+browser.
+
+![cc-session-browser](https://raw.githubusercontent.com/bartTC/cc-session-browser/main/docs/screenshot.png)
+
+## Features
+
+- **Browse** every project and session Claude Code has recorded, with the real
+  project path recovered from the transcripts rather than the dashed directory
+  name.
+- **Read** transcripts with rendered markdown, syntax-highlighted code,
+  expandable tool calls and their output, inline screenshots, and subagent
+  transcripts shown where they were spawned.
+- **Search** across all sessions — titles, prompts, replies and tool
+  invocations — or within a single project.
+- **Resume, fork, or start** a session in your terminal. Forking uses
+  `--fork-session`, so the original transcript is never touched.
+
+Nothing is sent anywhere: the tool reads local files and serves them on
+`127.0.0.1`.
+
+## Configuration
+
+Optional. Everything has a working default.
+
+```sh
+cc-session-browser --help-config    # every option, with your paths filled in
+cc-session-browser --write-config   # write a commented starter file
+```
+
+The config file is read from the first of these that exists:
+
+1. `--config PATH`
+2. `$CC_SESSION_BROWSER_CONFIG`
+3. `./cc-session-browser.toml`
+4. `~/.config/cc-session-browser/config.toml` (`%APPDATA%` on Windows)
+
+`$CLAUDE_CONFIG_DIR` is honoured, so a non-standard Claude Code location needs
+no configuration at all.
+
+```toml
+# cc-session-browser configuration
+
+
+# Where Claude Code keeps its session transcripts. $CLAUDE_CONFIG_DIR is
+# honoured automatically, so you rarely need to set this.
+#
+# projects_dir = "~/.claude/projects"
+
+
+# Projects to leave out of the sidebar. Each entry is a glob, matched against
+# the project name, its full path, and its Claude Code slug -- so you never
+# have to know what a slug looks like.
+#
+# hide = [
+#     "scratch",
+#     "*/Workspace/throwaway-*",
+# ]
+
+
+[server]
+
+# Bind address. Leave this on loopback: the endpoint that opens a terminal
+# starts processes on your machine.
+#
+# host = "127.0.0.1"
+
+# Port to serve on.
+#
+# port = 8765
+
+# Open a browser window on startup.
+#
+# open_browser = true
+
+
+[launch]
+
+# Open a session in a new "window" or a new "tab".
+# Tabs are supported for: gnome-terminal, iterm, kitty, konsole, wezterm, wt
+# (kitty needs allow_remote_control). Every other terminal falls back to a
+# window.
+#
+# mode = "window"
+
+# Which terminal to use. Auto-detected from $TERM_PROGRAM when unset.
+# Known terminals: ghostty, gnome-terminal, iterm, kitty, konsole, terminal, wezterm, wt
+#
+# terminal = "iterm"
+
+# Full override, for a terminal that is not in that list. {script} is a
+# generated shell script that cds into the project and runs claude; {cwd} is
+# the project directory.
+#
+# terminal_argv = ["alacritty", "--working-directory", "{cwd}", "-e", "{script}"]
+
+# Path to the claude CLI. Found on PATH when unset.
+#
+# claude_bin = "/usr/local/bin/claude"
+```
+
+## Requirements
+
+Python 3.11+. Terminal integration supports iTerm, Terminal.app, Ghostty,
+kitty, WezTerm, GNOME Terminal, Konsole and Windows Terminal; anything else can
+be driven with a `terminal_argv` template.

cc_session_browser-0.1.0/README.md

@@ -0,0 +1,114 @@
+# cc-session-browser
+
+A browser for your Claude Code sessions.
+
+```sh
+uvx cc-session-browser
+```
+
+No install, no configuration. It indexes `~/.claude/projects` and opens a
+browser.
+
+![cc-session-browser](https://raw.githubusercontent.com/bartTC/cc-session-browser/main/docs/screenshot.png)
+
+## Features
+
+- **Browse** every project and session Claude Code has recorded, with the real
+  project path recovered from the transcripts rather than the dashed directory
+  name.
+- **Read** transcripts with rendered markdown, syntax-highlighted code,
+  expandable tool calls and their output, inline screenshots, and subagent
+  transcripts shown where they were spawned.
+- **Search** across all sessions — titles, prompts, replies and tool
+  invocations — or within a single project.
+- **Resume, fork, or start** a session in your terminal. Forking uses
+  `--fork-session`, so the original transcript is never touched.
+
+Nothing is sent anywhere: the tool reads local files and serves them on
+`127.0.0.1`.
+
+## Configuration
+
+Optional. Everything has a working default.
+
+```sh
+cc-session-browser --help-config    # every option, with your paths filled in
+cc-session-browser --write-config   # write a commented starter file
+```
+
+The config file is read from the first of these that exists:
+
+1. `--config PATH`
+2. `$CC_SESSION_BROWSER_CONFIG`
+3. `./cc-session-browser.toml`
+4. `~/.config/cc-session-browser/config.toml` (`%APPDATA%` on Windows)
+
+`$CLAUDE_CONFIG_DIR` is honoured, so a non-standard Claude Code location needs
+no configuration at all.
+
+```toml
+# cc-session-browser configuration
+
+
+# Where Claude Code keeps its session transcripts. $CLAUDE_CONFIG_DIR is
+# honoured automatically, so you rarely need to set this.
+#
+# projects_dir = "~/.claude/projects"
+
+
+# Projects to leave out of the sidebar. Each entry is a glob, matched against
+# the project name, its full path, and its Claude Code slug -- so you never
+# have to know what a slug looks like.
+#
+# hide = [
+#     "scratch",
+#     "*/Workspace/throwaway-*",
+# ]
+
+
+[server]
+
+# Bind address. Leave this on loopback: the endpoint that opens a terminal
+# starts processes on your machine.
+#
+# host = "127.0.0.1"
+
+# Port to serve on.
+#
+# port = 8765
+
+# Open a browser window on startup.
+#
+# open_browser = true
+
+
+[launch]
+
+# Open a session in a new "window" or a new "tab".
+# Tabs are supported for: gnome-terminal, iterm, kitty, konsole, wezterm, wt
+# (kitty needs allow_remote_control). Every other terminal falls back to a
+# window.
+#
+# mode = "window"
+
+# Which terminal to use. Auto-detected from $TERM_PROGRAM when unset.
+# Known terminals: ghostty, gnome-terminal, iterm, kitty, konsole, terminal, wezterm, wt
+#
+# terminal = "iterm"
+
+# Full override, for a terminal that is not in that list. {script} is a
+# generated shell script that cds into the project and runs claude; {cwd} is
+# the project directory.
+#
+# terminal_argv = ["alacritty", "--working-directory", "{cwd}", "-e", "{script}"]
+
+# Path to the claude CLI. Found on PATH when unset.
+#
+# claude_bin = "/usr/local/bin/claude"
+```
+
+## Requirements
+
+Python 3.11+. Terminal integration supports iTerm, Terminal.app, Ghostty,
+kitty, WezTerm, GNOME Terminal, Konsole and Windows Terminal; anything else can
+be driven with a `terminal_argv` template.

cc_session_browser-0.1.0/pyproject.toml

@@ -0,0 +1,115 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "cc-session-browser"
+version = "0.1.0"
+description = "Three-pane browser for your local Claude Code sessions"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Martin Mahner", email = "martin@elephant.house" }]
+keywords = ["claude", "claude-code", "sessions", "browser", "transcript"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Environment :: Web Environment",
+    "Intended Audience :: Developers",
+    "Operating System :: MacOS",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development :: Documentation",
+]
+dependencies = [
+    "starlette>=0.40",
+    "uvicorn>=0.30",
+    "jinja2>=3.1",
+    "markdown-it-py>=3.0",
+    "pygments>=2.18",
+]
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0",
+    "httpx2>=0.28",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"
+
+[project.urls]
+Homepage = "https://github.com/bartTC/cc-session-browser"
+Issues = "https://github.com/bartTC/cc-session-browser/issues"
+
+[project.scripts]
+cc-session-browser = "cc_session_browser.__main__:main"
+ccsb = "cc_session_browser.__main__:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/cc_session_browser"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src", "README.md"]
+
+[tool.ruff]
+target-version = "py311"
+lint.select = ["ALL"]
+lint.ignore = [
+    # Valid exclusions.
+    "COM812", # Conflicts with ruff format
+    "E501", # Line too long (>88)
+    "D203", # incorrect-blank-line-before-class (conflicts with D211)
+    "D212", # Don't require summary on first line
+    "D401", # First line of docstring should be in imperative mood
+    "ERA001", # Found commented-out code
+    "FBT", # Flake Boolean Trap (don't use arg=True in functions)
+    "ANN401", # Any is legitimate for the recursive tree dicts
+    "CPY001", # Copyright header per file — the LICENSE file covers it
+
+    # Size and complexity metrics. The request handlers, the transcript parser
+    # and the indexer are long because the work is genuinely sequential, not
+    # because they are tangled; splitting them to satisfy a counter would make
+    # them harder to follow.
+    "C901",    # Function is too complex (mccabe)
+    "PLR0911", # Too many return statements
+    "PLR0912", # Too many branches
+    "PLR0913", # Too many arguments
+    "PLR0914", # Too many local variables
+    "PLR0915", # Too many statements
+    "PLR0916", # Too many boolean expressions
+    "PLR0917", # Too many positional arguments
+    "PLR1702", # Too many nested blocks
+    "PLR0904", # Too many public methods
+]
+
+[tool.ruff.lint.extend-per-file-ignores]
+# A CLI writes to stdout; that is its job. Ruff's fix for T201 deletes the
+# call, which silently turned every message in here into nothing.
+"src/cc_session_browser/__main__.py" = ["T201"]
+# The only values interpolated into SQL here are module-level constants and
+# generated "?" placeholders; every user value is a bound parameter.
+"src/cc_session_browser/index.py" = ["S608"]
+"tests/*.py" = [
+    "S101", # Use of `assert` detected
+    "PLR2004", # Magic value in comparison — tests compare to literal counts/percentages
+    "D", # Tests don't need docstrings on every class/method
+    "ANN", # Fake objects and inline helpers don't need full type annotations
+    "SLF001", # Tests routinely reach into implementation internals
+    "S314", # xml.etree parses our own generated output, not untrusted input
+    "ARG001", # pytester/tmp_path fixtures accepted for their side effects
+    "ARG002", # Same for unused parameters on fake callables
+    "N806", # MagicMock instances are conventionally named like classes
+    "S108", # /tmp paths here are fixture strings, never touched on disk
+    "TRY003", # Test doubles raise with a literal message on purpose
+    "EM101", # Same
+]
+"tests/conftest.py" = [
+    "D", "ANN",
+]
+"tests/__init__.py" = ["D104"]

cc_session_browser-0.1.0/src/cc_session_browser/__init__.py

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

cc_session_browser-0.1.0/src/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())