OpenCode Visualizer CN

English | 中文

简介

本项目是 OpenCode 的一个第三方 Web UI，fork 自 vis。由于上游仓库不接受 PR，我们将其作为独立项目持续维护，并进行了大量功能改进、性能优化和本地化支持。

核心改进方向：i18n 支持、字体与主题管理、会话批量操作与 Pin 功能、悬浮窗与 Dock 栏管理、性能优化、桌面应用打包。

功能特性

上游原始功能（由 xenodrive/vis 提供）

本项目完整保留了上游 Vis 的所有核心功能：

审阅优先的悬浮窗口 — 以审阅为核心设计的浮动窗口系统，保持工具输出和智能体推理过程的完整上下文，支持交互式审阅与回溯
多项目与会话管理 — 支持多项目和工作树（Worktree）的会话组织，轻松切换不同代码库与分支上下文
代码与 Diff 查看器 — 内置语法高亮，支持多种编程语言的代码展示与 diff 对比，专为快速、自信的代码审阅设计
交互式智能体工作流 — 权限请求、问题提示等人机协作交互，让 AI 代理在关键操作前获得用户确认
嵌入式终端 — 基于 xterm.js 的完整终端模拟器，支持 Shell 交互与命令执行

原项目同时支持 Cloud（托管版免安装） 和 Local（本地部署） 两种使用方式。本项目在此基础上扩展了更多功能。

本项目新增功能

功能类别	改进内容	状态
国际化 (i18n)	完整 i18n 框架支持，支持简体中文、繁体中文、日语、世界语	✅ 已上线
字体管理	支持设置 Shell 字体、界面等宽字体，支持设置终端/代码/消息/UI/侧边栏字体大小，系统字体自动发现	🅱️ Beta
供应商与模型管理	查看/启用/禁用本地模型和供应商；支持所有提供商的 Web 端连接、自定义提供商连接；完善的 i18n 支持	✅ 已上线
状态监控	查看服务器、MCP、LSP、Plugin、Skills 状态；支持关闭 MCP 连接；实时显示当前会话 Token 消耗（上下文限制、输入/输出/推理 Token、使用率进度条）	✅ 已上线
主题设置	自定义各卡片不同组件颜色	🅱️ Beta
编辑器集成	使用系统 `$EDITOR` 打开文本文件	✅ 已上线
代码行评论	鼠标拖拽选择范围，评价并附加到输入框	✅ 已上线
会话树管理	侧栏增加会话树栏，基于项目-沙盒-会话的三层级进行会话置顶	✅ 已上线
批量管理	顶栏 Management 按钮，多选 Session 操作	✅ 已上线
取消归档	找回已归档的 Session	✅ 已上线
会话重命名	重命名 Session	✅ 已上线
悬浮窗管理	全面覆盖的关闭/最小化按钮，底部 Dock 栏存放最小化窗口	✅ 已上线
悬浮窗预览自动换行	在设置中开启/关闭；超大文件使用可变行高虚拟滚动，换行时仍限制实际挂载行数	✅ 已上线
快捷命令	支持 `@` 显式召唤代理、`$` 召唤技能	✅ 已上线
代码片段 (Snippets)	自定义触发词（`\name` 或 `::name`、`;name` 等带标点前缀）与动态变量（`{date}`、`{time}`、`{datetime}`、`{uuid}`、`{clipboard}`、`{activeFile}`、`{cwd}`、`{selection}`、`{cursor}`）；标签筛选、启用开关、导入/导出；可从收藏一键创建；输入触发词后显式选择补全展开	✅ 已上线
本地文件编辑	内置 CodeMirror 6 编辑器，在 Web 端编辑本地文件：三个后端均通过桥接 `/fs/writeFile` 写入（OpenCode 经已连接的 vis_bridge 并回读校验，Codex / ACP 经各自桥接工作区接口）；编辑器字号、缩进与键盘快捷键可自定义；桌面端可用本地应用打开临时副本并将每次保存同步回后端，带磁盘变更冲突保护	✅ 已上线
文件树 Git 操作	基于 git status 的文件树，支持暂存区/变更/全部三种视图与 diff 统计；分支搜索、创建（输入新名称）、切换、合并、变基、删除本地分支；ahead/behind 徽标提供 push/pull，分支与上游操作菜单提供 fetch。切换分支与 fetch 直接执行，合并/变基/删除/push/pull 需确认；这些用户触发的分支操作在一次性 PTY（`/bin/sh -c`）中运行，成功后自动关闭并刷新文件树	✅ 已上线
性能优化	超大 Session 懒加载、超多 Session 后台 Hydration、冷启动加速、输出面板连续批次加载、悬浮窗弹出性能优化	✅ 已上线
桌面应用	Electron 桌面端打包，支持 Windows / macOS / Linux；应用与 vis_bridge 的应用内更新检查与下载、系统托盘（最小化/关闭到托盘）、任务完成桌面通知与可选提示音	✅ 已上线
Codex 集成 (Alpha)	vis_bridge 轻量桥接器转发 Codex app-server JSON-RPC；Codex Panel 最小化悬浮窗面板，内置模型、技能、插件市场、MCP 服务器与本地文件管理；运行时检查器按方法探测 app-server 能力（支持/不支持/需开启实验开关）；设置中开启实验性功能	🅰️ Alpha
ACP Agent 集成 (Alpha)	ACP v1 作为第三后端复用主会话界面；状态监控中管理 Pi、Oh My Pi、Kimi Code 等 ACP Agent	🅰️ Alpha
Forge 集成 (Beta)	基于 zsh PTY 的 Forge 悬浮终端；命令菜单、结构化会话侧栏、状态读取与刷新恢复	🅱️ Beta
Kimi Web 集成 (Alpha)	kimi web 作为第四后端，REST 与 WS 经 vis_bridge 转发、kimi bearer 由 bridge 惰性注入（浏览器不直连上游）；复用主会话界面，覆盖建/选会话、流式文本与思考、历史（含注入消息过滤）、审批与提问、重命名/归档/恢复/删除/中止、steer、附件、Token 用量与状态监控；工具、推理、子代理三路悬浮窗自动弹出；能力探测通过前不暴露对应入口	🅰️ Alpha

