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

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

💡 Light Theme Screenshots

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

🔧 Advanced Features

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

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

Transform the way you interact with Claude Code

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

• 📋 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

Get up and running in under 2 minutes:

# Install globally via npm npm install -g claude-code-webui # Start the server claude-code-webui # Open browser to http://localhost:8080

# 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

# 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

• ✅ 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

The backend server supports the following command-line options:

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

# 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

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

# 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

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

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

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

• 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

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

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

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

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.

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

MIT License - see LICENSE for details.