mirror of
https://github.com/aljazceru/claude-code-viewer.git
synced 2026-01-03 13:44:23 +01:00
124 lines
4.4 KiB
Markdown
124 lines
4.4 KiB
Markdown
# 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:**
|
|
```bash
|
|
pnpm dev
|
|
```
|
|
This runs Next.js on port 3400 with Turbopack for fast development.
|
|
|
|
**Build and type checking:**
|
|
```bash
|
|
pnpm build
|
|
pnpm typecheck
|
|
```
|
|
|
|
**Linting and formatting:**
|
|
```bash
|
|
pnpm lint # Run all lint checks
|
|
pnpm fix # Fix all linting and formatting issues
|
|
```
|
|
|
|
**Testing:**
|
|
```bash
|
|
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 |