claude-code-log 1.0.0__tar.gz → 1.1.1__tar.gz

claude_code_log-1.1.1/.claude/skills/tool-renderer/SKILL.md

@@ -0,0 +1,414 @@
+---
+name: tool-renderer
+description: Implement specialized rendering for Claude Code tools. Use when adding a new tool type (WebSearch, WebFetch, etc.) to the transcript viewer, or when asked to implement tool rendering.
+---
+
+# Implementing a Tool Renderer
+
+This guide walks through adding rendering support for a new Claude Code tool, using WebSearch as an example.
+
+## Before You Start
+
+**Examine existing test data** to understand the tool's actual JSON structure:
+
+```bash
+# Find test files containing the tool
+rg -l "ToolName" test/test_data/
+
+# Look at actual JSONL entries
+rg '"name":\s*"ToolName"' test/test_data/ -A 2 -B 2
+```
+
+Key fields to identify:
+- **Input parameters**: What's in `tool_use.input`?
+- **toolUseResult structure**: What metadata does the structured result contain?
+- **tool_result.content**: What does the raw text output look like?
+
+The `toolUseResult` field on transcript entries often contains richer structured data than `tool_result.content`. **Always prefer parsing from `toolUseResult` when available.**
+
+## Overview
+
+Tool rendering involves several components working together:
+
+1. **Models** (`models.py`) - Type definitions for tool inputs and outputs
+2. **Factory** (`factories/tool_factory.py`) - Parsing raw JSON into typed models
+3. **HTML Formatters** (`html/tool_formatters.py`) - HTML rendering functions
+4. **Renderers** - Integration with HTML and Markdown renderers
+
+## Step 1: Define Models
+
+### Tool Input Model
+
+Add a Pydantic model for the tool's input parameters in `models.py`:
+
+```python
+class WebSearchInput(BaseModel):
+    """Input parameters for the WebSearch tool."""
+    query: str
+```
+
+### Tool Output Model
+
+Add a dataclass for the parsed output. Output models are dataclasses (not Pydantic) since they're created by our parsers, not from JSON:
+
+```python
+@dataclass
+class WebSearchLink:
+    """Single search result link."""
+    title: str
+    url: str
+
+@dataclass
+class WebSearchOutput:
+    """Parsed WebSearch tool output."""
+    query: str
+    links: list[WebSearchLink]
+    preamble: Optional[str] = None  # Text before the Links
+    summary: Optional[str] = None   # Markdown analysis after the Links
+```
+
+**Note:** Some tools have structured output with multiple sections. WebSearch is parsed as **preamble/links/summary** - text before Links, the Links JSON array, and markdown analysis after. This allows flexible rendering while preserving all content.
+
+### Update Type Unions
+
+Add the new types to the `ToolInput` and `ToolOutput` unions:
+
+```python
+ToolInput = Union[
+    # ... existing types ...
+    WebSearchInput,
+    ToolUseContent,  # Generic fallback - keep last
+]
+
+ToolOutput = Union[
+    # ... existing types ...
+    WebSearchOutput,
+    ToolResultContent,  # Generic fallback - keep last
+]
+```
+
+## Step 2: Implement Factory Functions
+
+In `factories/tool_factory.py`:
+
+### Register Input Model
+
+Add the input model to `TOOL_INPUT_MODELS`:
+
+```python
+TOOL_INPUT_MODELS: dict[str, type[BaseModel]] = {
+    # ... existing entries ...
+    "WebSearch": WebSearchInput,
+}
+```
+
+### Implement Output Parser
+
+**Important**: Always check if the tool has structured `toolUseResult` data available. This is the preferred approach because:
+- It's more reliable than regex parsing of text content
+- It often contains metadata (timing, byte counts, status codes) not in the text
+- The structure is well-defined and type-safe
+
+Example `toolUseResult` structures in test data:
+```json
+// WebSearch
+{"query": "...", "results": [...], "durationSeconds": 15.7}
+
+// WebFetch
+{"url": "...", "result": "...", "code": 200, "codeText": "OK", "bytes": 12345, "durationMs": 1500}
+```
+
+Create a parser function that extracts from `toolUseResult`:
+
+```python
+def _parse_websearch_from_structured(
+    tool_use_result: ToolUseResult,
+) -> Optional[WebSearchOutput]:
+    """Parse WebSearch from structured toolUseResult data.
+
+    The toolUseResult for WebSearch has the format:
+    {
+        "query": "search query",
+        "results": [
+            {"tool_use_id": "...", "content": [{"title": "...", "url": "..."}]},
+            "Analysis text..."
+        ]
+    }
+    """
+    if not isinstance(tool_use_result, dict):
+        return None
+    query = tool_use_result.get("query")
+    results = tool_use_result.get("results")
+    # ... extract links from results[0].content, summary from results[1] ...
+    return WebSearchOutput(query=query, links=links, preamble=None, summary=summary)
+
+
+def parse_websearch_output(
+    tool_result: ToolResultContent,
+    file_path: Optional[str],
+    tool_use_result: Optional[ToolUseResult] = None,  # Extended signature
+) -> Optional[WebSearchOutput]:
+    """Parse WebSearch tool result from structured toolUseResult."""
+    del tool_result, file_path  # Unused
+    if tool_use_result is None:
+        return None
+    return _parse_websearch_from_structured(tool_use_result)
+```
+
+### Register Output Parser
+
+Add to `TOOL_OUTPUT_PARSERS` and **register in `PARSERS_WITH_TOOL_USE_RESULT`** if using the extended signature:
+
+```python
+TOOL_OUTPUT_PARSERS: dict[str, ToolOutputParser] = {
+    # ... existing entries ...
+    "WebSearch": parse_websearch_output,
+}
+
+# REQUIRED for parsers that use toolUseResult - without this, the structured
+# data won't be passed to your parser!
+PARSERS_WITH_TOOL_USE_RESULT: set[str] = {"WebSearch", "WebFetch"}
+```
+
+**Note**: If your parser has the 3-argument signature `(tool_result, file_path, tool_use_result)`, you MUST add it to `PARSERS_WITH_TOOL_USE_RESULT`. Otherwise `create_tool_output()` won't pass the structured data.
+
+## Step 3: Implement HTML Formatters
+
+In `html/tool_formatters.py`:
+
+### Input Formatter
+
+**Design consideration**: The title already shows key info (tool name + primary parameter). Only show content in the body if it adds value or is too long for the title.
+
+```python
+def format_websearch_input(search_input: WebSearchInput) -> str:
+    """Format WebSearch tool use content."""
+    # If query is short enough to fit in title, return empty
+    if len(search_input.query) <= 100:
+        return ""  # Full query shown in title
+    escaped_query = escape_html(search_input.query)
+    return f'<div class="websearch-query">{escaped_query}</div>'
+```
+
+This avoids redundancy when the title already shows everything important.
+
+### Output Formatter
+
+For tools with structured content like WebSearch, combine all parts into markdown then render:
+
+```python
+def _websearch_as_markdown(output: WebSearchOutput) -> str:
+    """Convert WebSearch output to markdown: preamble + links list + summary."""
+    parts = []
+    if output.preamble:
+        parts.extend([output.preamble, ""])
+    for link in output.links:
+        parts.append(f"- [{link.title}]({link.url})")
+    if output.summary:
+        parts.extend(["", output.summary])
+    return "\n".join(parts)
+
+
+def format_websearch_output(output: WebSearchOutput) -> str:
+    """Format WebSearch as single collapsible markdown block."""
+    markdown_content = _websearch_as_markdown(output)
+    return render_markdown_collapsible(markdown_content, "websearch-results")
+```
+
+### Update Exports
+
+Add functions to `__all__`:
+
+```python
+__all__ = [
+    # ... existing exports ...
+    "format_websearch_input",
+    "format_websearch_output",
+]
+```
+
+## Step 4: Wire Up HTML Renderer
+
+In `html/renderer.py`:
+
+### Import Formatters
+
+```python
+from .tool_formatters import (
+    # ... existing imports ...
+    format_websearch_input,
+    format_websearch_output,
+)
+```
+
+### Add Format Methods
+
+```python
+def format_WebSearchInput(self, input: WebSearchInput, _: TemplateMessage) -> str:
+    return format_websearch_input(input)
+
+def format_WebSearchOutput(self, output: WebSearchOutput, _: TemplateMessage) -> str:
+    return format_websearch_output(output)
+```
+
+### Add Title Method (Optional)
+
+For a custom title in the message header:
+
+```python
+def title_WebSearchInput(self, input: WebSearchInput, message: TemplateMessage) -> str:
+    return self._tool_title(message, "🔎", f'"{input.query}"')
+```
+
+## Step 5: Implement Markdown Renderer
+
+In `markdown/renderer.py`:
+
+### Import Models
+
+```python
+from ..models import (
+    # ... existing imports ...
+    WebSearchInput,
+    WebSearchOutput,
+)
+```
+
+### Add Format Methods
+
+```python
+def format_WebSearchInput(self, input: WebSearchInput, _: TemplateMessage) -> str:
+    """Format -> empty (query shown in title)."""
+    return ""
+
+def format_WebSearchOutput(self, output: WebSearchOutput, _: TemplateMessage) -> str:
+    """Format -> markdown list of links."""
+    parts = [f"Query: *{output.query}*", ""]
+    for link in output.links:
+        parts.append(f"- [{link.title}]({link.url})")
+    return "\n".join(parts)
+
+def title_WebSearchInput(self, input: WebSearchInput, _: TemplateMessage) -> str:
+    """Title -> '🔎 WebSearch `query`'."""
+    return f'🔎 WebSearch `{input.query}`'
+```
+
+## Step 6: Add Tests
+
+Create a dedicated test file `test/test_{toolname}_rendering.py`. Tests are **required** - they catch regressions and document expected behavior.
+
+### Test Structure
+
+```python
+"""Test cases for {ToolName} tool rendering."""
+
+from claude_code_log.factories.tool_factory import parse_{toolname}_output
+from claude_code_log.html.tool_formatters import (
+    format_{toolname}_input,
+    format_{toolname}_output,
+)
+from claude_code_log.models import (
+    ToolResultContent,
+    {ToolName}Input,
+    {ToolName}Output,
+)
+
+
+class Test{ToolName}Input:
+    """Test input model and formatting."""
+
+    def test_input_basic(self):
+        """Test input model creation."""
+        ...
+
+    def test_format_input_short(self):
+        """Test formatting when content fits in title."""
+        ...
+
+    def test_format_input_long(self):
+        """Test formatting when content is too long for title."""
+        ...
+
+
+class Test{ToolName}Parser:
+    """Test output parsing."""
+
+    def test_parse_structured_output(self):
+        """Test parsing from structured toolUseResult."""
+        ...
+
+    def test_parse_minimal_output(self):
+        """Test parsing with only required fields."""
+        ...
+
+    def test_parse_missing_field(self):
+        """Test graceful failure with missing required field."""
+        ...
+
+    def test_parse_no_tool_use_result(self):
+        """Test returns None when no toolUseResult."""
+        ...
+
+
+class Test{ToolName}OutputFormatting:
+    """Test output HTML formatting."""
+
+    def test_format_output_full(self):
+        """Test formatting with all metadata."""
+        ...
+
+    def test_format_output_minimal(self):
+        """Test formatting with minimal data."""
+        ...
+```
+
+### Running Tests
+
+```bash
+# Run just your new tests
+uv run pytest test/test_{toolname}_rendering.py -v
+
+# Run full test suite to check for regressions
+uv run pytest -n auto -m "not (tui or browser)" -v
+```
+
+## Checklist
+
+### Models (`models.py`)
+- [ ] Add input model (Pydantic `BaseModel`)
+- [ ] Add output model (dataclass with all fields from `toolUseResult`)
+- [ ] Update `ToolInput` union
+- [ ] Update `ToolOutput` union
+
+### Factory (`factories/tool_factory.py`)
+- [ ] Add to `TOOL_INPUT_MODELS`
+- [ ] Import output model
+- [ ] Implement output parser with 3-arg signature if using `toolUseResult`
+- [ ] Add to `TOOL_OUTPUT_PARSERS`
+- [ ] Add to `PARSERS_WITH_TOOL_USE_RESULT` (required if parser uses `toolUseResult`)
+
+### HTML (`html/tool_formatters.py`, `html/renderer.py`)
+- [ ] Import models
+- [ ] Add input formatter function
+- [ ] Add output formatter function
+- [ ] Update `__all__` exports
+- [ ] Wire up `format_{Input}` method in renderer
+- [ ] Wire up `format_{Output}` method in renderer
+- [ ] Add `title_{Input}` method in renderer
+
+### Markdown (`markdown/renderer.py`)
+- [ ] Import models
+- [ ] Add `format_{Input}` method
+- [ ] Add `format_{Output}` method
+- [ ] Add `title_{Input}` method
+
+### Tests (`test/test_{toolname}_rendering.py`)
+- [ ] Create test file
+- [ ] Test input model creation
+- [ ] Test input formatting (short/long content)
+- [ ] Test parser with full structured data
+- [ ] Test parser with minimal data
+- [ ] Test parser with missing fields (graceful failure)
+- [ ] Test parser with no `toolUseResult`
+- [ ] Test output formatting
+- [ ] Run full test suite to verify no regressions

