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

📱 Screenshots

📑 Table of Contents

• ✨ Why Claude Code Web UI?
• 🚀 Quick Start
• ⚙️ CLI Options
• 🚨 Troubleshooting
• 🔧 Development
• 🔒 Security Considerations
• 📚 Documentation
• ❓ FAQ
• 🤝 Contributing
• 📄 License

✨ 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:

🎯 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:

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:

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

🔗 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.