# Claude Web UI

A desktop and mobile UI for [Claude Code](https://docs.anthropic.com/en/docs/claude-code), [Cursor CLI](https://docs.cursor.com/en/cli/overview), [Codex](https://developers.openai.com/codex), [Gemini-CLI](https://geminicli.com/), and [Free Claude Code](https://github.com/Alishahryar1/free-claude-code). Use it locally or remotely to view your active projects and sessions from everywhere.

*A fork of [Claude Code UI](https://github.com/siteboon/claudecodeui) with built-in support for Free Claude Code (FCC) integration.*

[CloudCLI Cloud](https://cloudcli.ai) · [Bug Reports](https://github.com/HeliosAiden/claude-web-ui/issues) · [Contributing](CONTRIBUTING.md)

*English · [Русский](./README.ru.md) · [Deutsch](./README.de.md) · [한국어](./README.ko.md) · [中文](./README.zh-CN.md) · [日本語](./README.ja.md) · [Türkçe](./README.tr.md)*

## Features

- **Responsive Design** - Works seamlessly across desktop, tablet, and mobile so you can also use Agents from mobile 
- **Interactive Chat Interface** - Built-in chat interface for seamless communication with the Agents
- **Integrated Shell Terminal** - Direct access to the Agents CLI through built-in shell functionality
- **File Explorer** - Interactive file tree with syntax highlighting and live editing
- **Git Explorer** - View, stage and commit your changes. You can also switch branches 
- **Session Management** - Resume conversations, manage multiple sessions, and track history
- **Plugin System** - Extend Claude Web UI with custom plugins — add new tabs, backend services, and integrations. [Build your own →](https://github.com/cloudcli-ai/cloudcli-plugin-starter)
- **Activity Bar Navigation** — VSCode-style vertical activity bar for switching between Explorer, Bookmarks, Search, Git, and Settings views
- **Session Tabs** — Tmux-like horizontal tab bar for open chat/shell sessions with provider logos, status dots, and close buttons
- **Chat Find (Ctrl+F)** — Search text across all messages in the current conversation with match navigation and highlighting
- **Free Claude Code (FCC) Integration** - Built-in support for Free Claude Code. Auto-discovers FCC configuration, falls back to the `fcc-claude` CLI, and uses FCC auth tokens — no manual setup needed
- **Prompt Templates** - Create, edit, and insert reusable prompt templates from Settings. Save any message as a template with one click. Searchable template picker in the chat composer
- **Thinking Modes** - Toggle between normal, think-hard, and think-harder modes (Claude provider) directly from the chat composer toolbar
- **Settings Dashboard** - Manage credentials, prompt templates, plugins, themes, language, and provider configurations from a central Settings page
- **Model Compatibility** - Works with Claude, GPT, and Gemini model families (see [`shared/modelConstants.js`](shared/modelConstants.js) for the full list of supported models)


## Free Claude Code (FCC) Integration

This fork includes built-in support for [Free Claude Code](https://github.com/Alishahryar1/free-claude-code), allowing you to use Claude Code without an Anthropic subscription. FCC acts as a local proxy between the Claude SDK and alternative API providers.

### How It Works

When you launch Claude Web UI, it detects your FCC setup from multiple sources, checked in priority order:

1. **Shell environment** — `export ANTHROPIC_BASE_URL=http://127.0.0.1:8082`
2. **CLI flags** — `--anthropic-base-url http://127.0.0.1:8082 --anthropic-auth-token mytoken`
3. **Project `.env`** — place a `.env` file in your working directory
4. **Global config** — `~/.config/claude-web-ui/.env` (set once, applies everywhere)
5. **FCC auto-discovery** — `~/.config/free-claude-code/.env` loaded automatically, with conflicting variables (PORT, HOST, etc.) safely skipped

Once configured, the integration works through several layers:

- **API routing** — when `ANTHROPIC_BASE_URL` points to a local FCC proxy, API calls are routed through FCC instead of directly to `api.anthropic.com`
- **CLI path fallback** — if the standard `claude` CLI is not found, the server falls back to the `fcc-claude` command automatically
- **Auth token detection** — FCC auth tokens are recognized and show as "Free Claude Code" in the authentication status
- **Clean separation** — FCC config is read-only; this fork never modifies your FCC environment

### Setup

1. Install and configure [Free Claude Code](https://github.com/Alishahryar1/free-claude-code) on your machine
2. Configure Claude Web UI to use your FCC proxy — choose one of these methods:

   **CLI flags** (one-off):
   ```
   npx @heliosaiden/claude-web-ui --anthropic-base-url http://127.0.0.1:8082
   ```

   **Project `.env` file** (per-project):
   ```
   echo "ANTHROPIC_BASE_URL=http://127.0.0.1:8082" > .env
   npx @heliosaiden/claude-web-ui
   ```

   **Global config** (set once, works everywhere):
   ```
   mkdir -p ~/.config/claude-web-ui
   echo "ANTHROPIC_BASE_URL=http://127.0.0.1:8082" >> ~/.config/claude-web-ui/.env
   ```

   **FCC auto-discovery** (zero config):
   If your FCC `.env` is at `~/.config/free-claude-code/.env`, Claude Web UI discovers it automatically.

3. Start the server — your FCC setup is detected and used for API routing
4. Check the authentication status in the UI to confirm "Free Claude Code" is detected

Run `claude-web-ui status` to see your current configuration, or `claude-web-ui help` for all CLI options.


## Quick Start

### Self-Hosted (Open source)

#### npm

Try Claude Web UI instantly with **npx** (requires **Node.js** v22+):

```
npx @heliosaiden/claude-web-ui
```

To use with a local [Free Claude Code](https://github.com/Alishahryar1/free-claude-code) proxy:

```
npx @heliosaiden/claude-web-ui --anthropic-base-url http://127.0.0.1:8082
```

Or install **globally** for regular use:

```
npm install -g @heliosaiden/claude-web-ui
claude-web-ui
```

Open `http://localhost:3001` — all your existing sessions are discovered automatically.

#### Clone (for FCC support)

To run this fork with Free Claude Code support:

```bash
git clone https://github.com/HeliosAiden/claude-web-ui.git
cd claude-web-ui
npm install
npm run dev
```

Open `http://localhost:3001`. Your FCC configuration will be auto-discovered from `~/.config/free-claude-code/.env`.

#### Docker Sandboxes (Experimental)

Run agents in isolated sandboxes with hypervisor-level isolation. Starts Claude Code by default. Requires the [`sbx` CLI](https://docs.docker.com/ai/sandboxes/get-started/).

```
npx @heliosaiden/claude-web-ui@latest sandbox ~/my-project
```

Supports Claude Code, Codex, and Gemini CLI. See the [sandbox docs](docker/) for setup and advanced options.


---

## Which option is right for you?

Claude Web UI is a fork of the open source UI layer that powers CloudCLI Cloud, with built-in Free Claude Code integration. You can self-host it on your own machine, run it in a Docker sandbox for isolation, or use CloudCLI Cloud for a fully managed environment.

| | Self-Hosted (npm) | Self-Hosted (Docker Sandbox) *(Experimental)* | CloudCLI Cloud |
|---|---|---|---|
| **Best for** | Local agent sessions on your own machine | Isolated agents with web/mobile IDE | Teams who want agents in the cloud |
| **How you access it** | Browser via `[yourip]:port` | Browser via `localhost:port` | Browser, any IDE, REST API, n8n |
| **Setup** | `npx @heliosaiden/claude-web-ui` | `npx @heliosaiden/claude-web-ui@latest sandbox ~/project` | No setup required |
| **Isolation** | Runs on your host | Hypervisor-level sandbox (microVM) | Full cloud isolation |
| **Machine needs to stay on** | Yes | Yes | No |
| **Mobile access** | Any browser on your network | Any browser on your network | Any device, native app coming |
| **Agents supported** | Claude Code, Cursor CLI, Codex, Gemini CLI, Free Claude Code | Claude Code, Codex, Gemini CLI | Claude Code, Cursor CLI, Codex, Gemini CLI |
| **File explorer and Git** | Yes | Yes | Yes |
| **MCP configuration** | Synced with `~/.claude` | Managed via UI | Managed via UI |
| **REST API** | Yes | Yes | Yes |
| **Team sharing** | No | No | Yes |
| **Platform cost** | Free, open source | Free, open source | Starts at $7/month |

> All options use your own AI subscriptions (Claude, Cursor, etc.) — CloudCLI provides the environment, not the AI.

---

## Security & Tools Configuration

**🔒 Important Notice**: All Claude Code tools are **disabled by default**. This prevents potentially harmful operations from running automatically.

### Enabling Tools

To use Claude Code's full functionality, you'll need to manually enable tools:

1. **Open Tools Settings** - Click the gear icon in the sidebar
2. **Enable Selectively** - Turn on only the tools you need
3. **Apply Settings** - Your preferences are saved locally

![Tools Settings Modal](public/screenshots/tools-modal.png)
*Tools Settings interface - enable only what you need*

**Recommended approach**: Start with basic tools enabled and add more as needed. You can always adjust these settings later.

---

## Plugins

Claude Web UI has a plugin system that lets you add custom tabs with their own frontend UI and optional Node.js backend. Install plugins from git repos directly in **Settings > Plugins**, or build your own.

### Available Plugins

| Plugin | Description |
|---|---|
| **[Project Stats](https://github.com/cloudcli-ai/cloudcli-plugin-starter)** | Shows file counts, lines of code, file-type breakdown, largest files, and recently modified files for your current project |
| **[Web Terminal](https://github.com/cloudcli-ai/cloudcli-plugin-terminal)** | Full xterm.js terminal with multi-tab support|
| **[CloudCLI Scheduler](https://github.com/grostim/cloudcli-cron)** | Create workspace-scoped scheduled prompts and execute them through a local CLI such as Codex, Claude Code, or Gemini CLI|
### Build Your Own

**[Plugin Starter Template →](https://github.com/cloudcli-ai/cloudcli-plugin-starter)** — fork this repo to create your own plugin. It includes a working example with frontend rendering, live context updates, and RPC communication to a backend server.

**[Plugin Documentation →](https://cloudcli.ai/docs/plugin-overview)** — full guide to the plugin API, manifest format, security model, and more.

---
## FAQ

<details>
<summary>How is this different from Claude Code Remote Control?</summary>

Claude Code Remote Control lets you send messages to a session already running in your local terminal. Your machine has to stay on, your terminal has to stay open, and sessions time out after roughly 10 minutes without a network connection.

Claude Web UI and CloudCLI Cloud extend Claude Code rather than sit alongside it — your MCP servers, permissions, settings, and sessions are the exact same ones Claude Code uses natively. Nothing is duplicated or managed separately.

Here's what that means in practice:

- **All your sessions, not just one** — Claude Web UI auto-discovers every session from your `~/.claude` folder. Remote Control only exposes the single active session to make it available in the Claude mobile app.
- **Your settings are your settings** — MCP servers, tool permissions, and project config you change in Claude Web UI are written directly to your Claude Code config and take effect immediately, and vice versa.
- **Works with more agents** — Claude Code, Cursor CLI, Codex, Gemini CLI, and Free Claude Code, not just Claude Code.
- **Full UI, not just a chat window** — file explorer, Git integration, MCP management, and a shell terminal are all built in.
- **CloudCLI Cloud runs in the cloud** — close your laptop, the agent keeps running. No terminal to babysit, no machine to keep awake.

</details>

<details>
<summary>Do I need to pay for an AI subscription separately?</summary>

Claude Web UI provides the environment, not the AI. You can bring your own Claude, Cursor, Codex, or Gemini subscription. CloudCLI Cloud starts at $7/month for the hosted environment on top of that.

Alternatively, this fork includes built-in support for [Free Claude Code](https://github.com/Alishahryar1/free-claude-code), which lets you use Claude Code without an Anthropic subscription by routing through alternative API providers. See the [Free Claude Code (FCC) Integration](#free-claude-code-fcc-integration) section above.

</details>

<details>
<summary>What is Free Claude Code (FCC) and how does this fork support it?</summary>

[Free Claude Code](https://github.com/Alishahryar1/free-claude-code) is an open-source project that lets you run Claude Code without an Anthropic subscription by routing API calls through alternative providers. This fork includes built-in integration:

- **Auto-discovery** — FCC environment variables are loaded automatically from `~/.config/free-claude-code/.env`
- **CLI fallback** — Falls back to the `fcc-claude` binary if `claude` is not found
- **Auth recognition** — FCC auth tokens are detected and displayed as "Free Claude Code" in the UI
- **Zero config** — No manual `.env` changes or extra setup required

See the [Free Claude Code Integration](#free-claude-code-fcc-integration) section for details.

</details>

<details>
<summary>Can I use Claude Web UI on my phone?</summary>

Yes. For self-hosted, run the server on your machine and open `[yourip]:port` in any browser on your network. For CloudCLI Cloud, open it from any device — no VPN, no port forwarding, no setup. A native app is also in the works.

</details>

<details>
<summary>Will changes I make in the UI affect my local Claude Code setup?</summary>

Yes, for self-hosted. Claude Web UI reads from and writes to the same `~/.claude` config that Claude Code uses natively. MCP servers you add via the UI show up in Claude Code immediately and vice versa.

</details>

---

## Community & Support

- **[Documentation](https://cloudcli.ai/docs)** — installation, configuration, features, and troubleshooting
- **[Discord](https://discord.gg/buxwujPNRE)** — get help and connect with other users
- **[GitHub Issues](https://github.com/HeliosAiden/claude-web-ui/issues)** — bug reports and feature requests
- **[Upstream Project](https://github.com/siteboon/claudecodeui)** — original CloudCLI project this fork is based on
- **[Contributing Guide](CONTRIBUTING.md)** — how to contribute to the project

## License

GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later) — see [LICENSE](LICENSE) for the full text, including additional terms under Section 7.

This project is open source and free to use, modify, and distribute under the AGPL-3.0-or-later license. If you modify this software and run it as a network service, you must make your modified source code available to users of that service.

Claude Web UI — a fork of [CloudCLI](https://cloudcli.ai) with Free Claude Code integration.

## Acknowledgments

### Built With
- **[Claude Code](https://docs.anthropic.com/en/docs/claude-code)** - Anthropic's official CLI
- **[Cursor CLI](https://docs.cursor.com/en/cli/overview)** - Cursor's official CLI
- **[Codex](https://developers.openai.com/codex)** - OpenAI Codex
- **[Gemini-CLI](https://geminicli.com/)** - Google Gemini CLI
- **[Free Claude Code](https://github.com/Alishahryar1/free-claude-code)** - Open-source Claude Code without Anthropic subscription
- **[React](https://react.dev/)** - User interface library
- **[Vite](https://vitejs.dev/)** - Fast build tool and dev server
- **[Tailwind CSS](https://tailwindcss.com/)** - Utility-first CSS framework
- **[CodeMirror](https://codemirror.net/)** - Advanced code editor


### Sponsors
- [Siteboon - AI powered website builder](https://siteboon.ai)
---

**Made with care for the Claude Code, Cursor, Codex, and Free Claude Code community.**
