Login

A desktop and mobile visual interface for Claude Code, supporting cross-platform AI programming assistant management.

GPL-3.0JavaScript 1.7ksiteboonclaudecodeui Last Updated: 2025-07-15

Claude Code UI Project Details

Project Overview

Claude Code UI is an open-source, web and mobile-friendly user interface designed for Anthropic's official Claude Code CLI. This project allows users to view and manage all Claude Code sessions and projects locally or remotely, in the same manner as the CLI. This provides users with a complete interface that works anywhere.

Project Features

🎨 Responsive Design

  • Cross-platform Compatibility: Seamless support for desktop, tablet, and mobile devices
  • Adaptive Layout: Collapsible sidebar and intelligent content prioritization
  • Touch-friendly: Swipe gestures and touch navigation
  • Mobile Navigation: Bottom tab bar for convenient thumb access

💬 Interactive Chat Interface

  • Built-in Chat: Integrated chat interface for seamless communication with Claude Code
  • Real-time Communication: Stream Claude's responses via WebSocket connection
  • Session Management: Resume previous conversations or start new sessions
  • Message History: Complete conversation history with timestamps and metadata
  • Multi-format Support: Text, code blocks, and file references

🖥️ Integrated Terminal Functionality

  • Direct CLI Access: Direct access to Claude Code CLI via built-in shell functionality
  • Process Management: Process generation and management integrated with Claude CLI
  • Command Execution: Supports all Claude Code CLI commands

📁 File Explorer

  • Interactive File Tree: Interactive file tree with syntax highlighting and real-time editing
  • Real-time File Editing: Read, modify, and save files directly within the interface
  • Syntax Highlighting: Supports multiple programming languages
  • File Operations: Create, rename, delete files and directories

💾 Session Persistence

  • Auto-save: All conversations are automatically saved
  • Session Organization: Sessions grouped by project and timestamp
  • Session Operations: Rename, delete, and export conversation history
  • Cross-device Sync: Access sessions from any device

Technical Architecture

System Architecture Diagram

┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Frontend │ │ Backend │ │ Claude CLI │
│ (React/Vite) │◄──►│ (Express/WS) │◄──►│ Integration │
└─────────────────┘ └─────────────────┘ └─────────────────┘

Backend Tech Stack

  • Express Server: Provides RESTful API and static file serving
  • WebSocket Server: Used for chat and project refresh communication
  • Claude CLI Integration: Process generation and management
  • Session Management: JSONL parsing and conversation persistence
  • File System API: Provides file browser for projects

Frontend Tech Stack

  • React 18: Modern component architecture using Hooks
  • CodeMirror: Advanced code editor with syntax highlighting
  • Vite: Fast build tool and development server
  • Tailwind CSS: Utility-first CSS framework

Installation & Configuration

System Requirements

  • Node.js v16 or higher
  • Claude Code CLI installed and configured

Installation Steps

  1. Clone Repository:

    git clone https://github.com/siteboon/claudecodeui.git
    cd claudecodeui
    
  2. Install Dependencies:

    npm install
    
  3. Configure Environment:

    cp .env.example .env
    # Edit .env file as needed
    
  4. Start Application:

    # Development Mode (with hot reload)
    npm run dev
    
  5. Open Browser:

    • Development Environment: http://localhost:3001

Security Settings

🔒 Important Security Notice

All Claude Code tools are disabled by default. This prevents potentially harmful operations from running automatically.

To use the full functionality of Claude Code, you need to manually enable tools:

  1. Open Tool Settings: Click the gear icon in the sidebar
  2. Selectively Enable: Only enable the tools you need
  3. Apply Settings: Your preferences will be saved locally

Recommended Approach: Start by enabling essential tools and gradually add more functionality as needed.

Key Features

Project Management

  • Automatic Project Discovery: UI automatically discovers Claude Code projects from ~/.claude/projects/
  • Visual Project Browser: Displays all available projects with their metadata and session count
  • Project Operations: Rename, delete, and organize projects
  • Smart Navigation: Quick access to recent projects and sessions

File Management

  • Project Structure Browsing: With expand/collapse navigation
  • Real-time Editing: Modify files directly within the interface
  • File Operations: Full file and directory management capabilities

Session Management

  • Persistent Storage: All sessions are automatically saved
  • History Tracking: Complete conversation history tracking
  • Multi-session Support: Manage multiple project sessions simultaneously

Troubleshooting

Common Issue 1: UI shows no projects or an empty project list

Solution:

  • Ensure Claude CLI is correctly installed
  • Run the claude command in at least one project directory to initialize it
  • Verify the ~/.claude/projects/ directory exists and has appropriate permissions

Common Issue 2: Files not loading, permission errors, or empty directories

Solution:

  • Check project directory permissions (using ls -la in the terminal)
  • Verify the project path exists and is accessible
  • Check server console logs for detailed error messages
  • Ensure you are not attempting to access system directories outside the project scope

Star History Chart