📋 详细变更日志：请参阅 CHANGELOG.md
🗺️ 路线图与计划：请参阅 RoadMap.md

技术栈

层级	技术	说明
前端框架	Vue 3 + Composition API	响应式 UI 框架
构建工具	Vite	极速开发与构建
样式方案	Tailwind CSS v4 + PostCSS	原子化 CSS
终端组件	xterm.js	嵌入式终端模拟器
代码高亮	Shiki	语法高亮与 Markdown 渲染
国际化	Vue I18n	多语言支持
后端服务	Hono + `@hono/node-server`	轻量级 HTTP 服务
桌面端	Electron	跨平台桌面应用打包
代码规范	oxlint + oxfmt	高性能 JS/TS 代码检查与格式化
测试框架	Vitest	单元测试

环境要求

在开始前，请确保你的环境满足以下条件：

依赖	版本要求	说明
Node.js	≥ 24 且 < 25	运行时与构建环境
pnpm	11.21.0 (推荐)	包管理器，本项目使用 `packageManager` 锁定
OpenCode Server	最新版	后端服务，提供 API 与智能体能力
ACP Agent CLI	可选	如 `pi-acp`、`omp --mode acp`、`kimi acp`；在状态监控中按需启用
系统 `$EDITOR`	可选	用于"用编辑器打开"功能（如 VS Code、Neovim 等）

💡 提示：本项目默认端口已从 3000 修改为 23003，以减少在 WSL 上与 Windows 服务的端口冲突。

快速开始

git clone https://github.com/qiyuanhuakai/opencode-visualizer-cn
cd opencode-visualizer-cn
pnpm install
pnpm build
node server.js

建议使用 nohup node server.js 2>&1 & 将服务器放在后台持久运行。

然后打开 http://localhost:23003。

部署到 GitHub Pages

本仓库内置 .github/workflows/deploy.yml，可直接把前端静态资源托管到 GitHub Pages，让浏览器作为 SPA 直连本机 OpenCode server。

# 1. 推到你的 GitHub 仓库
git push origin main

# 2. 仓库 Settings → Pages → Source 选择 GitHub Actions
# 3. 本机启动 OpenCode 时务必声明 CORS：
opencode serve --cors https://<user>.github.io

详细步骤、自定义域名、CORS 排错，请参阅 docs/deploy-github-pages.md。

vis_bridge 使用说明

vis_bridge 是本地进程监督器与协议桥接器：启动时探测并托管 OpenCode server、Codex app-server，并按配置启动 ACP Agent。Codex 使用原生 WebSocket JSON-RPC；ACP v1 Agent 使用 stdio JSON-RPC 到 WebSocket 的转发。

安装 Codex CLI

确保已安装 OpenAI Codex CLI，并且 codex 命令在 PATH 中可用：

codex --version

启动 vis_bridge

发布页只提供原生安装包，不直接发布 vis_bridge 单文件：

