🌐 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

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

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

$3

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

$3

``bash


Install globally via npm

npm install -g claude-code-webui

Start the server

claude-code-webui

Open browser to http://localhost:8080

`

$3

`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

`

$3

`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

`

$3

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

$3

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

$3

`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

$3

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

$3

`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
`

$3

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.

$3

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

$3

- 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

$3

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

---