claude-code-webui

v0.1.56

Published

3 months ago

Web-based interface for the Claude Code CLI with streaming chat interface

Downloads

350

0High
0Medium
0Low

sugyan

claude claude-cli ai web-ui chat anthropic backend nodejs

🌐 Claude Code Web UI

A modern web interface for Claude Code CLI - Transform your command-line coding experience into an intuitive web-based chat interface

🎬 View Demo

📱 Screenshots

| Desktop Interface | Mobile Experience | | -------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | | | | | Chat-based coding interface with instant responses and ready input field | Mobile-optimized chat experience with touch-friendly design |

| Desktop (Light) | Mobile (Light) | | ----------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | | | | Clean light interface for daytime coding sessions | iPhone SE optimized light theme interface |

| Desktop Permission Dialog | Mobile Permission Dialog | | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | | | | Secure tool access with granular permission controls and clear approval workflow | Touch-optimized permission interface for mobile devices |

📑 Table of Contents

✨ Why Claude Code Web UI?

Transform the way you interact with Claude Code

Instead of being limited to command-line interactions, Claude Code Web UI brings you:

| CLI Experience | Web UI Experience | | ----------------------------- | ---------------------------- | | ⌨️ Terminal only | 🌐 Any device with a browser | | 📱 Desktop bound | 📱 Mobile-friendly interface | | 📝 Plain text output | 🎨 Rich formatted responses | | 🗂️ Manual directory switching | 📁 Visual project selection |

🎯 Key Features

📋 Permission Mode Switching - Toggle between normal and plan mode execution
🔄 Real-time streaming responses - Live Claude Code output in chat interface
📁 Project directory selection - Visual project picker for context-aware sessions
💬 Conversation history - Browse and restore previous chat sessions
🛠️ Tool permission management - Granular control over Claude's tool access
🎨 Dark/light theme support - Automatic system preference detection
📱 Mobile-responsive design - Touch-optimized interface for any device

🚀 Quick Start

Get up and running in under 2 minutes:

Option 1: npm Package (Recommended)

# Install globally via npm
npm install -g claude-code-webui

# Start the server
claude-code-webui

# Open browser to http://localhost:8080

Option 2: Binary Release

# Download and run (macOS ARM64 example)
curl -LO https://github.com/sugyan/claude-code-webui/releases/latest/download/claude-code-webui-macos-arm64
chmod +x claude-code-webui-macos-arm64
./claude-code-webui-macos-arm64

# Open browser to http://localhost:8080

Option 3: Development Mode

# Backend (choose one)
cd backend && deno task dev    # Deno runtime
cd backend && npm run dev      # Node.js runtime

# Frontend (new terminal)
cd frontend && npm run dev

# Open browser to http://localhost:3000

Prerequisites

✅ Claude CLI installed and authenticated (Get it here)
✅ Node.js >=20.0.0 (for npm installation) or Deno (for development)
✅ Modern browser (Chrome, Firefox, Safari, Edge)
✅ dotenvx (for development): Install guide

⚙️ CLI Options

The backend server supports the following command-line options:

| Option | Description | Default | | ---------------------- | --------------------------------------------------------- | ----------- | | -p, --port <port> | Port to listen on | 8080 | | --host <host> | Host address to bind to (use 0.0.0.0 for all interfaces) | 127.0.0.1 | | --claude-path <path> | Path to claude executable (overrides automatic detection) | Auto-detect | | -d, --debug | Enable debug mode | false | | -h, --help | Show help message | - | | -v, --version | Show version | - |

Environment Variables

PORT - Same as --port
DEBUG - Same as --debug

Examples

# Default (localhost:8080)
claude-code-webui

# Custom port
claude-code-webui --port 3000

# Bind to all interfaces (accessible from network)
claude-code-webui --host 0.0.0.0 --port 9000

# Enable debug mode
claude-code-webui --debug

# Custom Claude CLI path (for non-standard installations or aliases)
claude-code-webui --claude-path /path/to/claude