平台	安装文件	安装结果
Linux	`VisBridge-<version>-<arch>-Linux.deb` / `VisBridge-<version>-<arch>-Linux.rpm`	分别适用于 DEB / RPM 系统，安装到 `/usr/bin/vis_bridge`
macOS	`VisBridge-<version>-<arch>-MacOS.pkg`	安装到 `/usr/local/bin/vis_bridge`
Windows	`VisBridge-<version>-<arch>-Windows.exe`	安装到 `%LOCALAPPDATA%\Programs\vis_bridge` 并加入用户 PATH

从 GitHub Releases 下载当前平台的安装包并运行；Windows 安装后需重新打开终端。安装完成后可验证：

vis_bridge --help

安装后使用守护进程命令启动、停止或重启：

vis_bridge start
vis_bridge stop
vis_bridge restart

在 bridge 所在主机的外部终端中手动更新：

vis_bridge update --check  # 仅查询最新正式版本，不下载或安装
vis_bridge update          # 显示更新信息并确认后安装
vis_bridge upgrade --yes   # update 的别名；非交互使用需显式确认

更新仅适用于原生安装包管理的 vis_bridge；源码或自定义位置仍可执行 --check。Linux 根据包归属及发行版选择 DEB/RPM，macOS 使用 PKG，Windows 使用每用户 NSIS 安装包；下载须通过大小与 SHA-256 校验。安装会停止 bridge 及其子进程，不自动重启，不能从 bridge 自己托管的终端发起安装。POSIX 终端保留安装器退出状态，非 root 用户需要 sudo 权限；Windows 在原命令退出后交接安装，并打印持久结果日志位置，交接成功不等于安装成功。

start 会等待 bridge 完成监听和初次服务探测后再返回。OpenCode、Codex 或 ACP Agent 启动失败时，命令行会直接列出对应名称和错误；bridge 本身仍可用时会继续在后台运行，完整错误也会显示在“状态监控”→“ACP”中。配置损坏或端口被占用等 bridge 级错误会让 start 以失败退出，不会留下一个表面可用的服务。

Linux 的 --check 在有新版时也需要可识别的发行版及包管理工具，无法确定 DEB/RPM 时会明确失败。安装前若祖先进程身份不可读，会在确认后请求仅用于读取进程身份的 sudo 权限，不能因此跳过托管终端检查。

源码开发使用相同的守护进程命令：

# 源码运行
node vis_bridge.js start

# 构建并运行单文件可执行程序
pnpm bridge:build
./dist-bridge/vis_bridge start

vis_bridge 会自动探测或启动默认的 OpenCode 与 Codex 服务。ACP Agent 中 Kimi Code、Oh My Pi 与 Pi 默认启用，其余可在右上角“状态监控”→“ACP”中启用；详细参数请运行 vis_bridge --help。监听非环回地址时必须配置 bridge token，以保护 PTY、文件、命令、状态、ACP 与 Codex 转发接口。守护进程的状态和日志保存在当前用户目录中（Linux：~/.local/state/vis/bridge，macOS：~/Library/Application Support/vis/bridge，Windows：%LOCALAPPDATA%\vis\bridge）。直接通过 --bridge-token 或 --upstream-token 传入的密钥不会写入守护进程状态或长期保留在守护进程参数中；需要无参数 restart 时请改用环境变量或 token 文件。--target 必须是不带用户名、密码、查询参数或片段的 ws:///wss:// 地址，上游认证请使用专用 token 选项。macOS 手动删除 /usr/local/bin/vis_bridge 前请先运行 vis_bridge stop。

使用 Codex Panel

进入 Vis 的"设置"
在"实验性功能"区域开启"Codex Panel"
右上角会出现codex panel按钮
点击按钮并连接vis_bridge即可与codex panel交互

⚠️ 注意：Codex Panel 目前为 Alpha 状态，功能可能不稳定。需要有效的 OpenAI API 密钥和 Codex CLI 权限。

Forge Panel 使用说明

Forge Panel 是一个轻量级的 zsh PTY 悬浮窗口，直接运行本机 Forge CLI；实时输出始终由 xterm.js 原样渲染，不依赖终端文本识别。

前置条件

确保已安装并配置 Forge，且 forge 命令可在登录 zsh 中使用。需要使用 : 快捷命令时，先运行 Forge 的 setup 流程：

forge setup

使用 Forge Panel

进入 Vis 的“设置” → “实验性功能”，开启“Forge Panel 按钮”
顶栏管理模式按钮右侧会出现 Forge 按钮，点击后打开 zsh PTY 悬浮窗口
顶部菜单可执行配置、临时设置、工作区与对话操作；状态菜单提供 :info、:tools、:skill 与 :workspace-info
底部输入框可选择 Forge、Muse、Sage、Suggest 或 Commit Preview，并将提示词写入 PTY
右侧结构化栏使用 Forge CLI 读取状态、会话列表与预览；可执行 :new、:clone、:conversation、:conversation-rename、:conversation-tree 和 :delete

