Claude Code Web Interface

A web-based interface for Claude Code CLI that can be accessed from any browser. This package allows you to run Claude Code in a terminal-like environment through your web browser, with real-time streaming and full interactivity.

Requirements

- Node.js >= 16
- Claude/Code CLI installed and available on PATH
- Modern browser with WebSocket support

⚠️ Authentication is now Required by Default

Breaking Change: Starting with v2.0.0, authentication is enabled by default for security. When you start the server, it will automatically generate a random token that you'll need to access the interface.

Quick Start: Just run the command and copy the displayed token:
``bash
npx claude-code-web


Look for: "Generated random authentication token: Xr9kM2nQ7w"


`

Migration: If you need the old behavior (no authentication), use --disable-auth:
`bash
npx claude-code-web --disable-auth
`

Features

- 🌐 Web-based terminal - Access Claude Code from any browser
- 🚀 Real-time streaming - Live output with WebSocket communication
- 🎨 Terminal emulation - Full ANSI color support and terminal features
- 🔐 Authentication - Secure by default with automatic token generation
- 📱 Responsive design - Works on desktop and mobile
- ⚡ NPX support - Run anywhere with npx claude-code-web
- 🎛️ Customizable - Adjustable font size, themes, and settings
- 🔄 Multi-Session Support - Create and manage multiple persistent Claude sessions
- 🌍 Multi-Browser Access - Connect to the same session from different browsers/devices
- 💾 Session Persistence - Sessions remain active even when disconnecting
- 📜 Output Buffering - Reconnect and see previous output from your session
- 🔀 VS Code-Style Split View - Drag tabs to create side-by-side terminals for different sessions

Installation

$3


`bash
npm install -g claude-code-web
`

$3

`bash
npx claude-code-web
`

$3

`bash
git clone
cd claude-code-web
npm install
npm run dev # starts with debug logging
`

Usage

$3

`bash

Start with default settings (port 32352, max20 plan, auto-generated auth token)

npx claude-code-web

Specify a subscription plan

npx claude-code-web --plan pro # 19k tokens, $18 limit
npx claude-code-web --plan max5 # 88k tokens, $35 limit
npx claude-code-web --plan max20 # 220k tokens, $140 limit (default)

Specify a custom port

npx claude-code-web --port 8080

Don't automatically open browser

npx claude-code-web --no-open
`

$3

`bash

Default: Auto-generates a random 10-character token (RECOMMENDED)

npx claude-code-web

Output will show: "Generated random authentication token: Xr9kM2nQ7w"

Use a custom authentication token

npx claude-code-web --auth your-secret-token

Disable authentication entirely (NOT recommended for production)

npx claude-code-web --disable-auth

Access with token in URL: http://localhost:32352/?token=your-token

`

$3

`bash

Enable HTTPS (requires SSL certificate files)

npx claude-code-web --https --cert /path/to/cert.pem --key /path/to/key.pem
`

$3

`bash

Enable additional logging and debugging

npx claude-code-web --dev

$3

You can customize how the assistants are labeled in the UI (for example, to display "Alice" instead of "Claude" or "R2" instead of "Codex").

- Flags:
- --claude-alias : Set the display name for Claude (default: env CLAUDE_ALIAS or "Claude").
- --codex-alias : Set the display name for Codex (default: env CODEX_ALIAS or "Codex").

Examples:

`
npx claude-code-web --claude-alias Alice --codex-alias R2
`

Or via environment variables:

`
export CLAUDE_ALIAS=Alice
export CODEX_ALIAS=R2
npx claude-code-web
`

These aliases are for display purposes only; they do not change which underlying CLI is launched.
`

$3


`bash

Start the server with defaults

npm start # equivalent to: node bin/cc-web.js

Start in dev mode with verbose logs

npm run dev # equivalent to: node bin/cc-web.js --dev

Run on a custom port

node bin/cc-web.js --port 8080

Provide an auth token

