{"id":29581578,"url":"https://github.com/daaain/claude-code-log","last_synced_at":"2025-07-21T11:07:17.840Z","repository":{"id":299059294,"uuid":"1001931311","full_name":"daaain/claude-code-log","owner":"daaain","description":"A Python CLI tool that converts Claude Code transcript JSONL files into readable HTML format.","archived":false,"fork":false,"pushed_at":"2025-07-14T23:29:42.000Z","size":70459,"stargazers_count":149,"open_issues_count":4,"forks_count":13,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-07-15T03:48:58.468Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://pypi.org/project/claude-code-log/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/daaain.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-14T10:50:43.000Z","updated_at":"2025-07-14T23:29:46.000Z","dependencies_parsed_at":"2025-07-15T01:13:08.623Z","dependency_job_id":"6b2d8862-7389-47df-aa0c-0eb4bef8f9d5","html_url":"https://github.com/daaain/claude-code-log","commit_stats":null,"previous_names":["daaain/claude-code-log"],"tags_count":16,"template":false,"template_full_name":null,"purl":"pkg:github/daaain/claude-code-log","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/daaain%2Fclaude-code-log","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/daaain%2Fclaude-code-log/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/daaain%2Fclaude-code-log/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/daaain%2Fclaude-code-log/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/daaain","download_url":"https://codeload.github.com/daaain/claude-code-log/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/daaain%2Fclaude-code-log/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266127424,"owners_count":23880441,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-07-19T20:01:51.286Z","updated_at":"2025-07-21T11:07:17.831Z","avatar_url":"https://github.com/daaain.png","language":"Python","readme":"# Claude Code Log\n\nA Python CLI tool that converts Claude Code transcript JSONL files into readable HTML format.\n\n[claude_code_log.webm](https://github.com/user-attachments/assets/12d94faf-6901-4429-b4e6-ea5f102d0c1c)\n\n## Project Overview\n\n📋 **[View Changelog](CHANGELOG.md)** - See what's new in each release\n\nThis tool generates clean, minimalist HTML pages showing user prompts and assistant responses chronologically. It's designed to create a readable log of your Claude Code interactions with support for both individual files and entire project hierarchies.\n\n[See example log (generated from real usage on this project).](https://daaain.github.io/claude-code-log/claude-code-log-transcript.html)\n\n## Quickstart\n\nTL;DR: run the command below and browse the pages generated from your entire Claude Code archives:\n\n```sh\nuvx claude-code-log@latest --open-browser\n```\n\n## Key Features\n\n- **Interactive TUI (Terminal User Interface)**: Browse and manage Claude Code sessions with real-time navigation, summaries, and quick actions for HTML export and session resuming\n- **Project Hierarchy Processing**: Process entire `~/.claude/projects/` directory with linked index page\n- **Individual Session Files**: Generate separate HTML files for each session with navigation links\n- **Single File or Directory Processing**: Convert individual JSONL files or specific directories\n- **Session Navigation**: Interactive table of contents with session summaries and quick navigation\n- **Token Usage Tracking**: Display token consumption for individual messages and session totals\n- **Runtime Message Filtering**: JavaScript-powered filtering to show/hide message types (user, assistant, system, tool use, etc.)\n- **Chronological Ordering**: All messages sorted by timestamp across sessions\n- **Interactive timeline**: Generate an interactive, zoomable timeline grouped by message times to navigate conversations visually\n- **Cross-Session Summary Matching**: Properly match async-generated summaries to their original sessions\n- **Date Range Filtering**: Filter messages by date range using natural language (e.g., \"today\", \"yesterday\", \"last week\")\n- **Rich Message Types**: Support for user/assistant messages, tool use/results, thinking content, images\n- **System Command Visibility**: Show system commands (like `init`) in expandable details with structured parsing\n- **Markdown Rendering**: Server-side markdown rendering with syntax highlighting using mistune\n- **Floating Navigation**: Always-available back-to-top button and filter controls\n- **CLI Interface**: Simple command-line tool using Click\n\n## What Problems Does This Solve?\n\nThis tool helps you answer questions like:\n\n- **\"How can I review all my Claude Code conversations?\"**\n- **\"What did I work on with Claude yesterday/last week?\"**\n- **\"How much are my Claude Code sessions costing?\"**\n- **\"How can I search through my entire Claude Code history?\"**\n- **\"What tools did Claude use in this project?\"**\n- **\"How can I share my Claude Code conversation with others?\"**\n- **\"What's the timeline of my project development?\"**\n- **\"How can I analyse patterns in my Claude Code usage?\"**\n\n## Usage\n\n### Interactive TUI (Terminal User Interface)\n\nThe TUI provides an interactive interface for browsing and managing Claude Code sessions with real-time navigation, session summaries, and quick actions.\n\n```bash\n# Launch TUI for all projects (default behavior)\nclaude-code-log --tui\n\n# Launch TUI for specific project directory\nclaude-code-log /path/to/project --tui\n\n# Launch TUI for specific Claude project\nclaude-code-log my-project --tui  # Automatically converts to ~/.claude/projects/-path-to-my-project\n```\n\n**TUI Features:**\n\n- **Session Listing**: Interactive table showing session IDs, summaries, timestamps, message counts, and token usage\n- **Smart Summaries**: Prioritizes Claude-generated summaries over first user messages for better session identification\n- **Working Directory Matching**: Automatically finds and opens projects matching your current working directory\n- **Quick Actions**:\n  - `h` or \"Export to HTML\" button: Generate and open session HTML in browser\n  - `c` or \"Resume in Claude Code\" button: Continue session with `claude -r \u003csessionId\u003e`\n  - `r` or \"Refresh\" button: Reload session data from files\n  - `p` or \"Projects View\" button: Switch to project selector view\n- **Project Statistics**: Real-time display of total sessions, messages, tokens, and date range\n- **Cache Integration**: Leverages existing cache system for fast loading with automatic cache validation\n- **Keyboard Navigation**: Arrow keys to navigate, Enter to expand row details, `q` to quit\n- **Row Expansion**: Press Enter to expand selected row showing full summary, first user message, working directory, and detailed token usage\n\n### Default Behavior (Process All Projects)\n\n```bash\n# Process all projects in ~/.claude/projects/ (default behavior)\nclaude-code-log\n\n# Explicitly process all projects\nclaude-code-log --all-projects\n\n# Process all projects and open in browser\nclaude-code-log --open-browser\n\n# Process all projects with date filtering  \nclaude-code-log --from-date \"yesterday\" --to-date \"today\"\nclaude-code-log --from-date \"last week\"\n\n# Skip individual session files (only create combined transcripts)\nclaude-code-log --no-individual-sessions\n```\n\nThis creates:\n\n- `~/.claude/projects/index.html` - Top level index with project cards and statistics\n- `~/.claude/projects/project-name/combined_transcripts.html` - Individual project pages (these can be several megabytes)\n- `~/.claude/projects/project-name/session-{session-id}.html` - Individual session pages\n\n### Single File or Directory Processing\n\n```bash\n# Single file\nclaude-code-log transcript.jsonl\n\n# Specific directory\nclaude-code-log /path/to/transcript/directory\n\n# Custom output location\nclaude-code-log /path/to/directory -o combined_transcripts.html\n\n# Open in browser after conversion\nclaude-code-log /path/to/directory --open-browser\n\n# Filter by date range (supports natural language)\nclaude-code-log /path/to/directory --from-date \"yesterday\" --to-date \"today\"\nclaude-code-log /path/to/directory --from-date \"3 days ago\" --to-date \"yesterday\"\n```\n\n## File Structure\n\n- `claude_code_log/parser.py` - Data extraction and parsing from JSONL files\n- `claude_code_log/renderer.py` - HTML generation and template rendering\n- `claude_code_log/converter.py` - High-level conversion orchestration\n- `claude_code_log/cli.py` - Command-line interface with project discovery\n- `claude_code_log/models.py` - Pydantic models for transcript data structures\n- `claude_code_log/templates/` - Jinja2 HTML templates\n  - `transcript.html` - Main transcript viewer template\n  - `index.html` - Project directory index template\n- `pyproject.toml` - Project configuration with dependencies\n\n## Development\n\nThe project uses:\n\n- Python 3.12+ with uv package management\n- Click for CLI interface and argument parsing\n- Pydantic for robust data modeling and validation\n- dateparser for natural language date parsing\n- Standard library for JSON/HTML processing\n- Minimal dependencies for portability\n- mistune for quick Markdown rendering\n\n## Development Commands\n\n### Testing\n\nThe project uses a categorized test system to avoid async event loop conflicts between different testing frameworks:\n\n#### Test Categories\n\n- **Unit Tests** (no mark): Fast, standalone tests with no external dependencies\n- **TUI Tests** (`@pytest.mark.tui`): Tests for the Textual-based Terminal User Interface\n- **Browser Tests** (`@pytest.mark.browser`): Playwright-based tests that run in real browsers\n\n#### Running Tests\n\n```bash\n# Run only unit tests (fast, recommended for development)\nuv run pytest -m \"not (tui or browser)\"\n\n# Run TUI tests (isolated event loop)\nuv run pytest -m tui\n\n# Run browser tests (requires Chromium)\nuv run pytest -m browser\n\n# Run all tests in sequence (separated to avoid conflicts)\nuv run pytest -m \"not tui and not browser\"; uv run pytest -m tui; uv run pytest -m browser\n```\n\n#### Prerequisites\n\nBrowser tests require Chromium to be installed:\n\n```bash\nuv run playwright install chromium\n```\n\n#### Why Test Categories?\n\nThe test suite is categorized because:\n\n- **TUI tests** use Textual's async event loop (`run_test()`)\n- **Browser tests** use Playwright's internal asyncio\n- **pytest-asyncio** manages async test execution\n\nRunning all tests together can cause \"RuntimeError: This event loop is already running\" conflicts. The categorization ensures reliable test execution by isolating different async frameworks.\n\n### Test Coverage\n\nGenerate test coverage reports:\n\n```bash\n# Run tests with coverage\nuv run pytest --cov=claude_code_log --cov-report=html --cov-report=term\n\n# Generate HTML coverage report only\nuv run pytest --cov=claude_code_log --cov-report=html\n\n# View coverage in terminal\nuv run pytest --cov=claude_code_log --cov-report=term-missing\n```\n\nHTML coverage reports are generated in `htmlcov/index.html`.\n\n**Comprehensive Testing \u0026 Style Guide**: The project includes extensive testing infrastructure and visual documentation. See [test/README.md](test/README.md) for details on:\n\n- **Unit Tests**: Template rendering, message type handling, edge cases\n- **Test Coverage**: 78%+ coverage across all modules with detailed reporting\n- **Visual Style Guide**: Interactive documentation showing all message types\n- **Representative Test Data**: Real-world JSONL samples for development\n- **Style Guide Generation**: Create visual documentation with `uv run python scripts/generate_style_guide.py`\n\n### Code Quality\n\n- **Format code**: `ruff format`\n- **Lint and fix**: `ruff check --fix`\n- **Type checking**: `uv run pyright` and `uv run ty check`\n\n### All Commands\n\n- **Test (Unit only)**: `uv run pytest`\n- **Test (TUI)**: `uv run pytest -m tui`\n- **Test (Browser)**: `uv run pytest -m browser`\n- **Test (All categories)**: `uv run pytest -m \"not tui and not browser\"; uv run pytest -m tui; uv run pytest -m browser`\n- **Test with Coverage**: `uv run pytest --cov=claude_code_log --cov-report=html --cov-report=term`\n- **Format**: `ruff format`\n- **Lint**: `ruff check --fix`\n- **Type Check**: `uv run pyright` and `uv run ty check`\n- **Generate Style Guide**: `uv run python scripts/generate_style_guide.py`\n\nTest with Claude transcript JSONL files typically found in `~/.claude/projects/` directories.\n\n## Release Process (For Maintainers)\n\nThe project uses an automated release process with semantic versioning. Here's how to create and publish a new release:\n\n### Quick Release\n\n```bash\n# Bump version and create release (patch/minor/major)\njust release-prep patch    # For bug fixes\njust release-prep minor    # For new features\njust release-prep major    # For breaking changes\n\n# Or specify exact version\njust release-prep 0.4.3\n\n# Preview what would be released\njust release-preview\n\n# Push to PyPI and create GitHub release\njust release-push\n```\n\n3. **GitHub Release Only**: If you need to create/update just the GitHub release:\n\n   ```bash\n   just github-release          # For latest tag\n   just github-release 0.4.2    # For specific version\n   ```\n\n### Cache Structure and Benefits\n\nThe tool implements a sophisticated caching system for performance:\n\n- **Cache Location**: `.cache/` directory within each project folder\n- **Session Metadata**: Pre-parsed session information (IDs, summaries, timestamps, token usage)\n- **Timestamp Index**: Enables fast date-range filtering without parsing full files\n- **Invalidation**: Automatic detection of stale cache based on file modification times\n- **Performance**: 10-100x faster loading for large projects with many sessions\n\nThe cache is transparent to users and automatically rebuilds when:\n\n- Source JSONL files are modified\n- New sessions are added\n- Cache structure version changes\n\n## Project Hierarchy Output\n\nWhen processing all projects, the tool generates:\n\n```sh\n~/.claude/projects/\n├── index.html                           # Master index with project cards\n├── project1/\n│   ├── combined_transcripts.html        # Combined project page\n│   ├── session-{session-id}.html        # Individual session pages\n│   └── session-{session-id2}.html       # More session pages...\n├── project2/\n│   ├── combined_transcripts.html\n│   └── session-{session-id}.html\n└── ...\n```\n\n### Index Page Features\n\n- **Project Cards**: Each project shown as a clickable card with statistics\n- **Session Navigation**: Expandable session list with summaries and quick access to individual session files\n- **Summary Statistics**: Total projects, transcript files, and message counts with token usage\n- **Recent Activity**: Projects sorted by last modification date\n- **Quick Navigation**: One-click access to combined transcripts or individual sessions\n- **Clean URLs**: Readable project names converted from directory names\n\n## Message Types Supported\n\n- **User Messages**: Regular user inputs and prompts\n- **Assistant Messages**: Claude's responses with token usage display\n- **Summary Messages**: Session summaries with cross-session matching\n- **System Commands**: Commands like `init` shown in expandable details with structured parsing\n- **Tool Use**: Tool invocations with collapsible details and special TodoWrite rendering\n- **Tool Results**: Tool execution results with error handling\n- **Thinking Content**: Claude's internal reasoning processes\n- **Images**: Pasted images and screenshots\n\n## HTML Output Features\n\n- **Responsive Design**: Works on desktop and mobile\n- **Runtime Message Filtering**: JavaScript controls to show/hide message types with live counts\n- **Session Navigation**: Interactive table of contents with session summaries and timestamp ranges\n- **Token Usage Display**: Individual message and session-level token consumption tracking\n- **Syntax Highlighting**: Code blocks properly formatted with markdown rendering\n- **Markdown Support**: Server-side rendering with mistune including:\n  - Headers, lists, emphasis, strikethrough\n  - Code blocks and inline code\n  - Links, images, and tables\n  - GitHub Flavored Markdown features\n- **Collapsible Content**: Tool use, system commands, and long content in expandable sections\n- **Floating Controls**: Always-available filter button, details toggle, and back-to-top navigation\n- **Cross-Session Features**: Summaries properly matched across async sessions\n\n## Installation\n\nInstall using pip:\n\n```bash\npip install claude-code-log\n```\n\nOr run directly with uvx (no separate installation step required):\n\n```bash\nuvx claude-code-log@latest\n```\n\nOr install from source:\n\n```bash\ngit clone https://github.com/daaain/claude-code-log.git\ncd claude-code-log\nuv sync\nuv run claude-code-log\n```\n\n## TODO\n\n- tutorial overlay\n- integrate `claude-trace` request logs if present?\n- Localised number formatting and timezone adjustment runtime? For this we'd need to make Jinja template variables more granular\n- convert images to WebP as screenshots are often huge PNGs – this might be time consuming to keep redoing (so would also need some caching) and need heavy dependencies with compilation (unless there are fast pure Python conversation libraries? Or WASM?)\n- add special formatting for built-in tools: Bash, Glob, Grep, LS, exit_plan_mode, Read, Edit, MultiEdit, Write, NotebookRead, NotebookEdit, WebFetch, TodoRead, TodoWrite, WebSearch\n  - render Edit / MultiEdit as diff(s)?\n- do we need to handle compacted conversation?\n- Thinking block should have Markdown rendering as sometimes they have formatting\n- system blocks like `init` also don't render perfectly, losing new lines\n- add `ccusage` like daily summary and maybe some textual summary too based on Claude generate session summaries?\n– import logs from @claude Github Actions\n- stream logs from @claude Github Actions, see [octotail](https://github.com/getbettr/octotail)\n- wrap up CLI as Github Action to run after Cladue Github Action and process [output](https://github.com/anthropics/claude-code-base-action?tab=readme-ov-file#outputs)\n- extend into a VS Code extension that reads the JSONL real-time and displays stats like current context usage and implements a UI to see messages, todos, permissions, config, MCP status, etc\n- feed the filtered user messages to headless claude CLI to distill the user intent from the session\n- filter message type on Python (CLI) side too, not just UI\n- Markdown renderer\n- figure out minimum Python version and introduce a testing matrix\n- add minimalist theme and make it light + dark; animate gradient background in fancy theme\n- do we need special handling for hooks?\n","funding_links":[],"categories":["Tools \u0026 Utilities","Python","监控与分析"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdaaain%2Fclaude-code-log","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdaaain%2Fclaude-code-log","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdaaain%2Fclaude-code-log/lists"}