claude-code-viewer/CLAUDE.md

CLAUDE.md

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

Project Overview

This is a web-based viewer for Claude Code conversation history files. The application provides a UI to browse and view JSONL conversation files from Claude Code projects stored in ~/.claude/projects/.

Development Commands

Start development server:

pnpm dev

This runs Next.js on port 3400 with Turbopack for fast development.

Build and type checking:

pnpm build
pnpm typecheck

Linting and formatting:

pnpm lint       # Run all lint checks
pnpm fix        # Fix all linting and formatting issues

Testing:

pnpm test       # Run tests once
pnpm test:watch # Run tests in watch mode

Architecture Overview

Technology Stack

• Frontend: Next.js 15 with React 19, TypeScript
• Backend: Hono.js API routes (served via Next.js API routes)
• Styling: Tailwind CSS with shadcn/ui components
• Data fetching: TanStack Query (React Query)
• Validation: Zod schemas
• Code formatting: Biome (replaces ESLint + Prettier)

Key Architecture Patterns

Monorepo Structure: Single Next.js app with integrated backend API

API Layer: Hono.js app mounted at /api with type-safe routes:

• /api/projects - List all Claude projects
• /api/projects/:projectId - Get project details and sessions
• /api/projects/:projectId/sessions/:sessionId - Get session conversations
• /api/events/state_changes - Server-Sent Events for real-time file monitoring

Data Flow:

1. Backend reads JSONL files from ~/.claude/projects/
2. Parses and validates conversation entries with Zod schemas
3. Frontend fetches via type-safe API client with TanStack Query
4. Real-time updates via Server-Sent Events for file system changes

Type Safety:

• Zod schemas for conversation data validation (src/lib/conversation-schema/)
• Type-safe API client with Hono and Zod validation
• Strict TypeScript configuration extending @tsconfig/strictest

File Structure Patterns

Conversation Schema (src/lib/conversation-schema/):

• Modular Zod schemas for different conversation entry types
• Union types for flexible conversation parsing
• Separate schemas for content types, tools, and message formats

Server Services (src/server/service/):

• Project operations: getProjects, getProject, getProjectMeta
• Session operations: getSessions, getSession, getSessionMeta
• Parsing utilities: parseJsonl, parseCommandXml
• File monitoring: FileWatcherService for real-time updates

Frontend Structure:

• Page components in app router structure
• Reusable UI components in src/components/ui/
• Custom hooks for data fetching (useProject, useConversations)
• Conversation display components in nested folders

Data Sources

The application reads Claude Code history from:

• Primary location: ~/.claude/projects/ (defined in src/server/service/paths.ts)
• File format: JSONL files containing conversation entries
• Structure: Project folders containing session JSONL files
• Real-time monitoring: Watches for file changes and updates UI automatically

Key Components

Conversation Parsing:

• JSONL parser validates each line against conversation schema
• Handles different entry types: User, Assistant, Summary, System
• Supports various content types: Text, Tool Use, Tool Result, Thinking

Command Detection:

• Parses XML-like command structures in conversation content
• Extracts command names and arguments for better display
• Handles different command formats (slash commands, local commands)

Key Features

Real-time Updates:

• FileWatcherService monitors ~/.claude/projects/ using Node.js fs.watch()
• Server-Sent Events stream for live UI updates
• Automatic refresh when conversation files are modified
• Heartbeat mechanism for connection health monitoring

CLI Installation:

• Can be installed via PORT=3400 npx github:d-kimuson/claude-code-viewer
• Standalone Next.js build with embedded dependencies
• Binary entry point at dist/index.js

Development Notes

• Biome handles both linting and formatting (no ESLint/Prettier)
• Vitest for testing with global test setup
• TanStack Query for server state management with error boundaries
• Jotai atoms for client-side state (filtering, UI state)
• React 19 with Suspense boundaries for progressive loading