# Web UI

CodeBuddy Code provides a built-in Web UI that offers a full-featured browser interface for interacting with the Agent. When you start CodeBuddy Code in serve mode or enable Remote Control, the Web UI is automatically available.

## Overview

The Web UI provides the same core capabilities as the terminal interface, with a visual layout optimized for browsers:

- **Chat**: Send messages, view conversations, and monitor tool execution in real time
- **Terminal**: Embedded terminal with split-pane support (up to 4 panels)
- **Instances**: Manage and switch between multiple CodeBuddy Code instances
- **Remote Control**: Connect WeChat and WeCom channels
- **Tasks**: Browse and create scheduled tasks from templates
- **Plugins**: Manage plugin installations and marketplaces
- **Settings**: Configure theme, language, model, and permission mode
- **Documentation**: Browse CLI documentation with full-text search
- **API Reference**: View the interactive Swagger UI for HTTP API exploration

## Accessing the Web UI

### Method 1: Serve Mode

Start CodeBuddy Code with the `--serve` flag:

```bash
codebuddy --serve --port 7890
```

Then open in your browser:

```
http://127.0.0.1:7890
```

### Method 2: Remote Control

In an existing CodeBuddy Code session, start the Gateway:

```
/gateway
```

The terminal displays a QR code and URL. Scan the QR code with your phone or open the URL in any browser. See the [Remote Control](remote-control.md) documentation for details.

## Authentication

The Web UI supports two authentication modes:

| Mode | Setting | Description |
|:-----|:--------|:-----------|
| No Auth (default) | `CODEBUDDY_GATEWAY_AUTH=none` | No password required |
| Password | `CODEBUDDY_GATEWAY_AUTH=password` | Password shown in terminal on startup |

Authentication methods (any one is sufficient):

- **URL parameter**: `?password=xxx` — auto-login via URL
- **Login page**: Enter the password displayed in the terminal
- **Bearer token**: `Authorization: Bearer <password>` for API access

Configure in `~/.codebuddy/settings.json`:

```json
{
  "gateway.auth": "none"
}
```

## Features

### Chat View

The default view for conversing with the Agent. Key features:

- **Rich message rendering**: Markdown, syntax-highlighted code blocks, tables, and images
- **Tool execution display**: See tool calls, their parameters, and results inline
- **Permission management**: Approve or deny tool permissions directly in the browser
- **Question panels**: Answer multi-choice questions from the Agent
- **Task progress**: Monitor background tasks and team progress in real time
- **Session management**: Create new chats, browse history, and switch sessions

### Terminal View

An embedded terminal powered by xterm.js:

- **Split panes**: Split horizontally or vertically, up to 4 panels
- **Independent sessions**: Each panel has its own PTY session
- **Persistent connections**: Terminal sessions survive page refreshes
- **Resize support**: Panels auto-resize when the window changes

### Documentation View

Browse the CLI documentation directly in the Web UI:

- **Full-text search**: Search across all documents with MiniSearch
- **Multi-language**: Automatically follows the UI language setting (Chinese/English)
- **Table of contents**: Auto-generated from document headings, with scroll spy
- **Internal navigation**: Document links navigate within the viewer (SPA)
- **API Reference**: Quick link to the interactive Swagger UI at `/api/docs`

### Instance Manager

Manage multiple CodeBuddy Code instances:

- **Instance list**: View all running instances with their working directories and status
- **Quick switch**: Switch between instances with a single click
- **Manual add**: Add remote instances by URL
- **Tunnel support**: Access instances through Cloudflare Tunnel

### Settings

- **Theme**: Light, Dark, or System (auto-detect)
- **Language**: Chinese, English, or System (auto-detect)
- **Model**: Select the AI model from available options
- **Permission mode**: Choose between Default, Accept Edits, Bypass Permissions, or Plan mode

## API Reference

When the HTTP server is running, an interactive API explorer is available at:

```
http://127.0.0.1:{PORT}/api/docs
```

This provides a Swagger UI where you can:

- Browse all available REST API endpoints
- View request/response schemas
- Try out API calls directly from the browser
- Download the OpenAPI 3.1 specification at `/api/openapi.json`

See the [HTTP API Documentation](http-api.md) for the complete API reference.

## Mobile Support

The Web UI is fully responsive and works on mobile devices:

- **Sidebar**: Collapses to a slide-out drawer on small screens
- **PWA support**: Add to home screen for a native app-like experience
- **Touch-friendly**: All interactions optimized for touch input
- **QR code access**: Scan from the terminal to open on your phone instantly

## Keyboard Shortcuts

| Shortcut | Action |
|:---------|:-------|
| `Enter` | Send message |
| `Shift+Enter` | New line in input |
| `Escape` | Stop running agent |

## Technical Details

- **Framework**: React 18 with Zustand for state management
- **Communication**: ACP protocol over HTTP/SSE (not WebSocket)
- **Styling**: Tailwind CSS with CSS variable theming
- **Terminal**: xterm.js with fit addon
- **Search**: MiniSearch for client-side full-text search
- **Markdown**: react-markdown with remark-gfm and syntax highlighting

## Related

- [Remote Control](remote-control.md) — Start the Web UI via Gateway and Tunnel
- [HTTP API](http-api.md) — Complete REST API documentation
- [ACP Protocol](acp.md) — Agent Client Protocol for IDE integration
- [Settings](settings.md) — Configuration options