侧栏可拖动调整宽度；向右拖过隐藏阈值后折叠，拖动隐藏滑杆向左可恢复。会话命令会随侧栏宽度在 6×1、3×2、2×3 布局间切换。Forge PTY 在页面刷新后会恢复为完整 Forge Panel，而不是普通终端。

⚠️ 注意：Forge Panel 目前为 Beta 状态。结构化读取依赖当前工作目录中的 Forge 数据；实时交互仍以 PTY 终端为准。

代码片段（Snippets）使用说明

代码片段让你把常用提示词保存为可复用模板，在输入框中通过触发词展开。

进入 Vis 的"设置" → "片段"，确认"启用片段"已开启
新建片段：设置触发词、正文，可附加标签便于筛选；保存自动完成
触发词默认以 \name 形式展开；使用 ::name、;name 等带标点的触发词可自定义前缀
正文中可使用动态变量：{date}、{time}、{datetime}、{uuid}、{clipboard}、{activeFile}、{cwd}、{selection}，以及 {cursor} 指定展开后的光标位置
在输入框中输入触发词，从补全列表选择对应片段或按 Enter 展开；Space 和 Tab 保持原有输入行为
收藏夹中的消息可通过"从收藏创建片段"直接转为代码片段；片段支持导出/导入 JSON 文件

功能展示

1. 主界面与简体中文支持

<-- -->

2. 字体管理

<-- --> <-- -->

3. 供应商与模型管理

<-- --> <-- --> <-- -->

4. 状态监控

<-- -->

5. 主题设置

<-- -->

6. 代码行评论

<-- -->

7. Session Pin

<-- -->

8. 批量管理

<-- -->

9. 悬浮窗与 Dock 栏

<-- -->

10. 编辑器打开

<-- -->

开发与构建

Web 开发

pnpm install
pnpm dev

Electron 桌面端

应用内更新、托盘、精简本地化菜单、任务完成通知与声音设置见桌面集成说明。macOS 保留现有 ad-hoc 签名，通过下载后手动安装更新；vis_bridge 使用独立系统安装器。

本项目支持将 Web UI 打包为原生桌面应用，基于 Electron 框架，支持 Windows、macOS 和 Linux 三大平台。

桌面端特性：

独立应用窗口，无需浏览器，支持 macOS 隐藏式标题栏
安全沙箱（contextIsolation + sandbox），外部链接通过系统浏览器打开
开发模式下自动处理 CORS，便于本地调试
应用与 vis_bridge 分别检查更新：Windows / Linux 安装版支持应用内下载安装；macOS 应用下载 DMG 后手动安装，vis_bridge 使用 PKG 安装包。自动检查与自动下载默认关闭，安装始终需要确认
可选"最小化到托盘"与"关闭到托盘"（默认关闭），托盘菜单可退出
远程 bridge 保留连接版本显示，需在其所在主机更新；仅本机回环连接提供本机安装包的更新操作
会话任务完成时弹出桌面通知，窗口可见且聚焦时同样生效；可选系统提示音（默认关闭）。macOS ad-hoc 构建不支持原生通知，仅保留声音回退
原生菜单跟随应用语言，保留退出与刷新入口
支持 NSIS / AppImage / deb / dmg 各平台安装包
运行时基线：Electron 43.4.1（Chromium 150 / Node 24.18.1），Chromium 沙箱全程开启

macOS 签名状态（重要）： macOS 安装包为 ad-hoc 签名（无 Developer ID、未分配 TeamIdentifier、无 notarization，mac.identity: "-"、mac.notarize: false）。Intel 与 Apple Silicon 产物均已在 macOS runner 上通过 codesign --verify --deep --strict，并分别验证 DMG 挂载与 ZIP 解压后的应用。Gatekeeper 仍会显示"无法验证开发者"的常规提示，需要右键 → 打开；macOS 上 Notifications 不可用，notarization 亦未配置。这些限制为本版本接受的明确决策，详见 CHANGELOG.md。

# 启动 Electron 开发模式（会自动复用或拉起 5173 上的 Vite）
pnpm electron:start

# 打包预览（不生成安装器）
pnpm electron:preview

# 完整构建（生成各平台安装包）
pnpm electron:build

说明：

pnpm electron:start 会先检查 127.0.0.1:5173 上是否已有 Vite；如果没有，会自动启动 pnpm dev 并等待就绪后再拉起 Electron。
pnpm dev 仍固定使用 127.0.0.1:5173，如果端口已被其它进程占用会直接报错，避免 Electron 连错端口。

构建产物输出到 dist-electron/，包含：

