New option --gist to publish straight to a Gist via gh CLI

Add a --gist feature to both of the commands that can output a session converted to HTML. If --gist
is provided  without a -o then it uses a tmp directory for the export (still with the session ID as
the name) which is still  printed out but is expected to be deleted by the OS at some point. The
--gist option causes the content of that  folder - the index.html and any page_*.html files as
multiple files in a single gist. There is just one catch: I  intend to serve those files using
https://gistpreview.github.io/?3769c0736f45668e9595eb4eb8493f9c/index.html -  but any links from that
page need to go to  https://gistpreview.github.io/?3769c0736f45668e9595eb4eb8493f9c/two.html so
relative URLs will not work as they  will incorrectly go to https://gistpreview.github.io/two.html.
So... if --gist is used then a little bit of  javascript needs to be injected into the bottom of the
index.html and other pages which checks to see if the  browser is accessing the page on
gistpreview.github.io and if it is corrects any a href links on the page

Do not forget the tests

and the README

https://gistpreview.github.io/?cbb6a57bc23ba2695bdc4e8d76997789

Author: simonw

README.md

@@ -39,6 +39,52 @@ This will generate:
 
 - `-o, --output DIRECTORY` - output directory (default: current directory)
 - `--repo OWNER/NAME` - GitHub repo for commit links (auto-detected from git push output if not specified)
+- `--gist` - upload the generated HTML files to a GitHub Gist and output a preview URL
+
+### Publishing to GitHub Gist
+
+Use the `--gist` option to automatically upload your transcript to a GitHub Gist and get a shareable preview URL:
+
+```bash
+claude-code-publish session.json --gist
+```
+
+This will output something like:
+```
+Gist: https://gist.github.com/username/abc123def456
+Preview: https://gistpreview.github.io/?abc123def456/index.html
+Files: /var/folders/.../session-id
+```
+
+The preview URL uses [gistpreview.github.io](https://gistpreview.github.io/) to render your HTML gist. The tool automatically injects JavaScript to fix relative links when served through gistpreview.
+
+When using `--gist` without `-o`, files are written to a temporary directory (shown in the output). You can combine both options to keep a local copy:
+
+```bash
+claude-code-publish session.json -o ./my-transcript --gist
+```
+
+**Requirements:** The `--gist` option requires the [GitHub CLI](https://cli.github.com/) (`gh`) to be installed and authenticated (`gh auth login`).
+
+## Importing from Claude API
+
+You can import sessions directly from the Claude API without needing to export a `session.json` file:
+
+```bash
+# List available sessions
+claude-code-publish list-web
+
+# Import a specific session
+claude-code-publish import SESSION_ID -o output-directory/
+
+# Import with interactive session picker
+claude-code-publish import
+
+# Import and publish to gist
+claude-code-publish import SESSION_ID --gist
+```
+
+On macOS, the API credentials are automatically retrieved from your keychain (requires being logged into Claude Code). On other platforms, provide `--token` and `--org-uuid` manually.
 
 ## Development
 

src/claude_code_publish/__init__.py

@@ -6,6 +6,7 @@
 import platform
 import re
 import subprocess
+import tempfile
 from pathlib import Path
 
 import click
@@ -609,6 +610,79 @@ def render_message(log_type, message_json, timestamp):
 });
 """
 
+# JavaScript to fix relative URLs when served via gistpreview.github.io
+GIST_PREVIEW_JS = r"""
+(function() {
+    if (window.location.hostname !== 'gistpreview.github.io') return;
+    // URL format: https://gistpreview.github.io/?GIST_ID/filename.html
+    var match = window.location.search.match(/^\?([^/]+)/);
+    if (!match) return;
+    var gistId = match[1];
+    document.querySelectorAll('a[href]').forEach(function(link) {
+        var href = link.getAttribute('href');
+        // Skip external links and anchors
+        if (href.startsWith('http') || href.startsWith('#') || href.startsWith('//')) return;
+        // Handle anchor in relative URL (e.g., page-001.html#msg-123)
+        var parts = href.split('#');
+        var filename = parts[0];
+        var anchor = parts.length > 1 ? '#' + parts[1] : '';
+        link.setAttribute('href', '?' + gistId + '/' + filename + anchor);
+    });
+})();
+"""
+
+
+def inject_gist_preview_js(output_dir):
+    """Inject gist preview JavaScript into all HTML files in the output directory."""
+    output_dir = Path(output_dir)
+    for html_file in output_dir.glob("*.html"):
+        content = html_file.read_text()
+        # Insert the gist preview JS before the closing </body> tag
+        if "</body>" in content:
+            content = content.replace(
+                "</body>",
+                f"<script>{GIST_PREVIEW_JS}</script>\n</body>"
+            )
+            html_file.write_text(content)
+
+
+def create_gist(output_dir, public=False):
+    """Create a GitHub gist from the HTML files in output_dir.
+
+    Returns the gist ID on success, or raises click.ClickException on failure.
+    """
+    output_dir = Path(output_dir)
+    html_files = list(output_dir.glob("*.html"))
+    if not html_files:
+        raise click.ClickException("No HTML files found to upload to gist.")
+
+    # Build the gh gist create command
+    # gh gist create file1 file2 ... --public/--private
+    cmd = ["gh", "gist", "create"]
+    cmd.extend(str(f) for f in sorted(html_files))
+    if public:
+        cmd.append("--public")
+
+    try:
+        result = subprocess.run(
+            cmd,
+            capture_output=True,
+            text=True,
+            check=True,
+        )
+        # Output is the gist URL, e.g., https://gist.github.com/username/GIST_ID
+        gist_url = result.stdout.strip()
+        # Extract gist ID from URL
+        gist_id = gist_url.rstrip("/").split("/")[-1]
+        return gist_id, gist_url
+    except subprocess.CalledProcessError as e:
+        error_msg = e.stderr.strip() if e.stderr else str(e)
+        raise click.ClickException(f"Failed to create gist: {error_msg}")
+    except FileNotFoundError:
+        raise click.ClickException(
+            "gh CLI not found. Install it from https://cli.github.com/ and run 'gh auth login'."
+        )
+
 
 def generate_pagination_html(current_page, total_pages):
     if total_pages <= 1:
@@ -845,18 +919,42 @@ def cli():
 @click.option(
     "-o",
     "--output",
-    default=".",
     type=click.Path(),
-    help="Output directory (default: current directory)",
+    help="Output directory (default: current directory, or temp dir with --gist)",
 )
 @click.option(
     "--repo",
     help="GitHub repo (owner/name) for commit links. Auto-detected from git push output if not specified.",
 )
-def session(json_file, output, repo):
+@click.option(
+    "--gist",
+    is_flag=True,
+    help="Upload to GitHub Gist and output a gistpreview.github.io URL.",
+)
+def session(json_file, output, repo, gist):
     """Convert a Claude Code session JSON file to HTML."""
+    # Determine output directory
+    if gist and output is None:
+        # Extract session ID from JSON file for temp directory name
+        with open(json_file, "r") as f:
+            data = json.load(f)
+        session_id = data.get("sessionId", Path(json_file).stem)
+        output = Path(tempfile.gettempdir()) / session_id
+    elif output is None:
+        output = "."
+
     generate_html(json_file, output, github_repo=repo)
 
+    if gist:
+        # Inject gist preview JS and create gist
+        inject_gist_preview_js(output)
+        click.echo("Creating GitHub gist...")
+        gist_id, gist_url = create_gist(output)
+        preview_url = f"https://gistpreview.github.io/?{gist_id}/index.html"
+        click.echo(f"Gist: {gist_url}")
+        click.echo(f"Preview: {preview_url}")
+        click.echo(f"Files: {output}")
+
 
 def resolve_credentials(token, org_uuid):
     """Resolve token and org_uuid from arguments or auto-detect.
