mirror of
https://github.com/siteboon/claudecodeui.git
synced 2026-01-23 18:07:34 +00:00
44c88ec15f
* 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> * feat: Implement slash command menu with fixed positioning and dark mode support - Add CommandMenu component with grouped command display - Implement command routes for listing, loading, and executing commands - Add command parser utility for argument and file processing - Fix menu positioning using fixed positioning relative to viewport - Add dark mode support with proper text contrast - Preserve metadata badge colors in dark mode - Support built-in, project, and user-level commands - Add keyboard navigation and selection 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * Update server/index.js Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * Update server/utils/commandParser.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 server/routes/commands.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 server/index.js Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * Update server/utils/commandParser.js Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * fix: Add responsive width constraints to CommandMenu - Use min() function to cap width at viewport - 32px - Add maxWidth constraint for better mobile support - Update package-lock.json with new dependencies 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * fix: Security and stability improvements for command execution and file operations Security Fixes: - Replace blocking fs.existsSync/readFileSync with async fs.promises.readFile in token usage endpoint - Implement comprehensive command injection protection using shell-quote parser - Validate commands against exact allowlist matches (no dangerous prefix matching) - Detect and block shell operators (&&, ||, |, ;, etc.) and metacharacters - Execute commands with execFile (shell: false) to prevent shell interpretation - Add argument validation to reject dangerous characters Bug Fixes: - Remove premature handleCommandSelect call from selectCommand to prevent double-counting usage - Add block scoping to 'session-aborted' switch case to prevent variable conflicts - Fix case fall-through by properly scoping const declarations with braces Technical Details: - server/index.js: Replace sync file ops with await fsPromises.readFile() - server/utils/commandParser.js: Complete security overhaul with shell-quote integration - src/components/ChatInterface.jsx: Command selection now only inserts text, execution happens on send 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * fix: Wrap orphaned token-usage endpoint code in proper async handler - Fixed syntax error caused by orphaned code at lines 1097-1114 - Added proper app.get endpoint definition for token-usage API - Wrapped code in async (req, res) handler with authentication middleware - Preserves all security features (async file reads, path validation) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * security: Add path traversal protection to file operation endpoints - Constrain file reads to project root directory - Constrain binary file serving to project root - Constrain file writes to project root - Use extractProjectDirectory to get actual project path - Validate resolved paths start with normalized project root - Prevent authenticated users from accessing files outside their projects Fixes path traversal vulnerability in: - GET /api/projects/:projectName/file (read endpoint) - GET /api/projects/:projectName/files/content (binary serve endpoint) - PUT /api/projects/:projectName/file (save endpoint) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * fix: Use WebSocket.OPEN constant instead of instance properties - Import WebSocket from 'ws' library - Change all instances from client.OPEN/ws.OPEN to WebSocket.OPEN - Fixed 4 occurrences: lines 111, 784, 831, 868 - Ensures correct WebSocket state checking using library constant Addresses CodeRabbit security review feedback. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * fix: Improve token usage tracking and fix race conditions - Use cumulative tokens from SDK instead of per-request tokens for accurate session totals - Add configurable context window budget via CONTEXT_WINDOW env var (default 160000) - Fix race condition where stale token usage data could overwrite current session data - Replace polling with one-time fetch on session load + post-message update - Add comprehensive debug logging for token budget flow - Show token percentage on all screen sizes (remove sm:inline hiding) - Add .mcp.json to .gitignore - Add ARCHITECTURE.md and slash-command-tasks.md documentation Technical improvements: - Token budget now fetched after message completion instead of WebSocket - Removed interval polling that could conflict with WebSocket updates - Added session/project validation before updating state - Improved input placeholder to wrap on small screens 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * fix: Improve CommandMenu positioning for mobile devices - Add responsive positioning logic that detects mobile screens (< 640px) - On mobile: Position menu from bottom (80px above input) with full width - On desktop: Use calculated top position with boundary checks - Ensure menu stays within viewport on all screen sizes - Use Math.max/min to prevent menu from going off-screen - Apply consistent positioning to both empty and populated menu states Technical changes: - Add getMenuPosition() function to calculate responsive styles - Mobile: bottom-anchored, full-width with 16px margins - Desktop: top-anchored with viewport boundary constraints - Spread menuPosition styles into both menu render cases 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * fix: Add click-outside detection and improve CommandMenu positioning - Add useEffect hook to detect clicks outside the menu and close it - Fix mobile positioning to use calculated position from textarea instead of hardcoded bottom value - Ensure menu appears just above the input on mobile with proper spacing - Keep full-width layout on mobile screens (< 640px) - Maintain viewport boundary checks on both mobile and desktop Technical changes: - Add mousedown event listener to document when menu is open - Check if click target is outside menuRef and call onClose - Remove hardcoded `bottom: '80px'` in favor of calculated `top` position - Use Math.max to ensure menu stays at least 16px from top edge 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * debug: Add console logging and improve mobile positioning logic - Add console logs to debug positioning and rendering - Improve mobile positioning with better space calculations - Check if there's enough space above textarea before positioning - Position from top of viewport if insufficient space above input - Ensure menu stays within visible viewport boundaries Debugging additions: - Log isOpen, commandsLength, position, and menuPosition - Log mobile positioning calculations 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * fix: Use bottom positioning for CommandMenu on mobile - Change mobile positioning from top-based to bottom-based (90px from bottom) - This ensures menu always appears just above input, regardless of keyboard state - Add maxHeight: '50vh' to prevent menu from taking up too much space - Remove complex position calculations that didn't work well with mobile keyboard - Remove debug console.log statements - Menu now correctly appears above input on all mobile screen sizes Technical changes: - Mobile: Use fixed bottom positioning instead of calculated top - Desktop: Continue using top positioning for consistency - Simplified positioning logic for better maintainability 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * fix: Filter Invalid API key messages from session titles API error messages were appearing as session titles because they come from assistant messages with isApiErrorMessage flag, but the filter only checked user messages. Updated assistant message handling to: - Skip messages with isApiErrorMessage: true flag - Filter messages starting with "Invalid API key" Also improved session title logic to prefer last user message over last assistant message for better context. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * fix: Fix Temporal Dead Zone error by reordering function declarations Reordered function declarations in ChatInterface.jsx to resolve ReferenceError where executeCommand tried to call handleBuiltInCommand and handleCustomCommand before they were initialized. - Moved handleBuiltInCommand before executeCommand (now at line 1441) - Moved handleCustomCommand before executeCommand (now at line 1533) - executeCommand now at line 1564, after its dependencies This fixes the "cannot access uninitialized variable" error that was preventing the chat interface from loading. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * fix: Improve session handling, message routing, and mobile UX Session Handling: - Fix new session message routing by allowing messages through when currentSessionId is null - Improve claude-complete event handling to update UI state for new sessions - Add session loading ref to prevent duplicate scroll triggers during session switches - Add extensive debug logging in claude-sdk.js to track session lifecycle Mobile UX: - Only close sidebar on mobile when switching between different projects - Keep sidebar open when clicking sessions within the same project - Add project context to session objects for better tracking Command Execution: - Auto-submit commands to Claude for processing after selection - Set command content in input and programmatically submit form Scroll Behavior: - Fix scroll behavior during session loading with isLoadingSessionRef - Prevent double-scroll effect when switching sessions - Ensure smooth scroll to bottom after messages fully render Message Filtering: - Update global message types to include 'claude-complete' - Allow messages through for new sessions (when currentSessionId is null) - Improve session-specific message filtering logic Dependencies: - Update @esbuild/darwin-arm64 to direct dependency 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * fix: Improve session handling, message routing, and mobile UX - Remove stale Playwright debug files (.playwright-mcp/) - Clean up slash-command-fix-progress.md tracking file - Improve session switching stability in ClaudeStatus component - Fix message routing to ensure responses go to correct session - Enhance mobile UX for CommandMenu with better positioning - Stabilize sidebar session management - Fix Temporal Dead Zone errors in ChatInterface 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * fix: Filter sessions containing Task Master subtask JSON from session list - Change filtering from startsWith to includes for {"subtasks": pattern - Apply filtering in parseJsonlSessions (line 781) for JSONL parsing - Apply filtering in getSessions (line 630) before returning to API - Fix inconsistent filter logic - use OR pattern for both user and assistant messages - Add filtering for "CRITICAL: You MUST respond with ONLY a JSON" messages - Prevents Task Master JSON responses from appearing as session titles in sidebar 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * fix: Filter JSON response sessions from session list - Change session filtering to use general pattern `startsWith('{ "')` - Catches all Task Master JSON responses (subtasks, complexity analysis, tasks) - Apply filter in both parseJsonlSessions() and getSessions() functions - Prevents JSON responses from appearing as session titles in UI 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * Update websocket.js * Update projects.js * Update CommandMenu.jsx --------- 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.