Windows：.exe (NSIS)
macOS：.dmg / .zip (Intel / Apple Silicon)
Linux：.AppImage / .deb

声明

本项目是为 OpenCode 构建的第三方 Web UI，并非由 OpenCode 团队开发，且与他们没有任何关联。

本项目基于 xenodrive/vis 构建，感谢原作者的出色工作。

License

MIT

Introduction

This project is a third-party Web UI for OpenCode, forked from vis. Since the upstream repository does not accept PRs, we maintain it as an independent project with significant feature improvements, performance optimizations, and localization support.

Core Improvement Areas: UI internationalization (i18n), font & theme management, session batch operations & Pin functionality, floating window & Dock bar management, performance optimization, desktop app packaging.

Features

Original Features (from xenodrive/vis)

All upstream Vis core features are fully preserved:

Review-first Floating Windows — Window-style floating panels designed around code review, preserving full context of tool output and agent reasoning for interactive review and backtracking
Multi-project Session Management — Organize sessions across multiple projects and worktrees, easily switch between different codebases and branch contexts
Code & Diff Viewer — Built-in syntax highlighting supporting multiple programming languages, with diff comparison designed for fast, confident code review
Interactive Agent Workflows — Permission requests, question prompts, and other human-in-the-loop interactions, allowing AI agents to get user confirmation before critical operations
Embedded Terminal — Full terminal emulator based on xterm.js with Shell interaction and command execution

The original project supports both Cloud (hosted, no installation) and Local (self-hosted) deployment modes. This project extends it with additional features.

New Features in This Project

Category	Feature	Status
Internationalization (i18n)	Full i18n framework supporting English, Simplified Chinese, Traditional Chinese, Japanese, and Esperanto	✅ Available
Font Management	Shell font, UI monospace font, adjustable terminal/code/message/UI/sidebar font sizes, system font auto-discovery	🅱️ Beta
Provider & Model Management	View/enable/disable local models and providers; support all provider Web connections and custom provider connections; full i18n support	✅ Available
Status Monitor	View server, MCP, LSP, Plugin, Skills status; close MCP connections; real-time session token usage (context limit, input/output/reasoning tokens, usage progress bar)	✅ Available
Theme Settings	Customize colors for different card components	🅱️ Beta
Editor Integration	Open text files with system `$EDITOR`	✅ Available
Code Line Comment	Drag to select range and append comment to input	✅ Available
Session Tree Management	Added a session tree panel in the sidebar; sessions are pinned based on a three-level hierarchy of project-sandbox-session	✅ Available
Batch Management	Top bar "Management" button for multi-select Session operations	✅ Available
Unarchive	Restore archived Sessions	✅ Available
Rename Session	Rename Session	✅ Available
Floating Window Management	Close/minimize buttons for all popups, bottom Dock bar	✅ Available
Floating Preview Auto-Wrap	Toggle in Settings; oversized files use variable-row-height virtual scrolling, still capping actually mounted rows while wrapped	✅ Available
Quick Commands	`@` to explicitly summon agents, `$` to invoke skills	✅ Available
Snippets	Custom triggers (`\name`, or punctuation-prefixed like `::name` / `;name`) with dynamic variables (`{date}`, `{time}`, `{datetime}`, `{uuid}`, `{clipboard}`, `{activeFile}`, `{cwd}`, `{selection}`, `{cursor}`); tag filtering, per-snippet toggle, JSON import/export; create snippets from favorites; type a trigger and pick its completion or press Enter to expand	✅ Available
Local File Editing	Embedded CodeMirror 6 editor; edit local files from the web UI on all three backends via the bridged `/fs/writeFile` (OpenCode writes through the connected vis_bridge with a verify-read, Codex / ACP through their bridged workspace endpoints); adjustable editor font size, indent, and remappable keyboard shortcuts; on desktop, open a temporary copy in a local application and sync each save back to the backend with on-disk conflict protection	✅ Available
File Tree Git Actions	git-status-based file tree with Index/Changes/All views and diff stats; branch search, create (prompts for a name), checkout, merge, rebase, and local branch deletion; push/pull on ahead/behind badges, and fetch in the branch/upstream action menu. Checkout and fetch run immediately; merge/rebase/delete/push/pull ask for confirmation; these user-triggered branch actions run in a one-shot PTY (`/bin/sh -c`) that closes on success and refreshes the file tree	✅ Available
Performance	Lazy loading for large sessions, background hydration, faster cold start, continuous batched output loading, floating window popup optimization	✅ Available
Desktop App	Electron desktop packaging for Windows / macOS / Linux; in-app update checks and downloads for both the app and vis_bridge, system tray (minimize/close to tray), desktop completion notifications with optional sound	✅ Available
Codex Integration (Alpha)	vis_bridge lightweight bridge for Codex app-server JSON-RPC; Codex Panel minimal floating panel with built-in model, skill, plugin marketplace, MCP server, and local file management; runtime inspector probes app-server capabilities per method (supported/unsupported/gated); experimental features toggle in settings	🅰️ Alpha
ACP Agent Integration (Alpha)	ACP v1 as a third backend using the shared main chat UI; manage Pi, Oh My Pi, Kimi Code, and other ACP agents in Status Monitor	🅰️ Alpha
Forge Integration (Beta)	zsh PTY-based Forge floating terminal with command menus, structured conversation sidebar, status reads, and refresh restoration	🅱️ Beta
Kimi Web Integration (Alpha)	kimi web as the fourth backend; REST and WebSocket are forwarded through vis_bridge with the kimi bearer injected lazily by the bridge (the browser never dials upstream); reuses the main chat UI for session create/select, streaming text and thinking, history with injection filtering, approvals and questions, rename/archive/restore/delete/abort, steer, attachments, token usage, and status monitoring; tool, reasoning, and subagent popups open automatically; entry points stay hidden until capability probing succeeds	🅰️ Alpha

