🌐 Claude Code Web UI

[!WARNING] This project is no longer actively maintained. Issues and pull requests are unlikely to receive responses. The repository has been archived and is kept available for reference. Feel free to fork it if you'd like to continue development.

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

🎬 View Demo

📱 Screenshots

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

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

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.

---