node bin/cc-web.js --auth YOUR_TOKEN
`

Multi-Session Features

$3

- Session Dropdown: Click "Sessions" in the header to view all active sessions
- New Session: Create named sessions with custom working directories
- Join Session: Connect to any existing session from any browser
- Leave Session: Disconnect without stopping the Claude process
- Delete Session: Stop Claude and remove the session

$3

- Sessions remain active even after all browsers disconnect
- Reconnect from any device using the same server
- Output history preserved (last 1000 lines)
- Multiple users can connect to the same session simultaneously

$3

- Remote Work: Start a session at work, continue from home
- Collaboration: Share a session with team members
- Device Switching: Move between desktop and mobile seamlessly
- Recovery: Never lose work due to connection issues

Command Line Options

| Option | Description | Default |
|--------|-------------|---------|
| -p, --port | Server port | 32352 |
| --no-open | Don't automatically open browser | false |
| --auth | Custom authentication token | auto-generated |
| --disable-auth | Disable authentication (not recommended) | false |
| --https | Enable HTTPS | false |
| --cert | SSL certificate file path | none |
| --key | SSL private key file path | none |
| --dev | Development mode with extra logging | false |
| --plan | Subscription plan (pro, max5, max20) | max20 |

How It Works

1. Claude Code Bridge - Spawns and manages Claude Code processes using node-pty
2. WebSocket Communication - Real-time bidirectional communication between browser and CLI
3. Terminal Emulation - Uses xterm.js for full terminal experience with ANSI colors
4. Process Management - Handles multiple sessions, process lifecycle, and cleanup
5. Session Persistence - Automatically saves and restores sessions across server restarts
6. Folder Mode - Browse and select working directories through the web interface
7. Security - Optional authentication and rate limiting for production use

API Endpoints

$3


- GET / - Web interface
- GET /api/health - Server health status
- GET /api/config - Get server configuration
- GET /api/sessions/list - List all active Claude sessions
- GET /api/sessions/persistence - Get session persistence info
- POST /api/sessions/create - Create a new session
- GET /api/sessions/:sessionId - Get session details
- DELETE /api/sessions/:sessionId - Delete a session
- GET /api/folders - List available folders (folder mode)
- POST /api/folders/select - Select working directory
- POST /api/set-working-dir - Set working directory
- POST /api/create-folder - Create new folder
- POST /api/close-session - Close a session

$3

- create_session - Create a new Claude session
- join_session - Join an existing session
- leave_session - Leave current session
- start_claude - Start Claude Code in current session
- input - Send input to Claude Code
- resize - Resize terminal
- stop - Stop Claude Code session
- ping/pong - Heartbeat

Security Considerations

$3

Claude Code Web now requires authentication by default for security:

Default Behavior: Automatically generates a secure 10-character random token
`bash
npx claude-code-web


Output: "Generated random authentication token: Xr9kM2nQ7w"


`

Custom Token: Specify your own token
`bash
npx claude-code-web --auth my-secure-token-123
`

Disable Authentication: Only for development (not recommended)
`bash
npx claude-code-web --disable-auth
`

Clients must provide the token either:
- In the Authorization header: Bearer your-token
- As a query parameter: ?token=your-token
- Through the web login prompt when accessing the interface

$3

Built-in rate limiting prevents abuse:
- 100 requests per minute per IP by default
- Configurable limits for production environments

$3

For production use, combine HTTPS with authentication:
`bash

Recommended: Auto-generated token with HTTPS

npx claude-code-web --https --cert cert.pem --key key.pem

Alternative: Custom token with HTTPS

npx claude-code-web --https --cert cert.pem --key key.pem --auth $(openssl rand -hex 32)
`

$3

- Default Authentication: Automatic token generation prevents unauthorized access
- Secure Token Display: Generated tokens are highlighted in the console for easy copying
- Session Security: Each session requires proper authentication
- WebSocket Protection: Authentication extends to WebSocket connections
- Warning System: Clear warnings when authentication is disabled

Development

$3

Use the commands above under "Local Development (from source)" and "Running from source". Ensure the Claude CLI is installed and on your PATH.

$3

`
claude-code-web/
├── bin/cc-web.js # CLI entry point
├── src/
│ ├── server.js # Express server + WebSocket
│ ├── claude-bridge.js # Claude Code process management
│ ├── utils/
│ │ ├── auth.js # Authentication utilities
│ │ └── session-store.js # Session persistence
│ └── public/ # Web interface files
│ ├── index.html # Main HTML
│ ├── app.js # Frontend JavaScript
│ ├── auth.js # Client-side authentication
│ ├── session-manager.js # Session management UI
│ ├── plan-detector.js # Plan mode detection
│ └── style.css # Styling
└── package.json
`

Testing

- Framework: Mocha with Node's assert
- Location: tests under test/*.test.js
- Run tests: npm test
- Guidelines: write fast, isolated unit tests; avoid network and real CLI calls—mock process spawns where possible.

Browser Compatibility

- Chrome/Chromium 90+
- Firefox 88+
- Safari 14+
- Edge 90+

Troubleshooting

$3


Ensure Claude Code is installed and accessible:
`bash
which claude

or

claude --version
`

$3

- Check firewall settings for the specified port
- Verify Claude Code is properly installed
- Try running with --dev` flag for detailed logs

$3

- Ensure the process has permission to spawn child processes
- Check file system permissions for the working directory

License

MIT — see the LICENSE file.

Contributing

Contributions welcome! See CONTRIBUTING for guidelines on development, testing, and pull requests.

Support

For issues and feature requests, please use the GitHub issue tracker.