aljaz/claude-code-viewer
1
0
Fork 0
mirror of https://github.com/aljazceru/claude-code-viewer.git synced 2026-01-06 23:24:21 +01:00
Code Issues Packages Projects Releases Wiki Activity

docs: write docs

Browse Source
This commit is contained in:
d-kimsuon
2025-08-31 17:34:28 +09:00
parent b4d2bfa2c1
commit 62ec94798e
4 changed files with 397 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files

30
CLAUDE.md
View File

@@ -12,7 +12,7 @@ This is a web-based viewer for Claude Code conversation history files. The appli
```bash
pnpm dev
```
This runs both Next.js (port 3400) and pathpida in watch mode for type-safe routing.
This runs Next.js on port 3400 with Turbopack for fast development.
**Build and type checking:**
```bash
@@ -50,15 +50,17 @@ pnpm test:watch # Run tests in watch mode
- `/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 React Query
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/`)
- pathpida for type-safe routing (`src/lib/$path.ts`)
- Type-safe API client with Hono and Zod validation
- Strict TypeScript configuration extending `@tsconfig/strictest`
### File Structure Patterns
@@ -72,6 +74,7 @@ pnpm test:watch # Run tests in watch mode
- 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
@@ -82,9 +85,10 @@ pnpm test:watch # Run tests in watch mode
### Data Sources
The application reads Claude Code history from:
- **Primary location**: `~/.claude/projects/` (defined in `src/server/service/paths.ts:4`)
- **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
@@ -98,9 +102,23 @@ The application reads Claude Code history from:
- 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
- Uses `pathpida` for compile-time route validation
- 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
- 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

126
README.md Normal file
View File

@@ -0,0 +1,126 @@
# Claude Code Viewer
A web-based viewer for browsing Claude Code conversation history files. View and navigate your Claude Code project conversations through a clean, intuitive interface.
## Overview
Claude Code Viewer parses JSONL conversation files stored in `~/.claude/projects/` and presents them in a human-readable web UI. Browse projects, sessions, and detailed conversation history with support for tool usage, subtasks, and real-time file monitoring.
## Features
- **Project Browser** - View all Claude Code projects with metadata and session counts
- **Session Navigation** - Browse conversation sessions within projects with filtering options
- **Conversation Display** - Human-readable format for Claude Code logs with syntax highlighting
- **Subtask Support** - Separate display for subtasks and sidechain conversations
- **Real-time Updates** - Automatic refresh when conversation files are modified
- **File System Watching** - Monitors `~/.claude/projects/` for changes and updates the UI
- **Responsive Design** - Works on desktop and mobile devices
## Installation & Usage
### Quick Start
Run directly from GitHub without installation:
```bash
PORT=3400 npx github:d-kimuson/claude-code-viewer
```
The server will start on port 3400 (or the specified PORT). Open `http://localhost:3400` in your browser.
### Alternative Installation
Clone and run locally:
```bash
git clone https://github.com/d-kimuson/claude-code-viewer.git
cd claude-code-viewer
pnpm i
pnpm build
pnpm start
```
## Requirements
- **Node.js** 18 or later
- **Claude Code** with conversation history in `~/.claude/projects/`
## Data Source
The application reads Claude Code conversation files from:
- **Location**: `~/.claude/projects/<project>/<session-id>.jsonl`
- **Format**: JSONL files containing conversation entries
- **Auto-detection**: Automatically discovers new projects and sessions
## Usage Guide
### 1. Project List
- Browse all Claude Code projects
- View project metadata (name, path, session count, last modified)
- Click any project to view its sessions
### 2. Session Browser
- View all conversation sessions within a project
- Filter to hide empty sessions
- Sessions show message counts and timestamps
- Click to view detailed conversation
### 3. Conversation Viewer
- Full conversation history with proper formatting
- Syntax highlighting for code blocks
- Tool usage and results clearly displayed
- Navigation sidebar for jumping between sessions
- Support for different message types (user, assistant, system, tools)
## Configuration
### Port Configuration
Set a custom port using the `PORT` environment variable:
```bash
PORT=8080 npx github:d-kimuson/claude-code-viewer
```
### Data Directory
The application automatically detects the standard Claude Code directory at `~/.claude/projects/`. No additional configuration is required.
## Browser Support
- Chrome/Chromium 90+
- Firefox 88+
- Safari 14+
- Edge 90+
## Troubleshooting
### No Projects Found
- Ensure Claude Code has been used and has created conversation files
- Check that `~/.claude/projects/` exists and contains project directories
- Verify file permissions allow reading the projects directory
### Connection Issues
- Check that the specified port is not in use
- Ensure firewall settings allow local connections
- Try a different port using the `PORT` environment variable
### Real-time Updates Not Working
- The application uses Server-Sent Events for real-time updates
- Some browsers or network configurations may block SSE connections
- Refresh the page manually to see latest changes
## License
This project is available under the MIT License. See the LICENSE file for details.
## Contributing
See [docs/dev.md](docs/dev.md) for development setup and contribution guidelines.