@@ -1120,7 +1218,7 @@ def generate_html_from_session_data(session_data, output_dir, github_repo=None):
     "-o",
     "--output",
     type=click.Path(),
-    help="Output directory (default: creates folder with session ID)",
+    help="Output directory (default: creates folder with session ID, or temp dir with --gist)",
 )
 @click.option("--token", help="API access token (auto-detected from keychain on macOS)")
 @click.option(
@@ -1130,7 +1228,12 @@ def generate_html_from_session_data(session_data, output_dir, github_repo=None):
     "--repo",
     help="GitHub repo (owner/name) for commit links. Auto-detected from git push output if not specified.",
 )
-def import_session(session_id, output, token, org_uuid, repo):
+@click.option(
+    "--gist",
+    is_flag=True,
+    help="Upload to GitHub Gist and output a gistpreview.github.io URL.",
+)
+def import_session(session_id, output, token, org_uuid, repo, gist):
     """Import a session from the Claude API and convert to HTML.
 
     If SESSION_ID is not provided, displays an interactive picker to select a session.
@@ -1190,12 +1293,25 @@ def import_session(session_id, output, token, org_uuid, repo):
         raise click.ClickException(f"Network error: {e}")
 
     # Determine output directory
-    if output is None:
+    if gist and output is None:
+        output = Path(tempfile.gettempdir()) / session_id
+    elif output is None:
         output = session_id
 
     click.echo(f"Generating HTML in {output}/...")
     generate_html_from_session_data(session_data, output, github_repo=repo)
-    click.echo(f"Done! Open {output}/index.html to view.")
+
+    if gist:
+        # Inject gist preview JS and create gist
+        inject_gist_preview_js(output)
+        click.echo("Creating GitHub gist...")
+        gist_id, gist_url = create_gist(output)
+        preview_url = f"https://gistpreview.github.io/?{gist_id}/index.html"
+        click.echo(f"Gist: {gist_url}")
+        click.echo(f"Preview: {preview_url}")
+        click.echo(f"Files: {output}")
+    else:
+        click.echo(f"Done! Open {output}/index.html to view.")
 
 
 def main():