https://github.com/sugyan/claude-code-webui
Web-based interface for Claude CLI with streaming chat responses
https://github.com/sugyan/claude-code-webui
claude claude-cli web-ui
Last synced: 26 days ago
JSON representation
Web-based interface for Claude CLI with streaming chat responses
- Host: GitHub
- URL: https://github.com/sugyan/claude-code-webui
- Owner: sugyan
- License: mit
- Created: 2025-06-10T03:06:25.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2025-09-06T14:56:13.000Z (30 days ago)
- Last Synced: 2025-09-06T16:25:27.783Z (30 days ago)
- Topics: claude, claude-cli, web-ui
- Language: TypeScript
- Size: 2.75 MB
- Stars: 551
- Watchers: 5
- Forks: 119
- Open Issues: 15
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
- awesome-claude-code - claude-code-webui - code-webui) | 支持流式聊天响应的 Claude CLI Web 界面 | 流式 Web 界面| (GUI 和 Web 界面)
- awesome-claude - claude-code-webui - 489⭐ - Web-based interface with streaming (Claude Code Ecosystem / User Interfaces & Web Apps)
- awesome - sugyan/claude-code-webui - Web-based interface for Claude CLI with streaming chat responses (TypeScript)
- awesome-claude-code - **claude-code-webui** - based interface for Claude CLI with streaming chat responses. (GUIs & Web UIs)
README
# 🌐 Claude Code Web UI
[](https://www.npmjs.com/package/claude-code-webui)
[](https://www.npmjs.com/package/claude-code-webui)
[](https://github.com/sugyan/claude-code-webui/blob/main/LICENSE)
[](https://github.com/sugyan/claude-code-webui/actions/workflows/ci.yml)
[](https://github.com/sugyan/claude-code-webui/releases)
> **A modern web interface for Claude Code CLI** - Transform your command-line coding experience into an intuitive web-based chat interface
[🎬 **View Demo**](https://github.com/user-attachments/assets/33e769b0-b17e-470b-8163-c71ef186b5af)
## 📱 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?](#-why-claude-code-web-ui)
- [🚀 Quick Start](#-quick-start)
- [⚙️ CLI Options](#-cli-options)
- [🚨 Troubleshooting](#-troubleshooting)
- [🔧 Development](#-development)
- [🔒 Security Considerations](#-security-considerations)
- [📚 Documentation](#-documentation)
- [❓ FAQ](#-faq)
- [🤝 Contributing](#-contributing)
- [📄 License](#-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)
```bash
# 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
```bash
# 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
```bash
# 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](https://github.com/anthropics/claude-code))
- ✅ **Node.js >=20.0.0** (for npm installation) or **Deno** (for development)
- ✅ **Modern browser** (Chrome, Firefox, Safari, Edge)
- ✅ **dotenvx** (for development): [Install guide](https://dotenvx.com/docs/install)
---
## ⚙️ CLI Options
The backend server supports the following command-line options:
| Option | Description | Default |
| ---------------------- | --------------------------------------------------------- | ----------- |
| `-p, --port ` | Port to listen on | 8080 |
| `--host ` | Host address to bind to (use 0.0.0.0 for all interfaces) | 127.0.0.1 |
| `--claude-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
```bash
# 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:**
```bash
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:**
```bash
# 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:
```bash
claude-code-webui --debug
```
---
## 🔧 Development
### Setup
```bash
# 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:
```bash
echo "PORT=9000" > .env
```
Run with dotenvx to use the `.env` file:
```bash
# 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:
```bash
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
```bash
# 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](./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](#-troubleshooting) section for detailed solutions including environment manager workarounds and debug steps.
---
## 🔗 Related Projects
**Alternative Claude Code Web UIs:**
- **[siteboon/claudecodeui](https://github.com/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](#-development) 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](LICENSE) for details.
---
**Made with ❤️ for the Claude Code community**
[⭐ Star this repo](https://github.com/sugyan/claude-code-webui) • [🐛 Report issues](https://github.com/sugyan/claude-code-webui/issues) • [💬 Discussions](https://github.com/sugyan/claude-code-webui/discussions)