246
docs/dev.md Normal file
View File

@@ -0,0 +1,246 @@
# Developer Documentation
This document provides technical details for developers contributing to Claude Code Viewer.
## Architecture Overview
### Tech Stack
- **Frontend**: Next.js 15 with React 19, TypeScript (strict configuration)
- **Backend**: Hono.js API routes with Zod validation
- **Styling**: Tailwind CSS with Radix UI components (shadcn/ui pattern)
- **State Management**: TanStack Query + Jotai atoms
- **Code Quality**: Biome (replaces ESLint + Prettier)
- **Testing**: Vitest with watch mode
### Project Structure
```text
src/
├── app/ # Next.js app router
│ ├── projects/ # Project listing and detail pages
│ │ └── [projectId]/ # Dynamic project routes
│ └── layout.tsx # Root layout with providers
├── server/ # Backend API implementation
│ ├── service/ # Core business logic
│ │ ├── file-watcher.ts # Real-time file monitoring
│ │ ├── paths.ts # File system path constants
│ │ └── project.ts # Project/session operations
│ └── api/ # Hono API route handlers
├── lib/
│ ├── conversation-schema/ # Zod schemas for JSONL validation
│ ├── api/ # Type-safe API client
│ └── utils/ # Shared utilities
└── components/
├── ui/ # Reusable UI components
└── conversation/ # Conversation-specific components
```
## Development Setup
### Prerequisites
- Node.js 18 or later
- pnpm (recommended package manager)
- Claude Code with sample conversation data in `~/.claude/projects/`
### Installation
```bash
git clone https://github.com/d-kimuson/claude-code-viewer.git
cd claude-code-viewer
pnpm install
```
### Development Commands
```bash
# Start development server (port 3400)
pnpm dev
# Type checking
pnpm typecheck
# Linting and formatting
pnpm lint # Check all rules
pnpm fix # Fix all issues
# Testing
pnpm test # Run once
pnpm test:watch # Watch mode
```
### Build Process
```bash
pnpm build # Creates standalone Next.js build in .next/standalone/
```
The build creates a standalone application that includes all dependencies for deployment.
## API Architecture
### Endpoints
- `GET /api/projects` - List all projects with metadata
- `GET /api/projects/:projectId` - Get project details and sessions
- `GET /api/projects/:projectId/sessions/:sessionId` - Get conversation data
- `GET /api/events/state_changes` - Server-Sent Events for real-time updates
### Data Flow
1. **File System → Parser**: Read JSONL files from `~/.claude/projects/`
2. **Parser → Validation**: Validate each line against Zod conversation schemas
3. **API → Frontend**: Type-safe data transfer with TanStack Query
4. **Real-time**: File watcher emits SSE events for live updates
### Backend Services
#### Core Services (`src/server/service/`)
- **`getProjects()`** - Scans project directories, returns sorted metadata
- **`getProject(projectId)`** - Fetches project details and session list
- **`getSession(projectId, sessionId)`** - Parses JSONL conversation files
- **`parseJsonl()`** - Validates JSONL lines against conversation schema
#### File Watching (`src/server/service/file-watcher.ts`)
- Singleton service using Node.js `fs.watch()`
- Monitors `~/.claude/projects/` recursively
- Emits `project_changed` and `session_changed` events
- Includes heartbeat mechanism (30s intervals)
## Data Validation
### Conversation Schema (`src/lib/conversation-schema/`)
Modular Zod schemas handle different conversation entry types:
- **Entry Types**: User, Assistant, System, Summary
- **Content Types**: Text, Tool Use, Tool Result, Thinking
- **Validation**: Strict type checking with fallback parsing
### Command Detection
Special XML-like command parsing for enhanced display:
```typescript
parseCommandXml(content: string) // Extracts command names and arguments
```
## Frontend Architecture
### Component Hierarchy
```text
RootLayout (providers, error boundaries)
├── ProjectList (grid of project cards)
├── ProjectDetail
│ ├── SessionList (filterable session grid)
│ └── SessionDetail
│ ├── SessionSidebar (navigation)
│ └── ConversationList (message display)
```
### State Management
- **Server State**: TanStack Query with suspense boundaries
- **Client State**: Jotai atoms for UI state (filters, sidebar state)
- **Real-time**: Server-Sent Events with automatic reconnection
### Type Safety
- **API Types**: Generated from Hono route definitions
- **Schemas**: Zod validation with TypeScript inference
- **Build-time**: Strict TypeScript configuration via `@tsconfig/strictest`
## Code Conventions
### File Organization
- **Services**: Business logic in `src/server/service/`
- **Components**: UI components with co-located styles
- **Schemas**: Modular Zod schemas with clear interfaces
- **Hooks**: Custom hooks for data fetching and state management
### Naming Conventions
- **Files**: `kebab-case.ts`
- **Components**: `PascalCase`
- **Functions**: `camelCase`
- **Constants**: `SCREAMING_SNAKE_CASE`
### Code Style
- **Formatter**: Biome (replaces Prettier)
- **Linter**: Biome (replaces ESLint)
- **Config**: Extends `@tsconfig/strictest` for maximum type safety
## Testing Strategy
### Test Structure
- **Unit Tests**: Individual functions and components
- **Integration Tests**: API routes and data flow
- **Setup**: Vitest with global test configuration
### Test Commands
```bash
pnpm test # Run all tests once
pnpm test:watch # Watch mode for development
```
## Performance Considerations
### Optimization Strategies
- **Static Generation**: Pre-built project metadata
- **Suspense Boundaries**: Progressive loading of conversation data
- **File Watching**: Efficient recursive directory monitoring
- **Memory Management**: Streaming JSONL parsing for large files
### Bundle Analysis
The app uses Next.js with Turbopack for fast development builds and optimized production bundles.
## Contributing Guidelines
### Pull Request Process
1. **Fork** the repository and create a feature branch
2. **Implement** changes following existing code conventions
3. **Test** your changes with `pnpm test`
4. **Lint** code with `pnpm fix`
5. **Type check** with `pnpm typecheck`
6. **Submit** PR with clear description and test coverage
### Code Review Criteria
- Type safety and error handling
- Performance impact on large conversation files
- UI/UX consistency with existing design
- Test coverage for new functionality
- Documentation updates for API changes
### Development Tips
- **Hot Reload**: Use `pnpm dev` for fast development iteration
- **Debug Mode**: Enable verbose logging in file watcher service
- **Mock Data**: Create sample JSONL files for testing edge cases
- **Browser DevTools**: React Query DevTools available in development
## Deployment
### Build Artifacts
- **Standalone**: Self-contained application in `.next/standalone/`
- **Static Assets**: Copied to standalone directory during build
- **Entry Point**: `dist/index.js` for CLI usage
### Environment Variables
- **PORT**: Server port (default: 3400)
- **NODE_ENV**: Environment mode (development/production)
The application is designed to be deployed as a standalone executable that can be installed via npm/npx.

1
package.json
View File

@@ -12,6 +12,7 @@
"scripts": {
"dev": "run-p 'dev:*'",
"dev:next": "PORT=3400 next dev --turbopack",
"start": "node dist/index.js",
"build": "next build && cp -r public .next/standalone/ && cp -r .next/static .next/standalone/.next/",
"lint": "run-s 'lint:*'",
"lint:biome-format": "biome format .",