Claude Web UI Docker Development

Expert guidance for the ClaudeWebUI-Docker repository - a containerized web interface for Claude Code with real-time chat, file management, terminal access, and git integration.

Project Overview

This is a full-stack web application that provides a browser-based interface for Claude Code, featuring:

Development Commands

When the user requests development tasks, use these patterns:

Starting Development Environment

```bash

Full development mode (concurrent server + client)

npm run dev

Individual services

npm run server # Backend only (Express + WebSocket)

npm run client # Frontend only (Vite dev server)

```

Production Tasks

```bash

Build for production

npm run build

Build and serve

npm run start

Preview production build

npm run preview

```

Initial Setup

```bash

Environment setup

cp .env.example .env

Edit .env for port configuration (default: API=3008, Frontend=3009)

Install dependencies

npm install

Verify Node.js version (requires v20+)

node --version

```

Architecture Knowledge

Frontend Structure (React + Vite)

- `ChatInterface.jsx` - Claude Code interaction with streaming WebSocket

- `FileTree.jsx` - Interactive file explorer with live editing

- `Shell.jsx` - Terminal interface using XTerm.js and node-pty

- `GitPanel.jsx` - Git operations and diff viewing

- `MainContent.jsx` - Tabbed content area coordinator

Backend Structure (Node.js + Express)

- `claude-cli.js` - Claude Code CLI integration and process management

- `projects.js` - Project discovery and session management

- `database/db.js` - SQLite authentication and user management

- `/ws` - Chat interface communication

- `/shell` - Terminal interface for direct CLI access

Session Protection System

The application implements sophisticated session protection:

State Management Patterns

When working with state, follow these patterns:

File System Integration

When implementing file operations:

Security Considerations

**CRITICAL SECURITY RULES:**

1. **Claude Code Tools**: Disabled by default for security - must be manually enabled through UI

2. **Authentication**: JWT-based with SQLite storage, bcrypt password hashing

3. **File Access**: Scope limited to discovered Claude projects with permission checking

4. **WebSocket Auth**: Query parameter-based authentication required

Configuration Files

Build System Files

Key Dependencies

**Frontend:**

**Backend:**

**Authentication:**

Claude Code CLI Integration

When working with Claude CLI integration:

WebSocket Communication

When implementing WebSocket features:

Common Issues & Troubleshooting

When debugging issues, check:

1. **Project Discovery**: Ensure Claude CLI is initialized in at least one project

2. **File Permissions**: Verify project directory access and permissions

3. **WebSocket Connection**: Check port configuration and firewall settings

4. **Tool Access**: Remember tools are disabled by default for security

Production Deployment

When deploying to production:

1. Vite builds frontend to `/dist` directory

2. Express serves static files and API endpoints

3. SQLite database initialization on first run

4. WebSocket server setup with authentication

5. Configure ports via environment variables

6. Set up CORS for cross-origin requests

Mobile & PWA Support

The application includes:

Development Environment Requirements

Instructions for Claude Code

When working on this project:

1. **Always check architecture** before making changes to understand component relationships

2. **Follow security patterns** - especially tool access and authentication

3. **Use provided scripts** rather than inventing new commands

4. **Respect session protection** - coordinate WebSocket updates carefully

5. **Test WebSocket changes** thoroughly as they affect real-time communication

6. **Preserve mobile compatibility** when updating UI components

7. **Maintain backward compatibility** with existing session files and database schema