A desktop and mobile UI for Claude Code, Anthropic's official CLI for AI-assisted coding. You can use it locally or remotely to view your active projects and sessions in claude code and make changes to them the same way you would do it in claude code CLI. This gives you a proper interface that works everywhere.
Main interface showing project overview and chat |
Responsive mobile design with touch navigation |
- Responsive Design - Works seamlessly across desktop, tablet, and mobile so you can also use Claude Code from mobile
- Interactive Chat Interface - Built-in chat interface for seamless communication with Claude Code
- Integrated Shell Terminal - Direct access to Claude Code CLI through built-in shell functionality
- File Explorer - Interactive file tree with syntax highlighting and live editing
- Git Explorer - View, stage and commit your changes. You can also switch branches
- Session Management - Resume conversations, manage multiple sessions, and track history
- Comprehensive Token Tracking - Detailed breakdown of input, output, cache creation, and cache read tokens
- Smart Number Formatting - Automatic K/M unit conversion for large token counts (e.g., 1.2M, 450K)
- Interactive Charts - Toggle data series visibility with clickable legends, cache data hidden by default
- Subscription Integration - Display Claude Max subscription status and OAuth token expiry from local credentials
- Improved Layout - Wider modal (1400px), optimized heights for summary cards, calendar, and charts
- Billing Tab - Real-time subscription info, token status tracking, and permission scopes display
- Accurate Cost Calculation - Aligned with ccusage tool using exact Anthropic pricing formulas
- Multi-Tab Analytics - Sessions, Models, and Billing tabs with comprehensive usage insights
- Browse Claude Code Agents - View and search through all 60+ available Claude Code subagents
- Smart Filtering - Filter agents by model type (Opus, Sonnet, Haiku) with real-time search
- Detailed Agent Info - Expandable cards showing agent descriptions, categories, and full instructions
- Pagination Support - Efficiently browse large collections with 20 agents per page
- One-Command Deploy - Full Docker support with
docker-compose up - Pre-configured Setup - Automated Claude Code installation and configuration
- Volume Mounting - Seamless access to your local workspace and Claude credentials
- Health Checks - Built-in monitoring and auto-restart capabilities
- VS Code Experience - Full-featured Monaco editor with syntax highlighting
- Multiple Themes - Support for popular VS Code themes
- IntelliSense - Code completion and suggestions
- Integrated File Editing - Edit files directly in the browser with professional IDE features
- Speech-to-Text - Voice input using Web Speech API or OpenAI Whisper
- Multi-language - Support for multiple languages in voice recognition
- Configurable - Choose between browser-based or API-based transcription
- Full Chinese Support - Complete UI translation to Simplified Chinese
- Language Toggle - Easy switching between English and Chinese
- Persistent Settings - Language preference saved across sessions
- Improved Navigation - Better touch controls and gesture support
- Responsive Layouts - Optimized UI for small screens
- Mobile-First Features - Dedicated mobile input components
- Dark/Light Themes - Full theme support with smooth transitions
- Keyboard Navigation - Complete keyboard shortcuts for power users
- Accessibility - WCAG compliant with screen reader support
- Loading States - Better feedback during operations
The fastest way to get started is using Docker:
# Clone the repository
git clone https://github.com/zhuzhe1983/claudecodeui.git
cd claudecodeui
# Copy and configure environment
cp .env.example .env.docker
# Edit .env.docker if needed (default port: 9998)
# Start with Docker Compose
docker-compose up -d
# Access the application
# Open http://localhost:9998 in your browserNote: Make sure your ~/.claude directory contains valid credentials for Claude Code to work properly.
- Node.js v20 or higher
- Claude Code CLI installed and configured
- Clone the repository:
git clone https://github.com/siteboon/claudecodeui.git
cd claudecodeui- Install dependencies:
npm install- Configure environment:
cp .env.example .env
# Edit .env with your preferred settings- Start the application:
# Development mode (with hot reload)
npm run dev
The application will start at the port you specified in your .env
- Open your browser:
- Development:
http://localhost:3001
- Development:
🔒 Important Notice: All Claude Code tools are disabled by default. This prevents potentially harmful operations from running automatically.
To use Claude Code's full functionality, you'll need to manually enable tools:
- Open Tools Settings - Click the gear icon in the sidebar
- Enable Selectively - Turn on only the tools you need
- Apply Settings - Your preferences are saved locally
Tools Settings interface - enable only what you need
Recommended approach: Start with basic tools enabled and add more as needed. You can always adjust these settings later.
The UI automatically discovers Claude Code projects from ~/.claude/projects/ and provides:
- Visual Project Browser - All available projects with metadata and session counts
- Project Actions - Rename, delete, and organize projects
- Smart Navigation - Quick access to recent projects and sessions
- Use responsive chat or Claude Code CLI - You can either use the adapted chat interface or use the shell button to connect to Claude Code CLI.
- Real-time Communication - Stream responses from Claude with WebSocket connection
- Session Management - Resume previous conversations or start fresh sessions
- Message History - Complete conversation history with timestamps and metadata
- Multi-format Support - Text, code blocks, and file references
- Interactive File Tree - Browse project structure with expand/collapse navigation
- Live File Editing - Read, modify, and save files directly in the interface
- Syntax Highlighting - Support for multiple programming languages
- File Operations - Create, rename, delete files and directories
- Session Persistence - All conversations automatically saved
- Session Organization - Group sessions by project and timestamp
- Session Actions - Rename, delete, and export conversation history
- Cross-device Sync - Access sessions from any device
- Responsive Design - Optimized for all screen sizes
- Touch-friendly Interface - Swipe gestures and touch navigation
- Mobile Navigation - Bottom tab bar for easy thumb navigation
- Adaptive Layout - Collapsible sidebar and smart content prioritization
- Add shortcut to Home Screen - Add a shortcut to your home screen and the app will behave like a PWA
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Frontend │ │ Backend │ │ Claude CLI │
│ (React/Vite) │◄──►│ (Express/WS) │◄──►│ Integration │
└─────────────────┘ └─────────────────┘ └─────────────────┘
- Express Server - RESTful API with static file serving
- WebSocket Server - Communication for chats and project refresh
- Claude CLI Integration - Process spawning and management
- Session Management - JSONL parsing and conversation persistence
- File System API - Exposing file browser for projects
- React 18 - Modern component architecture with hooks
- CodeMirror - Advanced code editor with syntax highlighting
We welcome contributions! Please follow these guidelines:
- Fork the repository
- Clone your fork:
git clone <your-fork-url> - Install dependencies:
npm install - Create a feature branch:
git checkout -b feature/amazing-feature
- Make your changes following the existing code style
- Test thoroughly - ensure all features work correctly
- Run quality checks:
npm run lint && npm run format - Commit with descriptive messages following Conventional Commits
- Push to your branch:
git push origin feature/amazing-feature - Submit a Pull Request with:
- Clear description of changes
- Screenshots for UI changes
- Test results if applicable
- Bug fixes - Help us improve stability
- New features - Enhance functionality (discuss in issues first)
- Documentation - Improve guides and API docs
- UI/UX improvements - Better user experience
- Performance optimizations - Make it faster
Problem: The UI shows no projects or empty project list Solutions:
- Ensure Claude CLI is properly installed
- Run
claudecommand in at least one project directory to initialize - Verify
~/.claude/projects/directory exists and has proper permissions d
Problem: Files not loading, permission errors, empty directories Solutions:
- Check project directory permissions (
ls -lain terminal) - Verify the project path exists and is accessible
- Review server console logs for detailed error messages
- Ensure you're not trying to access system directories outside project scope
GNU General Public License v3.0 - see LICENSE file for details.
This project is open source and free to use, modify, and distribute under the GPL v3 license.
- Claude Code - Anthropic's official CLI
- React - User interface library
- Vite - Fast build tool and dev server
- Tailwind CSS - Utility-first CSS framework
- CodeMirror - Advanced code editor
- Star this repository to show support
- Watch for updates and new releases
- Follow the project for announcements
Made with care for the Claude Code community.