claudecodeui/openspec/project.md

Project Context

Purpose

Claude Code UI (aka Cloud CLI) is a full-stack web application that provides a responsive desktop and mobile interface for Claude Code CLI, Cursor CLI, and OpenAI Codex. It enables users to interact with their AI programming assistants from any device through a browser, providing a seamless cross-device experience for AI-powered development workflows.

Key Goals:

• Provide universal access to AI CLI tools from any device (desktop, tablet, mobile)
• Enable real-time chat and terminal interactions with AI assistants
• Offer integrated file browsing, code editing, and Git operations
• Support session management and conversation resumption
• Maintain security through authentication and tool permission systems

Tech Stack

Frontend

• React 18 - Functional components with hooks
• Vite 7 - Fast build tool with hot module replacement
• React Router v6 - Client-side routing
• Tailwind CSS 3 - Utility-first styling with custom components
• CodeMirror 6 - Code editing with syntax highlighting (JavaScript, Python, JSON, Markdown, CSS, HTML)
• Xterm.js 5 - Terminal emulation with WebGL rendering
• React Markdown - Markdown rendering with KaTeX math support
• Lucide React - Icon library

Backend

• Node.js (v20+) - ES modules (type: "module")
• Express.js 4 - REST API server
• WebSocket (ws 8) - Real-time bidirectional communication
• SQLite (better-sqlite3 12) - Embedded database for users, sessions, settings
• JWT (jsonwebtoken 9) - Authentication tokens
• bcrypt 6 - Password hashing
• node-pty 1 - Pseudo-terminal for shell sessions

AI SDKs

• @anthropic-ai/claude-agent-sdk 0.1.x - Direct Claude integration
• @openai/codex-sdk 0.75.x - OpenAI Codex integration
• child process spawning - Cursor CLI integration

DevOps

• concurrently - Run frontend and backend in parallel
• Vite - Build system with manual chunk splitting
• auto-changelog - Automated CHANGELOG generation
• release-it - Release automation

Database

• SQLite with three main tables:
  • users - Authentication and user settings
  • api_keys - External API key management
  • user_credentials - Stored service credentials (GitHub, GitLab, etc.)

Project Conventions

Code Style

JavaScript/React (Frontend)

• ES Modules - All imports use .js or .jsx extensions explicitly
• Functional Components - React components are functional with hooks (no class components)
• File Naming:
  • Components: PascalCase (e.g., ChatInterface.jsx, Settings.jsx)
  • Utilities: camelCase (e.g., api.js, websocket.js)
  • Hooks: camelCase with use prefix (e.g., useAudioRecorder.js, useLocalStorage.jsx)
• Imports: Organized in groups (React, third-party, relative imports)
• JSX: Single quotes for attributes, double quotes for strings
• Component Organization:
  • Hooks at top level
  • Event handlers after hooks
  • Render helpers at bottom
  • Main render return at end

JavaScript (Backend)

• ES Modules - All files use .js extension with import/export
• Async/Await - Preferred over callbacks for async operations
• Error Handling - Try-catch blocks for file I/O, process spawning, database operations
• Comments: JSDoc-style for modules and key functions
• Constants: UPPER_SNAKE_CASE (e.g., TOOL_APPROVAL_TIMEOUT_MS, CONTEXT_WINDOW)

Code Comments

