mirror of
https://github.com/siteboon/claudecodeui.git
synced 2026-02-23 17:17:41 +00:00
597e9c54b7
* fix: intercept slash commands in handleSubmit to pass arguments correctly When a user types a slash command with arguments (e.g. `/feature implement dark mode`) and presses Enter, the command was not being intercepted as a slash command. Instead, the raw text was sent as a regular message to the Claude API, which responded with "Unknown skill: feature". Root cause: the command autocomplete menu (useSlashCommands) detects commands via the regex `/(^|\s)\/(\S*)$/` which only matches when the cursor is right after the command name with no spaces. As soon as the user types a space to add arguments, the pattern stops matching, the menu closes, and pressing Enter falls through to handleSubmit which sends the text as a plain message — completely bypassing command execution. This fix adds a slash command interceptor at the top of handleSubmit: - Checks if the trimmed input starts with `/` - Extracts the command name (text before the first space) - Looks up the command in the loaded slashCommands list - If found, delegates to executeCommand() which properly extracts arguments via regex and sends them to the backend /api/commands/execute endpoint - The backend then replaces $ARGUMENTS, $1, $2 etc. in the command template Changes: - Added `slashCommands` to the destructured return of useSlashCommands hook - Added slash command interception logic in handleSubmit before message dispatch - Added `executeCommand` and `slashCommands` to handleSubmit dependency array Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * fix: address review — pass rawInput param and cleanup UI state - Pass trimmedInput to executeCommand to avoid stale closure reads - Add UI cleanup (images, command menu, textarea) before early return - Update executeCommand signature to accept optional rawInput parameter Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Cloud CLI (aka Claude Code UI)
A desktop and mobile UI for Claude Code, Cursor CLI and Codex. You can use it locally or remotely to view your active projects and sessions in Claude Code, Cursor, or Codex and make changes to them from everywhere (mobile or desktop). This gives you a proper interface that works everywhere.
Screenshots
Desktop View
Main interface showing project overview and chat |
Mobile Experience
Responsive mobile design with touch navigation |
CLI Selection
Select between Claude Code, Cursor CLI and Codex |
|
Features
- Responsive Design - Works seamlessly across desktop, tablet, and mobile so you can also use Claude Code, Cursor, or Codex from mobile
- Interactive Chat Interface - Built-in chat interface for seamless communication with Claude Code, Cursor, or Codex
- Integrated Shell Terminal - Direct access to Claude Code, Cursor CLI, or Codex 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
- TaskMaster AI Integration (Optional) - Advanced project management with AI-powered task planning, PRD parsing, and workflow automation
- Model Compatibility - Works with Claude Sonnet 4.5, Opus 4.5, and GPT-5.2
Quick Start
Prerequisites
- Node.js v22 or higher
- Claude Code CLI installed and configured, and/or
- Cursor CLI installed and configured, and/or
- Codex installed and configured
One-click Operation (Recommended)
No installation required, direct operation:
npx @siteboon/claude-code-ui
The server will start and be accessible at http://localhost:3001 (or your configured PORT).
To restart: Simply run the same npx command again after stopping the server
Global Installation (For Regular Use)
For frequent use, install globally once:
npm install -g @siteboon/claude-code-ui
Then start with a simple command:
claude-code-ui
To restart: Stop with Ctrl+C and run claude-code-ui again.
To update:
cloudcli update
CLI Usage
After global installation, you have access to both claude-code-ui and cloudcli commands:
| Command / Option | Short | Description |
|---|---|---|
cloudcli or claude-code-ui |
Start the server (default) | |
cloudcli start |
Start the server explicitly | |
cloudcli status |
Show configuration and data locations | |
cloudcli update |
Update to the latest version | |
cloudcli help |
Show help information | |
cloudcli version |
Show version information | |
--port <port> |
-p |
Set server port (default: 3001) |
--database-path <path> |
Set custom database location |
Examples:
cloudcli # Start with defaults
cloudcli -p 8080 # Start on custom port
cloudcli status # Show current configuration
Run as Background Service (Recommended for Production)
For production use, run Claude Code UI as a background service using PM2 (Process Manager 2):
Install PM2
npm install -g pm2
Start as Background Service
# Start the server in background
pm2 start claude-code-ui --name "claude-code-ui"
# Or using the shorter alias
pm2 start cloudcli --name "claude-code-ui"
# Start on a custom port
pm2 start cloudcli --name "claude-code-ui" -- --port 8080
Auto-Start on System Boot
To make Claude Code UI start automatically when your system boots:
# Generate startup script for your platform
pm2 startup
# Save current process list
pm2 save
Local Development Installation
- 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:
Security & Tools Configuration
🔒 Important Notice: All Claude Code tools are disabled by default. This prevents potentially harmful operations from running automatically.
Enabling Tools
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.
TaskMaster AI Integration (Optional)
Claude Code UI supports TaskMaster AI (aka claude-task-master) integration for advanced project management and AI-powered task planning.
It provides
- AI-powered task generation from PRDs (Product Requirements Documents)
- Smart task breakdown and dependency management
- Visual task boards and progress tracking
Setup & Documentation: Visit the TaskMaster AI GitHub repository for installation instructions, configuration guides, and usage examples. After installing it you should be able to enable it from the Settings
Usage Guide
Core Features
Project Management
It automatically discovers Claude Code, Cursor or Codex sessions when available and groups them together into projects session counts
- Project Actions - Rename, delete, and organize projects
- Smart Navigation - Quick access to recent projects and sessions
- MCP support - Add your own MCP servers through the UI
Chat Interface
- Use responsive chat or Claude Code/Cursor CLI/Codex CLI - You can either use the adapted chat interface or use the shell button to connect to your selected CLI.
- Real-time Communication - Stream responses from your selected CLI (Claude Code/Cursor/Codex) 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
File Explorer & Editor
- 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
Git Explorer
TaskMaster AI Integration (Optional)
- Visual Task Board - Kanban-style interface for managing development tasks
- PRD Parser - Create Product Requirements Documents and parse them into structured tasks
- Progress Tracking - Real-time status updates and completion tracking
Session Management
- 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
Mobile App
- 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
Architecture
System Overview
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Frontend │ │ Backend │ │ Agent │
│ (React/Vite) │◄──►│ (Express/WS) │◄──►│ Integration │
│ │ │ │ │ │
└─────────────────┘ └─────────────────┘ └─────────────────┘
Backend (Node.js + Express)
- Express Server - RESTful API with static file serving
- WebSocket Server - Communication for chats and project refresh
- Agent Integration (Claude Code / Cursor CLI / Codex) - Process spawning and management
- File System API - Exposing file browser for projects
Frontend (React + Vite)
- React 18 - Modern component architecture with hooks
- CodeMirror - Advanced code editor with syntax highlighting
Contributing
We welcome contributions! Please see our Contributing Guide for details on commit conventions, development workflow, and release process.
Troubleshooting
Common Issues & Solutions
"No Claude projects found"
Problem: The UI shows no projects or empty project list Solutions:
- Ensure Claude Code is properly installed
- Run
claudecommand in at least one project directory to initialize - Verify
~/.claude/projects/directory exists and has proper permissions
File Explorer Issues
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
License
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.
Acknowledgments
Built With
- Claude Code - Anthropic's official CLI
- Cursor CLI - Cursor's official CLI
- Codex - OpenAI Codex
- React - User interface library
- Vite - Fast build tool and dev server
- Tailwind CSS - Utility-first CSS framework
- CodeMirror - Advanced code editor
- TaskMaster AI (Optional) - AI-powered project management and task planning
Support & Community
Stay Updated
- Star this repository to show support
- Watch for updates and new releases
- Follow the project for announcements
Sponsors
Made with care for the Claude Code, Cursor and Codex community.