🌐 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-06-23T14-47-36.webm

---

📑 Table of Contents

• ✨ Why Claude Code Web UI?
• 🚀 Quick Start
• ⚙️ CLI Options
• 🔧 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

---

🚀 Quick Start

Get up and running in under 2 minutes:

Option 1: Binary Release (Recommended)

# 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 2: 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)
• ✅ 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
-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

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

---

🔧 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

Both backend and frontend will automatically use this port:

• Backend: Uses dotenvx to read the .env file
• Frontend: Uses Vite's built-in .env support

---

🔒 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?

Ensure Claude CLI is installed and available in your PATH. Run claude --version to verify.

---

🤝 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