siteboon/claudecodeuiPlease refer to the latest official releases for information GitHub Homepage
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
Clone Repository:
git clone https://github.com/siteboon/claudecodeui.git cd claudecodeui
Install Dependencies:
npm install
Configure Environment:
cp .env.example .env # Edit .env file as needed
Start Application:
# Development Mode (with hot reload) npm run dev
Open Browser:
- Development Environment:
http://localhost:3001
- Development Environment:
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:
- Open Tool Settings: Click the gear icon in the sidebar
- Selectively Enable: Only enable the tools you need
- 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