📋 Detailed changelog: CHANGELOG.md
🗺️ Roadmap & Plans: RoadMap.md

Tech Stack

Layer	Technology	Description
Frontend Framework	Vue 3 + Composition API	Reactive UI framework
Build Tool	Vite	Fast development and production builds
Styling	Tailwind CSS v4 + PostCSS	Atomic CSS utility framework
Terminal	xterm.js	Embedded terminal emulator
Code Highlighting	Shiki	Syntax highlighting and Markdown rendering
Internationalization	Vue I18n	Multi-language support
Backend Service	Hono + `@hono/node-server`	Lightweight HTTP server
Desktop	Electron	Cross-platform desktop app packaging
Linting	oxlint + oxfmt	High-performance JS/TS linting and formatting
Testing	Vitest	Unit testing framework

Requirements

Before getting started, ensure your environment meets the following criteria:

Dependency	Version	Description
Node.js	>= 24 and < 25	Runtime and build environment
pnpm	11.21.0 (recommended)	Package manager, locked via `packageManager`
OpenCode Server	Latest	Backend service providing API and agent capabilities
ACP Agent CLI	Optional	For example `pi-acp`, `omp --mode acp`, or `kimi acp`; enable agents as needed in Status Monitor
System `$EDITOR`	Optional	For "Open in Editor" feature (e.g., VS Code, Neovim)

💡 Tip: This project changed the default port from 3000 to 23003 to reduce conflicts with Windows services when using WSL.

Quick Start

git clone https://github.com/qiyuanhuakai/opencode-visualizer-cn
cd opencode-visualizer-cn
pnpm install
pnpm build
node server.js

We recommend using nohup node server.js 2>&1 & to run the server persistently in the background.

Then open http://localhost:23003.

Deploying to GitHub Pages

This repo ships .github/workflows/deploy.yml, which builds the SPA and publishes it to GitHub Pages so the browser can connect directly to your local OpenCode server.

# 1. Push to your GitHub repository
git push origin main

# 2. In your repo: Settings → Pages → Source → GitHub Actions
# 3. Start OpenCode with an explicit CORS origin:
opencode serve --cors https://<user>.github.io

Full steps, custom domain, and CORS troubleshooting: see docs/deploy-github-pages.md.

vis_bridge Usage

vis_bridge is a local process supervisor and protocol bridge. At startup it probes and manages OpenCode server and Codex app-server, then starts configured ACP agents. Codex keeps its native WebSocket JSON-RPC transport; ACP v1 agents are forwarded from stdio JSON-RPC to WebSocket.

Install Codex CLI

Ensure you have the OpenAI Codex CLI installed and the codex command is available in your PATH:

codex --version

Start vis_bridge

GitHub Releases publish native installers only, not the intermediate standalone vis_bridge binary:

Platform	Installer	Result
Linux	`VisBridge-<version>-<arch>-Linux.deb` / `VisBridge-<version>-<arch>-Linux.rpm`	For DEB / RPM systems respectively; installs `/usr/bin/vis_bridge`
macOS	`VisBridge-<version>-<arch>-MacOS.pkg`	Installs `/usr/local/bin/vis_bridge`
Windows	`VisBridge-<version>-<arch>-Windows.exe`	Installs under `%LOCALAPPDATA%\Programs\vis_bridge` and adds it to the user PATH

Download and run the installer for your platform from GitHub Releases. Open a new terminal after installing on Windows, then verify the installation:

vis_bridge --help

After installation, control the background daemon with:

vis_bridge start
vis_bridge stop
vis_bridge restart