{claude_code_log-1.0.0 → claude_code_log-1.1.1}/.vscode/settings.json

@@ -5,4 +5,7 @@
         "docs/claude-code-log-transcript.html": true,
         "test/test_data/cache/**": true,
     },
-}
+    "python.defaultInterpreterPath": "${workspaceFolder}/.venv/bin/python",
+    "python-envs.defaultEnvManager": "ms-python.python:venv",
+    "python-envs.pythonProjects": []
+}

{claude_code_log-1.0.0 → claude_code_log-1.1.1}/CHANGELOG.md

@@ -6,6 +6,36 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 
+## [1.1.1] - 2026-03-10
+
+### Changed
+
+- **Fix build cold start + format justfile**
+- **fix: handle None level in SystemMessage title (#100)**
+
+
+## [1.1.0] - 2026-03-06
+
+### Changed
+
+- **Fix WebSearch and WebFetch rendering in agent transcripts (#98)**
+- **Fix fold-bar colors and System Hook alignment (#89)**
+- **Add WebFetch tool renderer (#87)**
+- **Merge pull request #83 from daaain/dev/websearch-tool-renderer**
+- **Update some outdated docs + VS Code insists on these settings (#86)**
+- **Fix double tab opening when clicking links in TUI MarkdownViewer**
+- **Simplify WebSearch parser and improve rendering**
+- **Use structured toolUseResult for WebSearch parsing**
+- **Add analysis content support to WebSearch output**
+- **Add documentation for implementing tool renderers**
+- **Add WebSearch HTML and Markdown formatters**
+- **Add WebSearch tool models and factory parser**
+- **Fix snapshot + make sure snapshot order is stable**
+- **Improve CSS layout to be responsive for mobile small screens (#77)**
+- **Update pyright to 1.1.408 (#82)**
+- **Support subagents directory structure (Claude Code 2.1.2+) (#80)**
+
+
 ## [1.0.0] - 2026-01-22
 
 BREAKING CHANGE: cache is now using a SQLite database instead of JSON files!

{claude_code_log-1.0.0 → claude_code_log-1.1.1}/CONTRIBUTING.md

@@ -226,14 +226,14 @@ The interactive timeline is implemented in JavaScript within `claude_code_log/te
 
 ## Cache System
 
-The tool implements a caching system for performance:
+The tool implements a SQLite-based caching system for performance:
 
-- **Location**: `.cache/` directory within each project folder
+- **Location**: `claude-code-log-cache.db` in the projects directory (or set `CLAUDE_CODE_LOG_CACHE_PATH` env var)
 - **Contents**: Pre-parsed session metadata (IDs, summaries, timestamps, token usage)
 - **Invalidation**: Automatic detection based on file modification times
 - **Performance**: 10-100x faster loading for large projects
 
-The cache automatically rebuilds when source files change or cache version changes.
+The cache automatically rebuilds when source files change or cache schema version changes.
 
 ## Release Process
 

{claude_code_log-1.0.0 → claude_code_log-1.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: claude-code-log
-Version: 1.0.0
+Version: 1.1.1
 Summary: Convert Claude Code transcript JSONL files to HTML
 Project-URL: Homepage, https://github.com/daaain/claude-code-log
 Project-URL: Issues, https://github.com/daaain/claude-code-log/issues
@@ -271,5 +271,4 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, testing, and archi
 - add minimalist theme and make it light + dark; animate gradient background in fancy theme
 - do we need special handling for hooks?
 - make processing parallel, currently we only use 1 CPU (core) and it's slow
-- migrate cache from JSON files to SQLite to make it faster and more versatile for downstream tasks and analytics
 - merge git worktree directories

{claude_code_log-1.0.0 → claude_code_log-1.1.1}/README.md

@@ -247,5 +247,4 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, testing, and archi
 - add minimalist theme and make it light + dark; animate gradient background in fancy theme
 - do we need special handling for hooks?
 - make processing parallel, currently we only use 1 CPU (core) and it's slow
-- migrate cache from JSON files to SQLite to make it faster and more versatile for downstream tasks and analytics
 - merge git worktree directories

{claude_code_log-1.0.0 → claude_code_log-1.1.1}/claude_code_log/converter.py

@@ -252,11 +252,25 @@ def load_transcript(
     agent_messages_map: dict[str, list[TranscriptEntry]] = {}
     if agent_ids:
         parent_dir = jsonl_path.parent
+        session_basename = (
+            jsonl_path.stem
+        )  # e.g., "29ccd257-68b1-427f-ae5f-6524b7cb6f20"
         for agent_id in agent_ids:
+            # Try legacy location first (same directory as session file)
             agent_file = parent_dir / f"agent-{agent_id}.jsonl"
             # Skip if the agent file is the same as the current file (self-reference)
             if agent_file == jsonl_path:
                 continue
+            # Try new subagents directory structure (Claude Code 2.1.2+)
+            if not agent_file.exists():
+                subagent_file = (
+                    parent_dir
+                    / session_basename
+                    / "subagents"
+                    / f"agent-{agent_id}.jsonl"
+                )
+                if subagent_file.exists():
+                    agent_file = subagent_file
             if agent_file.exists():
                 if not silent:
                     print(f"Loading agent file {agent_file}...")