CLI
IDECLIWorkBuddy

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
  • Editor: Supports up to 4 groups, with files draggable between groups and terminals dockable in the editor area
  • 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, permission mode, and the main agent (Standard / PTC / Minimal / Create)
  • 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
# Stamp process defaults on new chats (does not write settings.json):
codebuddy --serve --agent ptc --permission-mode bypassPermissions

Then open in your browser:

http://127.0.0.1:7890

For Standard mode, pass --agent cli explicitly. Do not rely on lastUsed or the default chip. Do not combine minimal with --permission-mode plan.

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.

Serve startup: agent and permission ​

These flags are process defaults and do not write settings. --agent overrides the chip lastUsed and leftover shipped standing keys (cli / ptc / minimal / create) on a continued session. It does not steal a custom @agent.

bash
codebuddy --serve --agent <mode> --permission-mode <permission>

Typical local debug line (--auth none is for localhost / CI only — do not expose this on the public internet):

bash
codebuddy --serve --agent ptc --permission-mode bypassPermissions --auth none --open

--agent shipped values ​

ValueUIConversation layerNotes
cliStandardNative full toolset (Bash / Read / Grep…)Default when omitted; pass it explicitly for Standard
ptcPTCREPL only; full sandboxCode Mode
minimalMinimalREPL only; sandbox provides Bash / Edit / Skill (no MCP)No Read / Glob / MCP; prompts and injected context do not teach these tools
createCreateSame tools as StandardExtra prompt for writing custom agents

A custom id is also valid (the name in .codebuddy/agents/<name>.md).

multitask is not a --serve / Web UI startup value: the entry guard rejects the process with a non-zero exit. Toggle the coordinator in-session with /multitask (interactive TUI) or session/set_config_option (configId=multitask).

--permission-mode ​

Help lists the first 6 values; runtime also accepts fullAccess.

ValueMeaning
defaultDefault: ask per rules
acceptEditsEdits auto-pass; other actions still ask
bypassPermissionsSkip permission prompts
planPlan mode. minimal + plan returns 400 — do not combine them
dontAskNever ask; deny when not already allowed
autoClassifier decides
fullAccessAccepted at runtime, not listed in help; similar to bypassPermissions

Related (rarely needed):

text
--permission-mode-before-plan <mode>   mode to restore when leaving plan
--subagent-permission-mode <mode>      subagent / teammate mode; does not inherit the main session

See Permission Modes for full semantics.

Mode × common permission ​

bash
# Standard + default permissions
codebuddy --serve --agent cli --permission-mode default --auth none --open

# Standard + skip permissions
codebuddy --serve --agent cli --permission-mode bypassPermissions --auth none --open

# PTC + skip permissions
codebuddy --serve --agent ptc --permission-mode bypassPermissions --auth none --open

# PTC + default permissions
codebuddy --serve --agent ptc --permission-mode default --auth none --open

# Minimal + skip permissions (do not add --permission-mode plan)
codebuddy --serve --agent minimal --permission-mode bypassPermissions --auth none --open

# Create + skip permissions
codebuddy --serve --agent create --permission-mode bypassPermissions --auth none --open

Other flags on the same command ​

FlagValuesNotes
--serveno valueHTTP + Web UI
--openno valueOpen the browser after ACP is up
--authpassword (default) / noneUse none for local debug
--base-pathe.g. /cnb-5gg-1k09dqp5v-001Mount the Web UI / API under a fixed path. You can also use CODEBUDDY_GATEWAY_BASE_PATH
--hostdefault 127.0.0.1Pass --host 0.0.0.0 to bind all interfaces
--portnumberAuto-selected when omitted

After setting --base-path, open the prefixed address shown on the Web UI line in the startup log, for example http://127.0.0.1:8321/cnb-5gg-1k09dqp5v-001/. PWA support is disabled in this mode to prevent the Service Worker from continuing to cache relative to the site root.

Authentication ​

The Web UI supports two authentication modes:

ModeSettingDescription
Password Auth (default)--auth password / CODEBUDDY_GATEWAY_AUTH=passwordDefault behavior for --serve; prints the password and a clickable link with the password in the terminal on startup
No Auth--auth none / CODEBUDDY_GATEWAY_AUTH=noneExplicitly disabled; prints a warning on startup. Any process on the same machine can execute commands and read/write files through this service — only recommended in isolated environments or CI

