diff --git a/CLAUDE.md b/CLAUDE.md
index c55acb3..d1497b5 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -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
\ No newline at end of file
+- 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
\ No newline at end of file
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..c68e709
--- /dev/null
+++ b/README.md
@@ -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.
diff --git a/docs/dev.md b/docs/dev.md
new file mode 100644
index 0000000..214c605
--- /dev/null
+++ b/docs/dev.md
@@ -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.
diff --git a/package.json b/package.json
index e0715da..80cfd26 100644
--- a/package.json
+++ b/package.json
@@ -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 .",