CLI
IDECLIWorkBuddyWorkBuddy Enterprise

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) and file paths dragged in from the Explorer
  • 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; create, edit, pause, or resume scheduled tasks; and view run history
  • 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.
  • Media preview: Local SVG images in the conversation render directly, and MP4, WebM, M4V, MOV, OGV, AVI, and MKV files get an inline video player. Files in remote workspaces load through authenticated endpoints and are still previewed in your local browser.
  • 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. Enter /export to download a ZIP archive of the current session, containing the conversation transcript and any available session logs; from shared workspace logs, only lines containing the current session ID are included. The archive may contain prompts, local paths, and sensitive information, so review it before sharing. 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
  • Completion and pending notifications: Get desktop notifications when a turn completes, a background task finishes, or the Agent is waiting for permission or answers; when connected to a remote workspace, notifications still go to your local desktop. Permission and copy-request-ID buttons show tooltips on hover.
  • 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
  • File path drag-and-drop: Drag files from the Explorer into the terminal to paste their paths, automatically escaped according to the current system's shell rules

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

AI Colleague Directory ​

The Web UI sidebar has a single workspace: the AI colleague directory. There is no longer a "solo / team" mode switch.

  • Default CodeBuddy: The default CodeBuddy at the top of the directory opens the main conversation session, sharing the same history as the former regular chat.
  • AI colleagues: Each colleague has its own independent Job / Session history; Jobs without an owner are still listed in the directory as usual.
  • Autonomous teaming switch: The settings page option "AI colleagues → Let agents team up on their own" (codebuddy.agentHome.orchestration) only controls whether the Agent can create and contact colleagues on its own, use channel task boards, and wake members. When turned off, the directory and existing colleagues, channels, and Jobs are all kept; the channel page notes that "colleagues will not be woken and the task board is read-only" and provides a link to enable it in settings. When locked by an environment variable, the switch is grayed out with an explanation.
  • Fallback: When Agent Home is turned off by the master switch or the ops rollback key, or when connected to an older backend that does not support this API, the sidebar falls back to the regular session / Job list.
  • Entry boundaries: Teaming tools and context are only available to turns sent from the Web UI and to AI colleague Jobs. Sessions started in the terminal do not get them; when a session used in the Web UI is continued in the same terminal, turns sent from the terminal do not get them either (even after the browser is closed), and they are restored when the Web UI sends again. WorkBuddy, IDE ACP, -p, and SDK stream-json are not affected.

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.

Relay Web Access (Open Directly in a Browser or Phone) ​

Besides connecting SSH between intranet devices, the Relay tunnel section of the Host Management page can bind the local Web UI to a fixed subpath on the relay gateway, so it can be opened directly from any browser or phone that can reach the gateway, with nothing to install on the accessing side. iOA accounts use the built-in gateway http://frp.devcloud.woa.com by default.

  1. In the gateway card's Web access section, click New binding. In the dialog, enter a subpath (leave empty to generate 10 random characters; availability is checked as you type), choose an access mode, enable the access key if needed, optionally enter other iOA accounts allowed to access, and click Bind. On phones the dialog is full screen.
  2. The dialog shows the final address http://frp.devcloud.woa.com/w/<subpath>/, which you can copy or scan. Each row in the list also offers copy, QR code, and Settings (opens the same dialog to change the access mode, key, and allow list; the subpath is read-only).
  3. When opened in a browser, access is verified according to the access mode:
    • iOA sign-in (default): Sign in with an iOA account (reusing the CodeBuddy login page). Access is granted to the binding owner (the same iOA identity) and iOA accounts on the allow list; anyone else sees "No access permission" after signing in.
    • Key only: No sign-in required, and the access key is always enabled. Opening the full link with the key goes straight to the page; without the key, only the key input page is shown. Anyone with the full link can open it, so keep it safe; the allow list does not apply in this mode.

Rules:

  • Subpath: 3-48 lowercase letters, digits, or hyphens, globally unique on the gateway. It is checked as you type; a subpath already taken (including by someone else's binding) cannot be bound, and reserved words such as api, admin, and console are not allowed.
  • Allow list (optional, only yourself by default, only applies to iOA sign-in): When binding or in Settings, enter the iOA English names of other users allowed to access (for example runpeihe, comma-separated, up to 50). They just sign in with their own iOA and do not need a relay account; if the access key is enabled, they also need the key. Removal from the list takes effect immediately. Any device under the same account can edit the list.
  • Access key (optional): When enabled, the key is required to open the page. Copy full link gives an address with ?relay_key=<key>; when already signed in, the gateway verifies the key directly and enters the page (without showing the key input page first), stores the key in that browser's localStorage per subpath, and removes it from the address bar, so later visits work without the query. You can turn it off or New key at any time (browsers that saved the old key need to open the full link again). The plaintext key is stored only on the device that created it; the gateway stores only its hash.
  • Authentication responsibilities: iOA sign-in, owner / allow list, and access key are all verified by the gateway. When forwarding, the gateway attaches a relay token generated by the local machine, which the local machine uses to recognize requests from the gateway, skip the Web UI password, and use /w/<subpath> as the page prefix. Direct connections to the relay port on the gateway are rejected; access is only through /w/<subpath>/.
  • Online status: The binding follows the local CodeBuddy Code process and is restored automatically after restart; when the local machine is not running, visitors see a "Device offline" page that retries automatically. After unbinding, the address becomes invalid immediately and the subpath is released.
  • Bindings created by other devices under the same gateway account are shown as Other device; you can copy the link, edit the allow list, or unbind them, but cannot change their access key.

Gateway administrators can view service status and manage all accounts, tunnels, Web bindings, and browser sessions at http://frp.devcloud.woa.com/console.

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
  • Relay Web access: Open the local Web UI on your phone via the relay gateway at /w/<subpath>/; see Relay Web Access

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)