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)
  • Workers: Manage CLI Worker processes and the Daemon process
  • Logs: Dedicated log viewer with support for multiple log types and keyword search
  • Remote Control: Connect WeChat and WeCom channels
  • Monitoring: System resource metrics and per-Worker process-level memory/uptime metrics
  • Tasks: Browse task templates and create scheduled tasks
  • Plugins: Manage plugin installations and plugin marketplace
  • 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 documentation for details.

Authentication ​

The Web UI supports two authentication modes:

ModeSettingDescription
No Auth (default)CODEBUDDY_GATEWAY_AUTH=noneNo password required
PasswordCODEBUDDY_GATEWAY_AUTH=passwordPassword 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 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 ​

ShortcutAction
EnterSend message
Shift+EnterNew line in input
EscapeStop 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