A desktop and mobile UI for Claude Code, enhanced with macOS native app integration. This fork adds Dock support, menu bar status, and seamless mobile access.
- 🖥️ Dock App - Launch directly from your Dock with ClaudeUI.app
- 📊 Menu Bar Status - Real-time status monitoring with SwiftBar
- 📱 Mobile Ready - Automatic IP detection for iPhone/iPad access
- 🔄 Process Management - PM2 integration for reliability
- ⏰ Activity Logging - Track all starts/stops with timestamps
Main interface showing project overview and chat |
Responsive mobile design with touch navigation |
- Responsive Design - Works seamlessly across desktop, tablet, and 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
- Session Management - Resume conversations, manage multiple sessions, and track history
- macOS with Homebrew installed
- Node.js v24.3.0 or higher
- Claude Code CLI installed and configured
- PM2 (
npm install -g pm2)
- Clone the repository:
git clone https://github.com/starworld/claudecodeui-macos.git
cd claudecodeui-macos- Install dependencies:
npm install- Configure environment:
cp .env.example .env
# Edit .env with your preferred settings- Create macOS App (see IMPLEMENTATION_GUIDE.yaml for details):
# Quick setup - check implementation guide for full instructions
cat IMPLEMENTATION_GUIDE.yaml- Start the application:
# Using the start script
./scripts/start-claude-ui.sh
# Or directly with PM2
pm2 start ecosystem.config.js- Access the application:
- Local:
http://localhost:3009 - Mobile: Check console output for IP address
- Local:
- Install SwiftBar for menu bar:
brew install swiftbar
# When prompted, select: ~/Library/Application Support/SwiftBar/Plugins-
Create Dock App:
- Run commands from
IMPLEMENTATION_GUIDE.yamlPhase 1 - Drag
/Applications/ClaudeUI.appto your Dock
- Run commands from
-
Menu Bar Features:
- 🟢 CI = Running
- ⚪ CI = Stopped
- Click for quick actions
🔒 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
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ 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