Add support for Claude Code local JSONL format

[simonw]

Add support for Claude Code's local JSONL format, which differs from the session JSON returned by Claude Code for web from that API

You'll need to refactor to introduce an abstraction layer that handles both formats - use TDD to build that

Copy this code into /tmp and use it as a reference for the new format: https://raw.githubusercontent.com/simonw/tools/refs/heads/main/claude-code-timeline.html

You can use this JSONL file to help test your implementation https://gist.githubusercontent.com/simonw/46afe835d634e8145e54503438fce644/raw/73a1c52ef28d1a36d76b11c1357db6da538d402b/43daf8c0-2ba6-4328-9f98-582b7b4b4cdd.jsonl

You'll need to create a minimal version of a JSONL file to include in the tests

You can use snapshot testing to help write tests for this too

Running "claude-code-publish" with no arguments at all should show a list of LOCAL files that can be shared - copy https://raw.githubusercontent.com/simonw/tools/refs/heads/main/python/claude_code_to_gist.py to /tmp and use that as inspiration for this feature

• Add parse_session_file() abstraction to handle both JSON and JSONL formats
• Add get_session_summary() to extract summaries from session files
• Add find_local_sessions() to discover JSONL files in ~/.claude/projects
• Add list-local command to show local sessions
• Change default behavior: running with no args now lists local sessions
• Add comprehensive tests for all new functionality
• Include sample JSONL test fixture and snapshot tests

Transcript: https://gistpreview.github.io/?25d90dadb5bc6c9d619e366c9060bcbf/index.html

[simonw]

Blocked on some design decisions:

• Design for the local v.s. remote CLI #4

[simonw]

Here's the --help output for the new local/web/json design from #4:

claude-code-publish % uv run claude-code-publish --help
Usage: claude-code-publish [OPTIONS] COMMAND [ARGS]...

  Convert Claude Code session JSON to mobile-friendly HTML pages.

Options:
  -v, --version  Show the version and exit.
  --help         Show this message and exit.

Commands:
  local*  Select and convert a local Claude Code session to HTML.
  json    Convert a Claude Code session JSON/JSONL file to HTML.
  web     Select and convert a web session from the Claude API to HTML.
claude-code-publish % uv run claude-code-publish local --help
Usage: claude-code-publish local [OPTIONS]

  Select and convert a local Claude Code session to HTML.

Options:
  -o, --output PATH  Output directory. If not specified, writes to temp dir
                     and opens in browser.
  -a, --output-auto  Auto-name output subdirectory based on session filename
                     (uses -o as parent, or current dir).
  --repo TEXT        GitHub repo (owner/name) for commit links. Auto-detected
                     from git push output if not specified.
  --gist             Upload to GitHub Gist and output a gistpreview.github.io
                     URL.
  --json             Include the original JSONL session file in the output
                     directory.
  --open             Open the generated index.html in your default browser
                     (default if no -o specified).
  --limit INTEGER    Maximum number of sessions to show (default: 10)
  --help             Show this message and exit.
claude-code-publish % uv run claude-code-publish web --help  
Usage: claude-code-publish web [OPTIONS] [SESSION_ID]

  Select and convert a web session from the Claude API to HTML.

  If SESSION_ID is not provided, displays an interactive picker to select a
  session.

Options:
  -o, --output PATH  Output directory. If not specified, writes to temp dir
                     and opens in browser.
  -a, --output-auto  Auto-name output subdirectory based on session ID (uses
                     -o as parent, or current dir).
  --token TEXT       API access token (auto-detected from keychain on macOS)
  --org-uuid TEXT    Organization UUID (auto-detected from ~/.claude.json)
  --repo TEXT        GitHub repo (owner/name) for commit links. Auto-detected
                     from git push output if not specified.
  --gist             Upload to GitHub Gist and output a gistpreview.github.io
                     URL.
  --json             Include the JSON session data in the output directory.
  --open             Open the generated index.html in your default browser
                     (default if no -o specified).
  --help             Show this message and exit.
claude-code-publish % uv run claude-code-publish json --help
Usage: claude-code-publish json [OPTIONS] JSON_FILE

  Convert a Claude Code session JSON/JSONL file to HTML.

Options:
  -o, --output PATH  Output directory. If not specified, writes to temp dir
                     and opens in browser.
  -a, --output-auto  Auto-name output subdirectory based on filename (uses -o
                     as parent, or current dir).
  --repo TEXT        GitHub repo (owner/name) for commit links. Auto-detected
                     from git push output if not specified.
  --gist             Upload to GitHub Gist and output a gistpreview.github.io
                     URL.
  --json             Include the original JSON session file in the output
                     directory.
  --open             Open the generated index.html in your default browser
                     (default if no -o specified).
  --help             Show this message and exit.

[simonw]

This feels pretty good. If you run just this command:

uv run claude-code-publish

You then get to select a local transcript and hit enter to instantly see it rendered and opened in a browser from a temporary directory.

[simonw]

OK I've been testing this out a bit - see links in commits here - https://github.com/simonw/tools/commits/e16c9e2b9a22af490321366dc98282a4915107d6/ - and I really like it.