• Block comments (/* */) for file headers and complex logic explanations
• Line comments (//) for inline explanations
• TODO/FIXME markers for pending work
• Session Protection comments use multi-line header format for critical integration points

Architecture Patterns

Frontend Architecture

• Component Hierarchy: App.jsx → Context Providers → Page Components → UI Components
• Context-based State Management:
  • AuthContext - User authentication state
  • WebSocketContext - WebSocket connection management
  • ThemeContext - Dark/light mode
  • TaskMasterContext - Task management state
  • TasksSettingsContext - Task settings persistence
• Custom Hooks for reusable logic (e.g., useAudioRecorder, useLocalStorage)
• Protected Routes - ProtectedRoute component wraps authenticated pages
• Error Boundaries - ErrorBoundary wraps main app for graceful failure

Backend Architecture

• Express Middleware Chain:
  1. CORS (cross-origin requests)
  2. JSON body parser
  3. JWT authentication (middleware/auth.js)
  4. Route handlers
• Modular Routes - Each feature has its own router in routes/ directory
• Session Management:
  • In-memory activeSessions Maps per provider (Claude, Cursor, Codex)
  • PTY sessions cached in ptySessionsMap with 30-minute timeout
  • Session resumption via sessionId parameter
• WebSocket Handlers:
  • /ws - Chat and AI assistant communication
  • /shell - Terminal/shell access with PTY spawning
• Error Handling:
  • Path validation prevents directory traversal
  • Try-catch wrapping for process spawning
  • WebSocket errors logged but don't crash server

Communication Patterns

• REST API - Standard HTTP methods for CRUD operations
• WebSocket Message Flow:
  1. Client sends command with options (projectPath, sessionId, etc.)
  2. Server invokes SDK/CLI integration
  3. Responses streamed via writer.send() with message type markers
  4. UI renders based on message type (content, tool_use, error, etc.)
• Message Types: claude-command, cursor-command, codex-command, abort-session, claude-permission-response

Testing Strategy

Current Status: No formal test suite exists. Manual testing focuses on:

• Multi-provider session management (Claude, Cursor, Codex)
• WebSocket connection reliability
• File operations security
• Terminal session persistence
• Cross-device responsiveness

Testing Guidelines (for future tests):

• Test WebSocket reconnection scenarios
• Verify file system path validation (directory traversal prevention)
• Test tool permission approval flows
• Validate session resumption across providers
• Test concurrent sessions and PTY cleanup
• Verify database migrations and schema changes

Git Workflow

Branching Strategy

• main - Production-ready code, always deployable
• feature/* - New features (e.g., feat/show-grant-permission-button)
• fix/* - Bug fixes (e.g., fix/server-crash-when-opening-settings)
• Merge commits - Pull requests merged with merge commits (not rebase)

Commit Message Conventions

Based on recent commit history:

• feat: - New features (e.g., "feat: add Bash command approval handling")
• fix: - Bug fixes (e.g., "fix: normalize file path handling")
• Merge pull request #XXX - PR merges (automated)
• Merge branch - Branch merges (automated)

Commit Message Format:

type: brief description

Optional detailed explanation with multiple lines.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Release Process

1. Update version in package.json
2. Run npm run release (triggers release-it)
3. Auto-generated CHANGELOG via auto-changelog
4. Tag and push to GitHub repository

Domain Context

AI CLI Tools Integration

Claude Code

• Session Location: ~/.claude/projects/[encoded-path]/
• Models: Claude Sonnet 4.5, Opus 4.5 (see shared/modelConstants.js)
• Tool Permissions: All tools disabled by default for security
• Approval Timeout: 55 seconds (configurable via CLAUDE_TOOL_APPROVAL_TIMEOUT_MS)
• SDK Integration: Direct SDK usage (no child processes) for better performance

Cursor CLI

• Session Location: ~/.cursor/projects/
• Integration: Child process spawning (cursor-agent command)
• Resume Support: --resume parameter for session continuation

OpenAI Codex

• Session Location: ~/.codex/sessions/ (JSONL format)
• Token Usage: Tracked and displayed in UI
• Integration: @openai/codex-sdk with session file parsing

Project Discovery

Projects auto-discovered from provider-specific directories using:

• extractProjectDirectory() - Resolves encoded project paths
• getFileTree() - Generates file tree structure for browsing
• chokidar - File watcher for live updates

File System Security

All file operations validate paths are within project root:

const normalizedRoot = path.resolve(projectRoot) + path.sep;
if (!resolved.startsWith(normalizedRoot)) {
    return res.status(403).json({ error: 'Path must be under project root' });
}

Session Protection System

Prevents sidebar project updates from interrupting active chat sessions:

• User sends message → Session marked as active
• Claude completes → Session marked as inactive
• Session aborted → Session marked as inactive
• App.jsx pauses sidebar updates when session is active

Important Constraints

Technical Constraints

• Node.js Version: Minimum v20 required (ES modules, crypto.randomUUID())
• Single User System: Database designed for single-user instance (not multi-tenant)
• In-Memory State: Active sessions and tool approvals don't persist across restarts
• No Native Notifications: Uses in-app UI for all alerts
• Tool Approval Timeout: Must be < 60s (SDK control timeout limit)

Security Constraints

• Path Traversal Protection: All file paths validated against project root
• Tool Permissions: Opt-in model (all tools disabled by default)
• Authentication: JWT-based with bcrypt password hashing
• API Key Management: Stored in database with user association
• WebSocket Security: Same-origin policy, no CORS on WebSocket routes

Performance Constraints

• Context Window: Default 160,000 tokens (configurable via CONTEXT_WINDOW)
• Chunk Size: Vite build warns at 1000KB chunks
• PTY Session Cache: 30-minute timeout to prevent memory leaks
• Database: SQLite (not suitable for high-concurrency multi-user scenarios)

Business Constraints

• Provider Dependency: Requires external CLI tools to be installed separately
• Single Instance Design: Not designed for hosted multi-tenant deployments
• No Native Mobile Apps: Web-only (can be wrapped in PWA, but not native)
• Open Source MIT License: Free to use, modify, and distribute

External Dependencies

Required CLI Tools (User-Installed)

• Claude Code CLI - npm install -g @anthropic-ai/claude-code
• Cursor CLI - Installed via Cursor IDE
• OpenAI Codex CLI - npm install -g @openai/codex

NPM Dependencies

Runtime (production):

• Web framework: express, react, react-dom, react-router-dom
• Real-time: ws, @xterm/xterm, node-pty
• Database: better-sqlite3, sqlite3
• Auth: jsonwebtoken, bcrypt
• AI SDKs: @anthropic-ai/claude-agent-sdk, @openai/codex-sdk
• UI: @uiw/react-codemirror, lucide-react, tailwindcss
• Utilities: chokidar, fuse.js, gray-matter, katex

Development:

• Build: vite, @vitejs/plugin-react, concurrently
• Release: release-it, auto-changelog
• Image processing: sharp

External Services

• GitHub API - Via @octokit/rest for Git operations
• OpenAI API - Optional Whisper transcription (requires OPENAI_API_KEY)
• MCP Servers - User-configurable Model Context Protocol servers

Environment Variables

PORT=3001                              # Backend server port
VITE_PORT=5173                         # Frontend dev server port
CONTEXT_WINDOW=160000                  # Claude context size
CLAUDE_TOOL_APPROVAL_TIMEOUT_MS=55000  # Tool approval timeout
OPENAI_API_KEY=                        # Whisper transcription key
VITE_IS_PLATFORM=false                 # Platform mode flag

Repository Information

• Homepage: https://claudecodeui.siteboon.ai
• Repository: https://github.com/siteboon/claudecodeui
• Issues: https://github.com/siteboon/claudecodeui/issues
• Package: @siteboon/claude-code-ui on npm