claude-code-viewer/docs/dev.md

Developer Documentation

This document provides technical details for developers contributing to Claude Code Viewer.

Architecture Overview

Frontend

• Framework: Next.js 15 (App Router)
• UI Libraries: React 19, Radix UI, Tailwind CSS
• State Management: Jotai (global state), TanStack Query (server state)

Backend

• API Framework: Hono integrated with Next.js API Routes
  • Type-safe communication via Hono RPC
  • Validation using @hono/zod-validator
• Effect-TS: All backend business logic is implemented using Effect-TS
  • Service layer managed through Effect Context (dependency injection container)
  • Controller → Service layered architecture, with each layer implemented in Effect
  • Type-safe error handling and side effect control

Data Source and Storage

• Single Source of Truth (SSoT): Claude Code's standard session logs (~/.claude/projects/)
  • No separate database; reads directly from JSONL files
  • Strict validation via Zod schemas ensures conversation data integrity
• Caching Mechanism: For performance optimization, metadata is cached in ~/.claude-code-viewer/
  • Frequently accessed data like session lists and project information
  • Cache is automatically invalidated via SSE events

Real-time Synchronization

• Server-Sent Events (SSE): Provides /api/sse endpoint
  • Clients maintain persistent SSE connections to listen for server events
  • Real-time delivery of session log updates, process state changes, etc.
  • Type-safe SSE events (TypeSafeSSE) guarantee payload types for each event kind
  • Client-side easily subscribes to events using the useServerEventListener hook

Session Process Management

Claude Code Viewer provides advanced control over Claude Code session processes:

• After starting a session, the process remains in the background unless explicitly aborted
• Paused sessions can continue without changing the session-id (no resume needed)
• Memory sharing between processes is required, making production build verification crucial

Development Environment Setup

Requirements

• Node.js: Version 20.12.0 or later (see .node-version)
• Package Manager: pnpm 10.8.1 or later

Initial Setup

# Install dependencies
pnpm install

Starting the Development Server

Development Mode (with limitations)

pnpm dev

The development server will start, but with the following limitations:

Next.js Development Server Constraints

The Next.js development server behaves like an Edge Runtime where API Routes don't share memory space. This causes:

1. Initialization runs on every request: Initialization occurs for each API request, degrading performance
2. Session process continuation unavailable: Cannot resume Paused sessions across different requests
3. SSE connection and process management inconsistencies: Events that should be notified via SSE aren't shared between processes

Therefore, development mode is sufficient for UI verification and minor changes, but production build startup is essential for comprehensive testing of session process management and SSE integration.

Production Mode (Recommended)

For comprehensive functionality testing, build and run in production mode:

# Build
pnpm build

# Start production server
pnpm start

The built application is output to the dist/ directory and started with pnpm start.

Quality Assurance

Code Formatter & Linter: Biome

Biome is used as the formatter and linter.

Commands:

# Auto-fix issues
pnpm fix

# Check only (run in CI)
pnpm lint

CI Requirement: Passing Biome checks is mandatory for PR merges.

Unit Tests: Vitest

Vitest-based tests are written for backend core logic (Effect-TS based service layer).

Commands:

# Run once
pnpm test

# Watch mode
pnpm test:watch

Test Coverage: Primarily business logic under src/server/core/

CI Requirement: All tests must pass for PR merges.

Type Checking: TypeScript

pnpm typecheck

Strict type configuration (@tsconfig/strictest) is adopted, emphasizing type safety.

E2E Snapshot Testing (VRT)

Playwright-based snapshot capture is implemented to visually confirm UI changes.

Note: This is Visual Regression Testing (VRT) for confirming UI changes, not traditional testing.

Local Execution

# Run server startup and snapshot capture together
pnpm e2e

# Or execute manually
pnpm e2e:start-server        # Start server
pnpm e2e:capture-snapshots   # Capture snapshots

Important: In local environments, UI varies based on the current path. Do not commit locally captured snapshots.

Automatic Updates in CI

When the vrt label is added to a PR, CI automatically captures and commits snapshots. Use this label for PRs with UI changes to update snapshots.

Project Structure

src/
├── app/                    # Next.js App Router
│   ├── api/[[...route]]/  # Hono API Routes
│   ├── components/         # Page-specific components
│   ├── projects/          # Project-related pages
│   └── ...
├── components/            # Shared UI components
├── lib/                   # Frontend common logic
│   ├── api/              # API client (Hono RPC)
│   ├── sse/              # SSE connection management
│   └── conversation-schema/  # Zod schemas for conversation logs
├── server/               # Backend implementation
│   ├── core/            # Core domain logic (Effect-TS)
│   │   ├── claude-code/ # Claude Code integration
│   │   ├── events/      # SSE event management
│   │   ├── session/     # Session management
│   │   └── ...
│   ├── hono/            # Hono application
│   └── lib/             # Backend common utilities
└── testing/             # Test helpers and mocks

Development Tips

1. Learning Effect-TS: The backend is built with Effect-TS. Refer to the official documentation
2. Debugging SSE: Check the Network tab in browser developer tools to inspect SSE connections
3. Log Inspection: Directly reference JSONL files under ~/.claude/projects/ to understand data structures
4. Mock Data: Mock data for E2E tests in mock-global-claude-dir/ is useful for development reference

Contributing

We welcome contributions! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes with appropriate tests
4. Ensure all quality checks pass (pnpm lint, pnpm test, pnpm typecheck)
5. Submit a pull request with a clear description of your changes

For UI changes, add the vrt label to your PR to update visual snapshots.