mirror of
https://github.com/siteboon/claudecodeui.git
synced 2025-12-08 17:09:38 +00:00
6dd303a321
* feat: Add token budget tracking and multiple improvements ## Features - **Token Budget Visualization**: Added real-time token usage tracking with pie chart display showing percentage used (blue < 50%, orange < 75%, red ≥ 75%) - **Show Thinking Toggle**: Added quick settings option to show/hide reasoning sections in messages - **Cache Clearing Utility**: Added `/clear-cache.html` page for clearing service workers, caches, and storage ## Improvements - **Package Upgrades**: Migrated from deprecated `xterm` to `@xterm/*` scoped packages - **Testing Setup**: Added Playwright for end-to-end testing - **Build Optimization**: Implemented code splitting for React, CodeMirror, and XTerm vendors to improve initial load time - **Deployment Scripts**: Added `scripts/start.sh` and `scripts/stop.sh` for cleaner server management with automatic port conflict resolution - **Vite Update**: Upgraded Vite from 7.0.5 to 7.1.8 ## Bug Fixes - Fixed static file serving to properly handle routes vs assets - Fixed session state reset to preserve token budget on initial load - Updated default Vite dev server port to 5173 (Vite's standard) ## Technical Details - Token budget is parsed from Claude CLI `modelUsage` field in result messages - Budget updates are sent via WebSocket as `token-budget` events - Calculation includes input, output, cache read, and cache creation tokens - Token budget state persists during active sessions but resets on session switch * feat: Add session processing state persistence Fixes issue where "Thinking..." banner and stop button disappear when switching between sessions. Users can now navigate freely while Claude is processing without losing the ability to monitor or stop the session. Features: - Processing state tracked in processingSessions Set (App.jsx) - Backend session status queries via check-session-status WebSocket message - UI state (banner + stop button) restored when returning to processing sessions - Works after page reload by querying backend's authoritative process maps - Proper cleanup when sessions complete in background Backend Changes: - Added sessionId to claude-complete, cursor-result, session-aborted messages - Exported isClaudeSessionActive, isCursorSessionActive helper functions - Exported getActiveClaudeSessions, getActiveCursorSessions for status queries - Added check-session-status and get-active-sessions WebSocket handlers Frontend Changes: - processingSessions state tracking in App.jsx - onSessionProcessing/onSessionNotProcessing callbacks - Session status check on session load and switch - Completion handlers only update UI if message is for current session - Always clean up processing state regardless of which session is active * feat: Make context window size configurable via environment variables Removes hardcoded 160k token limit and makes it configurable through environment variables. This allows easier adjustment for different Claude models or use cases. Changes: - Added CONTEXT_WINDOW env var for backend (default: 160000) - Added VITE_CONTEXT_WINDOW env var for frontend (default: 160000) - Updated .env.example with documentation - Replaced hardcoded values in token usage calculations - Replaced hardcoded values in pie chart display Why 160k? Claude Code reserves ~40k tokens for auto-compact feature, leaving 160k available for actual usage from the 200k context window. * fix: Decode HTML entities in chat message display HTML entities like < and > were showing as-is instead of being decoded to < and > characters. Added decodeHtmlEntities helper function to properly display angle brackets and other special characters. Applied to: - Regular message content - Streaming content deltas - Session history loading - Both string and array content types * refactor: Align package.json with main branch standards - Revert to main branch's package.json scripts structure - Remove custom scripts/start.sh and scripts/stop.sh - Update xterm dependencies to scoped @xterm packages (required for code compatibility) - Replace xterm with @xterm/xterm - Replace xterm-addon-fit with @xterm/addon-fit 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * feat: Replace CLI implementation with Claude Agents SDK This commit completes the migration to the Claude Agents SDK, removing the legacy CLI-based implementation and making the SDK the exclusive integration method. Changes: - Remove claude-cli.js legacy implementation - Add claude-sdk.js with full SDK integration - Remove CLAUDE_USE_SDK feature flag (SDK is now always used) - Update server/index.js to use SDK functions directly - Add .serena/ to .gitignore for AI assistant cache Benefits: - Better performance (no child process overhead) - Native session management with interrupt support - Cleaner codebase without CLI/SDK branching - Full feature parity with previous CLI implementation - Maintains compatibility with Cursor integration 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * Update server/claude-sdk.js Whoops. This is correct. Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * Update server/index.js Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * Update src/components/ChatInterface.jsx Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * Update src/components/ChatInterface.jsx Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * Update src/components/ChatInterface.jsx Left my test code in, but that's fixed. Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * fix: Prevent stale token-usage data from updating state on session switch - Add AbortController to cancel in-flight token-usage requests when session/project changes - Capture session/project IDs before fetch and verify they match before updating state - Handle AbortError gracefully without logging as error - Prevents race condition where old session data overwrites current session's token budget 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * Update src/components/TokenUsagePie.jsx Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> --------- Co-authored-by: viper151 <simosmik@gmail.com> Co-authored-by: Claude <noreply@anthropic.com> Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
Claude Code UI
A desktop and mobile UI for Claude Code, and Cursor CLI. You can use it locally or remotely to view your active projects and sessions in Claude Code or Cursor and make changes to them from everywhere (mobile or desktop). This gives you a proper interface that works everywhere. Supports models including Claude Sonnet 4, Opus 4.1, and GPT-5
Screenshots
Desktop View
Main interface showing project overview and chat |
Mobile Experience
Responsive mobile design with touch navigation |
CLI Selection
Select between Claude Code and Cursor CLI |
|
Features
- 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 or Cursor
- Integrated Shell Terminal - Direct access to Claude Code or Cursor 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
- TaskMaster AI Integration (Optional) - Advanced project management with AI-powered task planning, PRD parsing, and workflow automation
- Model Compatibility - Works with Claude Sonnet 4, Opus 4.1, and GPT-5
Quick Start
Prerequisites
- Node.js v20 or higher
- Claude Code CLI installed and configured, and/or
- Cursor CLI installed and configured
One-click Operation (Recommended)
No installation required, direct operation:
npx @siteboon/claude-code-ui
Your default browser will automatically open the Claude Code UI interface.
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
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
- MCP support - Add your own MCP servers through the UI
Chat Interface
- Use responsive chat or Claude Code/Cursor 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 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
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 │ │ Claude CLI │
│ (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
- CLI Integration (Claude Code / Cursor) - Process spawning and management
- Session Management - JSONL parsing and conversation persistence
- 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 follow these guidelines:
Getting Started
- 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
Development Process
- 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
What to Contribute
- 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
Troubleshooting
Common Issues & Solutions
"No Claude projects found"
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
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
- 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 community.