Authentication methods (any one is sufficient):

  • URL parameter: ?password=xxx — auto-login and sets a Cookie when opening the Web UI homepage (only valid on the homepage, not for /api/v1/* endpoints)
  • Login page: Enter the password displayed in the terminal
  • Bearer token: Authorization: Bearer <password> for API access
  • Cookie: gateway_session, automatically carried by the browser after login, valid for 30 days

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, images, and Mermaid diagrams (including flowcharts, sequence diagrams, and state diagrams). Diagrams follow the light or dark theme. During streaming, content first appears as a code block and is automatically replaced by a diagram when the fence closes. You can copy the source or export the diagram as SVG.
  • Nested-fence example preview: When a markdown code block contains another fenced block to demonstrate a Markdown snippet, the outer block renders as an example: plain text remains unchanged, inner fences use syntax highlighting for their own language, and copying still captures the entire original text.
  • Copy and export: Model output, user messages, channel messages, code blocks, and tool-call parameters and results all provide one-click copying. Markdown tables can be copied as Markdown or TSV, and Mermaid diagrams can be copied as source or exported as SVG. The top-right corner can export the entire conversation as Markdown or JSON, with JSON preserving the complete timeline. Copy buttons remain visible on touchscreens and narrow screens.
  • 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
  • Working directory management: Add or remove additional working directories to expand the Agent's file access scope. Working directories and agent mode are shown together at the top of the input card; they can be selected for a new session and become read-only once the session starts.
  • Main agent: On a blank session, switch cli / ptc / minimal / create or a custom agent. Chip picks write codebuddy.mainAgent.lastUsed and do not change default. Process --agent overrides lastUsed. Sessions with history lock the current agent. The equivalent TUI entry point is /agent-mode; selections are remembered and locked after the conversation starts. WorkBuddy neither displays nor parses this setting.
  • Right-side workbench: Explorer, file search, source control, file editing, and terminal each have a dedicated tool tab. The workbench supports one-click full screen and drag resizing; narrow panels automatically switch the file tree/editor layout and hide the editor minimap. File paths in conversations can jump to a specific line or line range. A regular URL click opens a safe preview in the workbench, while Cmd/Ctrl-click opens it in a new browser tab. Local HTML files can switch between source and safe preview. The editor, preview, and file tree can download the current file locally.
  • Goal: Enter /goal or open goal mode from the input box. Pause immediately unregisters continuation and aborts the current turn; the bar stays paused. Resume restarts with the same condition. Trash clears the goal and hides the bar.

Editor View ​

The Web IDE editor area supports multi-group workflows:

  • Group layout: Drag file or terminal tabs to an edge of the editor area to split horizontally or vertically, with up to 4 groups
  • Cross-group dragging: Move and reorder file tabs between groups
  • Terminal docking: Drag terminal tabs between the bottom panel and editor groups while preserving the current PTY session
  • Layout restoration: Refreshing the page restores the group structure, active tabs, and split ratios

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

Background sessions ​

The Web UI Agent View uses /api/v1/jobs for background agents. External workers stay in the separate Workers view and are not mixed into the jobs list.

  • Project list: Grouped by working directory, with pin, project groups, search, and completion notifications. Running jobs show a live indicator; jobs waiting for input show a needs-input hint.
  • Dispatch a new session: Choose a main agent (same catalog as the chat bar: four built-in modes + custom), model, reasoning effort, startup permission, launch directory, custom name, and shell mode, plus image and file attachments. Request fields: agent, model, effort, permissionMode, sourceSessionId (inherit limited context), bgIsolation (none / worktree; omitted follows the global setting). GET /api/v1/jobs/dispatch-context returns defaultAgentName, agents, and permissionMode (process --permission-mode). minimal cannot be combined with permissionMode=plan.
  • Context menu: Stop, restart, pin/unpin, rename, remove from project, copy session ID, copy working directory, and delete.
  • Session restore: Restarting a job restores its session. When the browser reopens, the main Web UI loads history with the persisted session ID and falls back to continue selection only on failure. Opening an existing subagent keeps the current view and input box instead of refreshing the entire page; the previous screen remains visible until history replay completes. When the URL contains a session ID, transient load failures are retried instead of opening a new session. Changing the model while a subagent is running is saved on that instance and persists after restart without changing the main chat's default model.
  • Embedded chat: Same-origin iframe pool on the parent gateway. The SPA is served by the parent; ACP / goal / internal APIs are reverse-proxied through /api/v1/jobs/:id/frame/ to that job's loopback. Storage, auth, and jobs stay on the parent. The iframe src does not carry the gateway password. Each page has an independent input box; during restore, drafts are moved only when a frame is unloaded rather than sharing a single input.
  • Channels and direct messages: Channel acknowledgements are attributed to the channel rather than rendered as “message from user”; @ in a 1:1 input box only provides autocomplete. After the user speaks in a channel, the avatars of awakened participants immediately show as busy. The default Agent is not included in the roster and does not receive unread counts for @everyone.
  • Conversation data: GET /api/v1/jobs/:id/transcript returns up to the latest 1000 ACP replay updates; GET /api/v1/jobs/:id/stream replays the transcript tail then tails new output over SSE.
  • Lifecycle: reply, stop, respawn, and delete. A delete blocked by a foreground-hold or worktree guard returns { deleted: false, reason }; the UI keeps the job and shows the reason.
  • Live updates: The list receives snapshot, added, changed, removed, and keepalive events from /api/v1/jobs/events.

See HTTP API — Jobs for endpoints, fields, error codes, and curl examples.

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
  • Main agent: Master switch codebuddy.mainAgent.enabled (on by default); "allow unopted hosts" allowUnopted (off by default, WorkBuddy stays native cli). The management page can set default and create custom agents with AI. Chip picks and the TUI /agent-mode write only lastUsed.

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; Mermaid diagrams are loaded dynamically on demand (only when a message contains a mermaid code block, so they do not increase the initial page load)