start waits until the bridge is listening and the initial service probe has completed. If OpenCode, Codex, or an ACP agent fails to start, the CLI prints the component name and error while keeping the usable bridge online; the full error also appears under Status Monitor → ACP. Bridge-level failures such as an invalid config or occupied listen port make start fail instead of publishing a superficially healthy service.

Update manually from an external terminal on the bridge host:

vis_bridge update --check  # Query the latest stable release without downloading or installing
vis_bridge update          # Show the offer, then confirm installation
vis_bridge upgrade --yes   # Alias for update; explicit consent for non-interactive use

Installation requires a native-package-managed vis_bridge; source and custom-location builds may still use --check. Linux selects DEB/RPM using package ownership and distribution evidence, macOS uses PKG, and Windows uses the per-user NSIS installer. Downloads must pass size and SHA-256 verification. Installation stops the bridge and its children without restarting them; do not install from a bridge-hosted terminal. POSIX preserves the installer exit status and requires sudo privileges when non-root. Windows waits for the original command to exit, then runs the installer and records its result at the printed persistent log path; accepted handoff does not mean successful installation.

On Linux, an available update also requires a recognized distribution and package tools for --check; ambiguous DEB/RPM selection fails explicitly. After confirmation, installation may request narrowly scoped sudo access to inspect otherwise unreadable ancestors rather than bypassing the hosted-terminal guard.

Source development uses the same daemon commands:

# Run from source
node vis_bridge.js start

# Build and run the single-file executable
pnpm bridge:build
./dist-bridge/vis_bridge start

vis_bridge automatically adopts or starts the default OpenCode and Codex services. Among ACP agents, Kimi Code, Oh My Pi, and Pi are enabled by default; others can be enabled under Status Monitor → ACP. Run vis_bridge --help for all options. When binding to a non-loopback host, a bridge token is required for the PTY, filesystem, command, supervisor, ACP, and Codex proxy surfaces. Daemon state and logs are stored per user (Linux: ~/.local/state/vis/bridge; macOS: ~/Library/Application Support/vis/bridge; Windows: %LOCALAPPDATA%\vis\bridge). Secrets passed directly through --bridge-token or --upstream-token are removed from the daemon command line and state; use environment variables or token files when unattended restart is required. --target must be a ws:// or wss:// URL without userinfo, query parameters, or fragments; use the dedicated token options for upstream authentication. On macOS, run vis_bridge stop before manually removing /usr/local/bin/vis_bridge.

Using Codex Panel

Go to Vis "Settings"
Enable "Codex Panel" in the "Experimental Features" section
A Codex Panel button will appear in the top-right corner
Click the button and connect to vis_bridge to interact with Codex Panel

⚠️ Note: Codex Panel is currently in Alpha and features may be unstable. Requires a valid OpenAI API key and Codex CLI permissions.

Forge Panel Usage

Forge Panel is a lightweight zsh PTY floating window that runs the local Forge CLI directly. xterm.js renders realtime output as-is; the panel does not depend on terminal text recognition.

Prerequisites

Install and configure Forge so the forge command is available from a login zsh. To use the : shortcuts, run Forge's setup flow first:

forge setup

Using Forge Panel

Go to Vis Settings → Experimental Features and enable Forge Panel Button
Click the Forge button to the right of the management-mode button to open a zsh PTY floating window
The top menus run configuration, temporary-setting, workspace, and conversation commands; the status menu provides :info, :tools, :skill, and :workspace-info
Use the bottom prompt bar to choose Forge, Muse, Sage, Suggest, or Commit Preview, then send the prompt to the PTY
The structured right rail reads Forge status, conversation lists, and previews through the Forge CLI; it also provides :new, :clone, :conversation, :conversation-rename, :conversation-tree, and :delete

Drag the sidebar to resize it. Dragging it right past the hide threshold collapses it; drag the hidden rail left to restore it. Conversation commands adapt between 6×1, 3×2, and 2×3 layouts as the sidebar width changes. After a page refresh, the Forge PTY is restored as the complete Forge Panel rather than a plain terminal.

⚠️ Note: Forge Panel is currently Beta. Structured reads use Forge data from the active working directory; realtime interaction always remains in the PTY terminal.

Snippets Usage

Snippets save reusable prompt templates that expand from triggers in the composer.

Go to Vis Settings → Snippets and make sure Enable snippets is on
Create a snippet with a trigger, body, and optional tags for filtering; changes save automatically
A plain trigger expands as \name; include punctuation such as ::name or ;name for a custom prefix
The body supports dynamic variables: {date}, {time}, {datetime}, {uuid}, {clipboard}, {activeFile}, {cwd}, {selection}, plus {cursor} to place the caret after expansion
Type a trigger in the composer and pick its completion or press Enter to expand; Space and Tab keep their normal behavior
Favorited messages can be turned into snippets via Create snippet from favorite; snippets export and import as JSON files