# Using environment variables
PORT=9000 DEBUG=true claude-code-webui

🚨 Troubleshooting

Claude CLI Path Detection Issues

If you encounter "Claude Code process exited with code 1" or similar errors, this typically indicates Claude CLI path detection failure.

Quick Solution:

claude-code-webui --claude-path "$(which claude)"

Common scenarios requiring explicit path specification:

Node.js environment managers (Volta, asdf, nvm, etc.)
Custom installation locations
Shell aliases or wrapper scripts

Environment-specific commands:

# For Volta users
claude-code-webui --claude-path "$(volta which claude)"

# For asdf users
claude-code-webui --claude-path "$(asdf which claude)"

Native Binary Installation: Supported. Script path detection may fail and show warnings, but the application will work correctly as long as the Claude executable path is valid.

Debug Mode: Use --debug flag for detailed error information:

claude-code-webui --debug

🔧 Development

Setup

# Clone repository
git clone https://github.com/sugyan/claude-code-webui.git
cd claude-code-webui

# Install dotenvx (see prerequisites)

# Start backend (choose one)
cd backend
deno task dev    # Deno runtime
# OR
npm run dev      # Node.js runtime

# Start frontend (new terminal)
cd frontend
npm run dev

Port Configuration

Create .env file in project root:

echo "PORT=9000" > .env

Run with dotenvx to use the .env file:

# Backend
cd backend
dotenvx run --env-file=../.env -- deno task dev    # Deno
dotenvx run --env-file=../.env -- npm run dev      # Node.js

# Frontend (uses Vite's built-in .env support)
cd frontend
npm run dev

Alternative: Set environment variables directly:

PORT=9000 deno task dev     # Deno
PORT=9000 npm run dev       # Node.js

🔒 Security Considerations

Important: This tool executes Claude CLI locally and provides web access to it.

✅ Safe Usage Patterns

🏠 Local development: Default localhost access
📱 Personal network: LAN access from your own devices

⚠️ Security Notes

No authentication: Currently no built-in auth mechanism
System access: Claude can read/write files in selected projects
Network exposure: Configurable but requires careful consideration

🛡️ Best Practices

# Local only (recommended)
claude-code-webui --port 8080

# Network access (trusted networks only)
claude-code-webui --port 8080 --host 0.0.0.0

Never expose to public internet without proper security measures.

📚 Documentation

For comprehensive technical documentation, see CLAUDE.md which covers:

Architecture overview and design decisions
Detailed development setup instructions
API reference and message types

❓ FAQ

Yes, you need the Claude CLI tool installed and authenticated. The web UI is a frontend for the existing Claude CLI.

Yes! The web interface is fully responsive and works great on mobile devices when connected to your local network.

Yes, everything runs locally. No data is sent to external servers except Claude's normal API calls through the CLI.

While technically possible, it's designed for local use. If deploying remotely, ensure proper authentication and security measures.

Download the latest binary from releases or pull the latest code for development mode.

These errors typically indicate Claude CLI path detection issues. See the Troubleshooting section for detailed solutions including environment manager workarounds and debug steps.

🔗 Related Projects

Alternative Claude Code Web UIs:

siteboon/claudecodeui
- A popular web-based Claude Code interface with mobile and remote management focus
- Offers additional features for project and session management
- Great alternative if you need more advanced remote access capabilities

Both projects aim to make Claude Code more accessible through web interfaces, each with their own strengths and approach.

🤝 Contributing

We welcome contributions! Please see our development setup and feel free to:

🐛 Report bugs
✨ Suggest features
📝 Improve documentation
🔧 Submit pull requests

Fun fact: This project is almost entirely written and committed by Claude Code itself! 🤖
We'd love to see pull requests from your Claude Code sessions too :)

📄 License

MIT License - see LICENSE for details.

Made with ❤️ for the Claude Code community

⭐ Star this repo • 🐛 Report issues • 💬 Discussions