🌐 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

codeGeneration-dark-2025-08-23T04-11-01.webm

📱 Screenshots

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

---

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

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

Q: Do I need Claude API access?

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

Q: Can I use this on mobile?

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

Q: Is my code safe?

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

Q: Can I deploy this to a server?

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

Q: How do I update?

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

Q: What if Claude CLI isn't found or I get "process exited with code 1"?

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