Development & Building

Web Development

pnpm install
pnpm dev

Electron Desktop App

This project supports packaging the Web UI as a native desktop application using Electron, supporting Windows, macOS, and Linux.

Desktop Features:

Standalone app window, no browser required, supports macOS hidden-inset title bar
Secure sandbox (contextIsolation + sandbox); external links open in system browser
Auto CORS handling in development mode for local debugging
Separate update checks for the app and vis_bridge: in-app download and install for Windows / Linux installed builds; on macOS, install the app manually from a DMG and vis_bridge from a PKG installer. Automatic checks and downloads are off by default and installing always asks for confirmation
Optional minimize-to-tray and close-to-tray (both off by default), with quit from the tray menu
Remote bridges keep their connected version display and must be updated on their own host; local installer updates are offered only for loopback connections
Desktop notifications when a session task completes, including while the window is visible and focused, with an optional system sound (off by default); macOS ad-hoc builds do not support native notifications and keep only the sound fallback
Native menus follow the app language and keep only Quit and Reload entries
Supports NSIS / AppImage / deb / dmg installers for each platform
Runtime baseline: Electron 43.4.1 (Chromium 150 / Node 24.18.1), Chromium sandbox always enabled

For details on in-app updates, tray behavior, and notification sounds, see docs/desktop-integration.md.

macOS Signing Status (Important): macOS builds are ad-hoc signed (no Developer ID, no assigned TeamIdentifier, no notarization; mac.identity: "-", mac.notarize: false). Both Intel and Apple Silicon artifacts have passed codesign --verify --deep --strict on macOS runners, with checks against the app bundles mounted from DMG and extracted from ZIP. Gatekeeper still shows the standard "cannot verify the developer" warning; right-click → Open is required. macOS Notifications are unavailable and notarization is not configured. These limits are accepted decisions for this release — see CHANGELOG.md.

# Desktop dev mode (hot reload)
pnpm electron:start

# Preview build (no installer)
pnpm electron:preview

# Full build (generate platform installers)
pnpm electron:build

Build artifacts are output to dist-electron/, including:

Windows: .exe (NSIS)
macOS: .dmg / .zip (Intel / Apple Silicon)
Linux: .AppImage / .deb

Disclaimer

This is a third-party Web UI for OpenCode. It was not developed by the OpenCode team and has no affiliation with them.

This project is built on top of xenodrive/vis. We thank the original authors for their excellent work.

License

MIT

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
.microscope		.microscope
.zread/wiki		.zread/wiki
app		app
bridge		bridge
build		build
docs		docs
electron		electron
scripts		scripts
.fallowrc.json		.fallowrc.json
.gitignore		.gitignore
.oxfmtrc.json		.oxfmtrc.json
.oxlintrc.json		.oxlintrc.json
CHANGELOG.md		CHANGELOG.md
DESIGN.md		DESIGN.md
README.md		README.md
RoadMap.md		RoadMap.md
artifact-budget.json		artifact-budget.json
electron-builder.yml		electron-builder.yml
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml
postcss.config.mjs		postcss.config.mjs
server.js		server.js
tsconfig.json		tsconfig.json
vis_bridge.d.ts		vis_bridge.d.ts
vis_bridge.js		vis_bridge.js
vite.config.ts		vite.config.ts

Latest commit

History

Folders and files

Repository files navigation

OpenCode Visualizer CN

简介

功能特性

上游原始功能（由 xenodrive/vis 提供）

本项目新增功能

技术栈

环境要求

快速开始

部署到 GitHub Pages

vis_bridge 使用说明

安装 Codex CLI

启动 vis_bridge

使用 Codex Panel

Forge Panel 使用说明

前置条件

使用 Forge Panel

代码片段（Snippets）使用说明

功能展示

1. 主界面与简体中文支持

2. 字体管理

3. 供应商与模型管理

4. 状态监控

5. 主题设置

6. 代码行评论

7. Session Pin

8. 批量管理

9. 悬浮窗与 Dock 栏

10. 编辑器打开

开发与构建

Web 开发

Electron 桌面端

声明

License

Introduction

Features

Original Features (from xenodrive/vis)

New Features in This Project

Tech Stack

Requirements

Quick Start

Deploying to GitHub Pages

vis_bridge Usage

Install Codex CLI

Start vis_bridge

Using Codex Panel

Forge Panel Usage

Prerequisites

Using Forge Panel

Snippets Usage

Development & Building

Web Development

Electron Desktop App

Disclaimer

License

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages