claudecodeui/CLAUDE.md

CLAUDE.md - Claude Code UI Project Guide

🚀 Quick Start Commands

Development

# Start development server (frontend + backend)
npm run dev

# Start backend only
npm run server

# Start frontend only  
npm run client

# Build for production
npm run build

Testing & Quality

# Run tests (if available)
npm test

# Check for linting issues
npm run lint

# Type checking (if TypeScript)
npm run typecheck

Port Configuration

• Backend: http://0.0.0.0:2008
• Frontend: http://localhost:2009
• WebSocket: ws://localhost:2008/ws

🏗️ High-Level Architecture

Technology Stack

• Frontend: React 18 + Vite
• Backend: Express.js with WebSocket server
• Database: SQLite (better-sqlite3)
• Authentication: JWT + bcrypt
• Real-time: WebSockets for live chat

System Design

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   React Client  │◄──►│  Express Server │◄──►│   Claude CLI    │
│                 │    │                 │    │                 │
│  - Chat UI      │    │  - Auth Routes  │    │  - Code Actions │
│  - Project Mgmt │    │  - WebSockets   │    │  - File Ops     │
│  - File Browser │    │  - Git API      │    │  - Tool Calling │
└─────────────────┘    └─────────────────┘    └─────────────────┘
         │                       │                       │
         └───────────────────────┼───────────────────────┘
                                 ▼
                     ┌─────────────────┐
                     │  SQLite DB      │
                     │  - Users        │
                     │  - Sessions     │
                     │  - Projects     │
                     └─────────────────┘

Key Components

Frontend (/src)

• App.jsx - Main application with session protection
• ChatInterface.jsx - Real-time chat with Claude
• components/ - Reusable UI components
• utils/api.js - API client utilities

Backend (/server)

• index.js - Express server with WebSocket setup
• routes/ - API endpoints (auth, git, files)
• middleware/ - Authentication & validation
• database/ - SQLite schema & operations

Authentication System

• Single-user system - Only one account allowed
• JWT tokens - Stateless authentication
• Setup mode - Automatic when no users exist
• Session protection - Prevents interruptions during active chats

🔧 Configuration & Setup

Environment Variables

# Server configuration
PORT=2008
VITE_PORT=2009

# Database
DB_PATH=server/database/auth.db

# Optional: Claude API configuration
ANTHROPIC_API_KEY=your_key_here

Initial Setup

1. Clone and install dependencies:

   npm install
   

2. First run (setup mode):

   npm run dev
   # Navigate to http://localhost:2009
   # Create your admin account
   

3. Database reset (if needed):

   rm server/database/auth.db
   npm run dev  # Triggers setup mode
   

🎯 Core Features

Project Management

• Multi-project support - Switch between different codebases
• Git integration - Status, branches, and file tracking
• Session isolation - Each project maintains separate chat history
• File browser - Navigate and edit project files

Chat Interface

• Real-time messaging - Instant responses via WebSockets
• Tool integration - Claude can execute code operations
• Session protection - Prevents UI updates during active conversations
• Message history - Persistent chat logs per project
• Status indicators - Shows Claude's working state

Security Features

• Tool permissions - Disabled by default for security
• Project sandboxing - Isolated file system access
• Authentication required - No anonymous access
• Session validation - JWT token verification

🐛 Troubleshooting

Common Issues

Port Conflicts

# Kill existing processes
pkill -f "node server/index.js"
pkill -f "npm run dev"

# Start fresh
npm run dev

Database Issues

# Reset database (triggers setup mode)
rm server/database/auth.db
npm run dev

Git Path Errors

• Symptom: Console logs showing "Project path not found"
• Cause: Projects reference non-existent directories
• Fix: Update project paths or remove orphaned projects

React Errors in ChatInterface

• Symptom: JavaScript errors when loading chat sessions
• Cause: Missing project directories or invalid status messages
• Fix: Implement better error boundaries and path validation

Performance Optimization

# Clear node modules and reinstall
rm -rf node_modules package-lock.json
npm install

# Rebuild frontend
npm run build

📁 Project Structure

claudecodeui/
├── src/                    # React frontend
│   ├── components/         # Reusable UI components
│   │   ├── ChatInterface.jsx
│   │   ├── ClaudeStatus.jsx
│   │   └── TodoList.jsx
│   ├── utils/             # Frontend utilities
│   └── App.jsx            # Main application
├── server/                # Express backend
│   ├── routes/            # API endpoints
│   │   ├── auth.js        # Authentication
│   │   ├── git.js         # Git operations
│   │   └── files.js       # File management
│   ├── middleware/        # Auth & validation
│   ├── database/          # SQLite setup
│   └── index.js           # Server entry point
├── public/                # Static assets
├── package.json           # Dependencies & scripts
└── vite.config.js         # Frontend build config

🔄 Development Workflow

Adding New Features

1. Backend API: Add routes in /server/routes/
2. Frontend UI: Create components in /src/components/
3. WebSocket events: Update both client and server handlers
4. Database changes: Modify schema in /server/database/

Git Integration Points

• Project loading: server/routes/git.js:62
• Status polling: Continuous Git status checks
• Branch management: server/routes/git.js:198
• Error handling: validateGitRepository() function

Session Protection System

• Activation: When user sends chat message
• WebSocket events: session-created, claude-complete, session-aborted
• Purpose: Prevents sidebar updates during active conversations
• Implementation: App.jsx + ChatInterface.jsx coordination

🚨 Known Issues & Fixes

Issue: Continuous Git Errors

Problem: Logs show repeated "Project path not found" errors Solution:

// Add to git.js validation
const validateProjectPath = (path) => {
  if (!fs.existsSync(path)) {
    console.warn(`Project path does not exist: ${path}`);
    return false;
  }
  return true;
};

Issue: React Error in ChatInterface Line 1515

Problem: Error when loading existing chat sessions Location: src/components/ChatInterface.jsx:1515 Solution: Add error boundary around claude-status message handling

Issue: WebSocket Connection Drops

Problem: Chat becomes unresponsive Solution: Implement automatic reconnection logic

📚 Integration with Claude Code CLI

This UI acts as a web interface for the Claude Code CLI:

Tool Integration

• File operations - Read, write, edit files
• Git commands - Status, diff, commit, push
• Terminal access - Execute shell commands
• Project navigation - Browse directory structure

API Endpoints

• POST /api/chat/send - Send message to Claude
• GET /api/projects - List available projects
• GET /api/git/status - Get Git repository status
• POST /api/files/read - Read file contents
• POST /api/files/write - Write file contents

WebSocket Events

• message - Chat messages
• claude-status - Working status updates
• session-created - New chat session
• session-complete - Chat finished
• session-aborted - Chat interrupted

🔐 Security Considerations

Authentication

• Single-user system - Only one account supported
• JWT expiration - Tokens have limited lifetime
• Password hashing - bcrypt with salt rounds 12
• Setup protection - Registration only when no users exist

File System Access

• Project sandboxing - Limited to configured directories
• Path validation - Prevent directory traversal attacks
• Tool permissions - Disabled by default
• Git operations - Validated repository paths

Network Security

• CORS configuration - Restricted origins
• WebSocket authentication - JWT token required
• Input validation - Sanitized user inputs
• Error messages - No sensitive information leakage

---

📞 Support & Maintenance

Health Checks

• Database connection - SQLite file integrity
• WebSocket status - Active connections count
• Git operations - Repository accessibility
• File system - Project directory permissions

Monitoring

• Server logs - Console output for debugging
• Error tracking - Catch and log exceptions
• Performance - WebSocket message timing
• Resource usage - Memory and CPU monitoring

Updates

• Dependencies - Regular npm audit and updates
• Security patches - Keep Express and React current
• Claude CLI - Ensure compatibility with latest version
• Database migrations - Handle schema changes

---

Last Updated: 2024-12-28
Version: 1.4.0
Tested with: Claude Code CLI