cclogviewer: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is a Go application that converts Claude Code JSONL log files into interactive HTML for easy reading. It's a command-line tool designed to help developers visualize and navigate their Claude Code session logs.

Common Development Commands

Building

make build                    # Build the binary
make build-release           # Build with version info
make build-all              # Build for all platforms (Linux, Darwin, Windows)

Running

go run cmd/cclogviewer/main.go -input file.jsonl    # Run directly with Go
./bin/cclogviewer -input file.jsonl                 # Run built binary

Testing

make test                    # Run all unit tests
make test-coverage          # Run tests with coverage report (HTML)
make test-coverage-report   # Show coverage percentage in terminal
make test-integration       # Run integration tests
make test-all              # Run all tests (unit + integration)
make benchmark             # Run benchmarks

Code Quality

make fmt                     # Format Go code
make lint                    # Run linter (requires golangci-lint)

Installation

make install                 # Install to /usr/local/bin
make install PREFIX=/opt     # Install to custom prefix
make uninstall              # Remove installed binary

Other Commands

make clean                   # Clean build artifacts
make deps                    # Download and tidy dependencies
make release                # Create release archives for all platforms

Architecture

The codebase follows a clean architecture pattern with clear separation of concerns:

• cmd/cclogviewer/: Entry point that handles CLI flags and orchestrates the conversion process
• internal/browser/: Cross-platform browser opening functionality
• internal/constants/: Centralized constants package containing all magic values organized by category (buffers, thresholds, types, etc.)
• internal/debug/: Debug utilities for development
• internal/models/: Data structures for log entries and tool calls
• internal/parser/: JSONL file parsing with configurable buffer sizes (removed 10MB line limit)
• internal/processor/: Transforms raw log entries into hierarchical structures
  • Modular message handlers for different entry types
  • Tool call matching and result correlation
  • Sidechain (Task tool) conversation grouping
  • tools/: Tool processing system with formatter interface
    • formatters/: Individual tool formatters (bash, edit, multiedit, read, todowrite, write)
    • diff/: Diff computation and formatting utilities
• internal/renderer/: HTML generation with modular templates
  • ansi/: ANSI color code parsing and conversion
  • builders/: HTML building utilities
  • templates/: Base HTML structure and template definitions (embedded at compile time)
  • templates/styles/: Modular CSS files (main.css, themes.css, components.css)
  • templates/scripts/: JavaScript functionality (main.js)
  • templates/partials/: Reusable HTML components (entry.html, tool-call.html)
• internal/testutil/: Shared test utilities and helpers for consistent testing
• internal/utils/: Shared utilities following DRY principles
  • extraction.go: JSON extraction utilities (ExtractString, ExtractBool, etc.)
  • validation.go: Field validation utilities
  • html.go: HTML escaping and formatting utilities
  • json.go: JSON manipulation utilities