Make pagination optional by default

Co-authored-by: Codex <[email protected]>

Author: gnyman

README.md

@@ -5,7 +5,7 @@
 [![Tests](https://github.com/simonw/claude-code-transcripts/workflows/Test/badge.svg)](https://github.com/simonw/claude-code-transcripts/actions?query=workflow%3ATest)
 [![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](https://github.com/simonw/claude-code-transcripts/blob/main/LICENSE)
 
-Convert Claude Code session files (JSON or JSONL) to clean, mobile-friendly HTML pages with pagination.
+Convert Claude Code session files (JSON or JSONL) to clean, mobile-friendly HTML pages.
 
 [Example transcript](https://static.simonwillison.net/static/2025/claude-code-microjs/index.html) produced using this tool.
 
@@ -51,10 +51,11 @@ All commands support these options:
 - `--open` - open the generated `index.html` in your default browser (default if no `-o` specified)
 - `--gist` - upload the generated HTML files to a GitHub Gist and output a preview URL
 - `--json` - include the original session file in the output directory
+- `--paginate` - enable pagination (default: single page)
 
 The generated output includes:
-- `index.html` - an index page with a timeline of prompts and commits
-- `page-001.html`, `page-002.html`, etc. - paginated transcript pages
+- `index.html` - the transcript (single page by default)
+- `page-001.html`, `page-002.html`, etc. - paginated transcript pages when `--paginate` is used
 
 ### Local sessions
 

src/claude_code_transcripts/__init__.py

@@ -304,7 +304,11 @@ def find_all_sessions(folder, include_agents=False):
 
 
 def generate_batch_html(
-    source_folder, output_dir, include_agents=False, progress_callback=None
+    source_folder,
+    output_dir,
+    include_agents=False,
+    progress_callback=None,
+    paginate=False,
 ):
     """Generate HTML archive for all sessions in a Claude projects folder.
 
@@ -319,6 +323,7 @@ def generate_batch_html(
         include_agents: Whether to include agent-* session files
         progress_callback: Optional callback(project_name, session_name, current, total)
             called after each session is processed
+        paginate: Whether to generate paginated output
 
     Returns statistics dict with total_projects, total_sessions, failed_sessions, output_dir.
     """
@@ -347,7 +352,7 @@ def generate_batch_html(
 
             # Generate transcript HTML with error handling
             try:
-                generate_html(session["path"], session_dir)
+                generate_html(session["path"], session_dir, paginate=paginate)
                 successful_sessions += 1
             except Exception as e:
                 failed_sessions.append(
@@ -1153,7 +1158,7 @@ def generate_index_pagination_html(total_pages):
     return _macros.index_pagination(total_pages)
 
 
-def generate_html(json_path, output_dir, github_repo=None):
+def generate_html(json_path, output_dir, github_repo=None, paginate=False):
     output_dir = Path(output_dir)
     output_dir.mkdir(exist_ok=True)
 
@@ -1212,6 +1217,58 @@ def generate_html(json_path, output_dir, github_repo=None):
     total_convs = len(conversations)
     total_pages = (total_convs + PROMPTS_PER_PAGE - 1) // PROMPTS_PER_PAGE
 
+    if not paginate:
+        messages_html = []
+        for conv in conversations:
+            is_first = True
+            for log_type, message_json, timestamp in conv["messages"]:
+                msg_html = render_message(log_type, message_json, timestamp)
+                if msg_html:
+                    if is_first and conv.get("is_continuation"):
+                        msg_html = f'<details class="continuation"><summary>Session continuation summary</summary>{msg_html}</details>'
+                    messages_html.append(msg_html)
+                is_first = False
+        page_template = get_template("page.html")
+        page_content = page_template.render(
+            css=CSS,
+            js=JS,
+            page_num=1,
+            total_pages=1,
+            pagination_html="",
+            messages_html="".join(messages_html),
+            paginate=False,
+        )
+        index_path = output_dir / "index.html"
+        index_path.write_text(page_content, encoding="utf-8")
+        print(f"Generated {index_path.resolve()} ({total_convs} prompts)")
+        return
+
+    if not paginate:
+        messages_html = []
+        for conv in conversations:
+            is_first = True
+            for log_type, message_json, timestamp in conv["messages"]:
+                msg_html = render_message(log_type, message_json, timestamp)
+                if msg_html:
+                    if is_first and conv.get("is_continuation"):
+                        msg_html = f'<details class="continuation"><summary>Session continuation summary</summary>{msg_html}</details>'
+                    messages_html.append(msg_html)
+                is_first = False
+        page_template = get_template("page.html")
+        page_content = page_template.render(
+            css=CSS,
+            js=JS,
+            page_num=1,
+            total_pages=1,
+            pagination_html="",
+            messages_html="".join(messages_html),
+            paginate=False,
+        )
+        index_path = output_dir / "index.html"
+        index_path.write_text(page_content, encoding="utf-8")
+        print(f"Generated {index_path.resolve()} ({total_convs} prompts)")
+        return
+
     for page_num in range(1, total_pages + 1):
         start_idx = (page_num - 1) * PROMPTS_PER_PAGE
         end_idx = min(start_idx + PROMPTS_PER_PAGE, total_convs)
@@ -1236,6 +1293,7 @@ def generate_html(json_path, output_dir, github_repo=None):
             total_pages=total_pages,
             pagination_html=pagination_html,
             messages_html="".join(messages_html),
+            paginate=True,
         )
         (output_dir / f"page-{page_num:03d}.html").write_text(
             page_content, encoding="utf-8"
@@ -1369,12 +1427,26 @@ def cli():
     is_flag=True,
     help="Open the generated index.html in your default browser (default if no -o specified).",
 )
+@click.option(
+    "--paginate",
+    is_flag=True,
+    help="Enable pagination (default: single page).",
+)
 @click.option(
     "--limit",
     default=10,
     help="Maximum number of sessions to show (default: 10)",
 )
-def local_cmd(output, output_auto, repo, gist, include_json, open_browser, limit):
+def local_cmd(
+    output,
+    output_auto,
+    repo,
+    gist,
+    include_json,
+    open_browser,
+    paginate,
+    limit,
+):
     """Select and convert a local Claude Code session to HTML."""
     projects_folder = Path.home() / ".claude" / "projects"
 
@@ -1425,7 +1497,7 @@ def local_cmd(output, output_auto, repo, gist, include_json, open_browser, limit
         output = Path(tempfile.gettempdir()) / f"claude-session-{session_file.stem}"
 
     output = Path(output)
-    generate_html(session_file, output, github_repo=repo)
+    generate_html(session_file, output, github_repo=repo, paginate=paginate)
 
     # Show output directory
     click.echo(f"Output: {output.resolve()}")
@@ -1487,7 +1559,14 @@ def local_cmd(output, output_auto, repo, gist, include_json, open_browser, limit
     is_flag=True,
     help="Open the generated index.html in your default browser (default if no -o specified).",
 )
-def json_cmd(json_file, output, output_auto, repo, gist, include_json, open_browser):
+@click.option(
+    "--paginate",
+    is_flag=True,
+    help="Enable pagination (default: single page).",
+)
+def json_cmd(
+    json_file, output, output_auto, repo, gist, include_json, open_browser, paginate
+):
     """Convert a Claude Code session JSON/JSONL file to HTML."""
     # Determine output directory and whether to open browser
     # If no -o specified, use temp dir and open browser by default
@@ -1500,7 +1579,7 @@ def json_cmd(json_file, output, output_auto, repo, gist, include_json, open_brow
         output = Path(tempfile.gettempdir()) / f"claude-session-{Path(json_file).stem}"
 
     output = Path(output)
-    generate_html(json_file, output, github_repo=repo)
+    generate_html(json_file, output, github_repo=repo, paginate=paginate)
 
     # Show output directory
     click.echo(f"Output: {output.resolve()}")
@@ -1574,7 +1653,9 @@ def format_session_for_display(session_data):
     return f"{session_id}  {created_at[:19] if created_at else 'N/A':19}  {title}"
 
 
-def generate_html_from_session_data(session_data, output_dir, github_repo=None):
+def generate_html_from_session_data(
+    session_data, output_dir, github_repo=None, paginate=False
+):
     """Generate HTML from session data dict (instead of file path)."""
     output_dir = Path(output_dir)
     output_dir.mkdir(exist_ok=True, parents=True)
@@ -1627,6 +1708,32 @@ def generate_html_from_session_data(session_data, output_dir, github_repo=None):
     total_convs = len(conversations)
     total_pages = (total_convs + PROMPTS_PER_PAGE - 1) // PROMPTS_PER_PAGE
 
+    if not paginate:
+        messages_html = []
+        for conv in conversations:
+            is_first = True
+            for log_type, message_json, timestamp in conv["messages"]:
+                msg_html = render_message(log_type, message_json, timestamp)
+                if msg_html:
+                    if is_first and conv.get("is_continuation"):
+                        msg_html = f'<details class="continuation"><summary>Session continuation summary</summary>{msg_html}</details>'
+                    messages_html.append(msg_html)
+                is_first = False
+        page_template = get_template("page.html")
+        page_content = page_template.render(
+            css=CSS,
+            js=JS,
+            page_num=1,
+            total_pages=1,
+            pagination_html="",
+            messages_html="".join(messages_html),
+            paginate=False,
+        )
+        index_path = output_dir / "index.html"
+        index_path.write_text(page_content, encoding="utf-8")
+        print(f"Generated {index_path.resolve()} ({total_convs} prompts)")
+        return
+
     for page_num in range(1, total_pages + 1):
         start_idx = (page_num - 1) * PROMPTS_PER_PAGE
         end_idx = min(start_idx + PROMPTS_PER_PAGE, total_convs)
@@ -1651,6 +1758,7 @@ def generate_html_from_session_data(session_data, output_dir, github_repo=None):
             total_pages=total_pages,
             pagination_html=pagination_html,
             messages_html="".join(messages_html),
+            paginate=True,
         )
         (output_dir / f"page-{page_num:03d}.html").write_text(
             page_content, encoding="utf-8"
@@ -1782,6 +1890,11 @@ def generate_html_from_session_data(session_data, output_dir, github_repo=None):
     is_flag=True,
     help="Open the generated index.html in your default browser (default if no -o specified).",
 )
+@click.option(
+    "--paginate",
+    is_flag=True,
+    help="Enable pagination (default: single page).",
+)
 def web_cmd(
     session_id,
     output,
@@ -1792,6 +1905,7 @@ def web_cmd(
     gist,
     include_json,
     open_browser,
+    paginate,
 ):
     """Select and convert a web session from the Claude API to HTML.
 
@@ -1863,7 +1977,9 @@ def web_cmd(
 
     output = Path(output)
     click.echo(f"Generating HTML in {output}/...")
-    generate_html_from_session_data(session_data, output, github_repo=repo)
+    generate_html_from_session_data(
+        session_data, output, github_repo=repo, paginate=paginate
+    )
 
     # Show output directory
     click.echo(f"Output: {output.resolve()}")
@@ -1921,13 +2037,18 @@ def web_cmd(
     is_flag=True,
     help="Open the generated archive in your default browser.",
 )
+@click.option(
+    "--paginate",
+    is_flag=True,
+    help="Enable pagination (default: single page).",
+)
 @click.option(
     "-q",
     "--quiet",
     is_flag=True,
     help="Suppress all output except errors.",
 )
-def all_cmd(source, output, include_agents, dry_run, open_browser, quiet):
+def all_cmd(source, output, include_agents, dry_run, open_browser, paginate, quiet):
     """Convert all local Claude Code sessions to a browsable HTML archive.
 
     Creates a directory structure with:
@@ -1993,6 +2114,7 @@ def on_progress(project_name, session_name, current, total):
         output,
         include_agents=include_agents,
         progress_callback=on_progress,
+        paginate=paginate,
     )
 
     # Report any failures

src/claude_code_transcripts/templates/page.html

@@ -1,10 +1,15 @@
 {% extends "base.html" %}
 
-{% block title %}Claude Code transcript - page {{ page_num }}{% endblock %}
+{% block title %}Claude Code transcript{% if paginate %} - page {{ page_num }}{% endif %}{% endblock %}
 
 {% block content %}
+        {% if paginate -%}
         <h1><a href="index.html" style="color: inherit; text-decoration: none;">Claude Code transcript</a> - page {{ page_num }}/{{ total_pages }}</h1>
         {{ pagination_html|safe }}
         {{ messages_html|safe }}
         {{ pagination_html|safe }}
+        {%- else -%}
+        <h1>Claude Code transcript</h1>
+        {{ messages_html|safe }}
+        {%- endif %}
 {%- endblock %}

tests/test_all.py

@@ -281,10 +281,14 @@ def test_handles_failed_session_gracefully(self, output_dir):
             # Patch generate_html to fail on one specific session
             original_generate_html = __import__("claude_code_transcripts").generate_html
 
-            def mock_generate_html(json_path, output_dir, github_repo=None):
+            def mock_generate_html(
+                json_path, output_dir, github_repo=None, paginate=False
+            ):
                 if "session1" in str(json_path):
                     raise RuntimeError("Simulated failure")
-                return original_generate_html(json_path, output_dir, github_repo)
+                return original_generate_html(
+                    json_path, output_dir, github_repo, paginate=paginate
+                )
 
             with patch(
                 "claude_code_transcripts.generate_html", side_effect=mock_generate_html