Skip to content

README.md

Latest commit

 

History

History
595 lines (417 loc) · 24.8 KB

README.md

File metadata and controls

595 lines (417 loc) · 24.8 KB
Raw

CodeMUX Logo

CodeMUX

一个把 AI 编码 CLI 变成桌面工作台的本地优先应用

在一个界面里管理 Claude Code / Codex / OpenCode / pi、多 Provider、MCP、Skills、Git Review、内置终端与内置浏览器，并可把任务派给 Agent 看板执行、用定时任务按时自动开工。

Version License Platform Electron 33 React 18 Rust

截图 • 当前亮点 • 快速开始 • 架构概览

CodeMUX 是什么

CodeMUX 是一个本地优先的桌面应用，由 Electron 桌面壳 + 独立 Rust daemon + React 渲染层 + Node.js sidecar 组成，目标不是做一个“再包一层聊天窗口”，而是把真实的 AI 编码工作流搬到一个更顺手的 GUI 里。

如果你平时在 Claude Code、Codex、OpenCode 这类 CLI 智能体上工作，通常会遇到这些问题：

  • 对话、工具调用、文件改动、终端输出分散在不同地方
  • 多 provider、多模型、多项目切换成本高
  • MCP、Skills、权限模式、历史会话都缺少统一管理入口
  • 想做代码审查或开一个项目终端，还要在应用外反复切换

CodeMUX 的做法是把这些环节收拢到一个桌面工作台里：会话、项目、Provider、Agent、MCP、Skills、Review、Terminal、Browser 都放在同一个界面中完成，还能派发工作任务与定时任务，让 Agent 在隔离分支上把活干完。

当前真正可用的核心运行时：

  • Claude Code
  • Codex
  • OpenCode（基于官方 @opencode-ai/sdk，可在运行时设置中按版本安装）
  • pi（基于 pi RPC 的极简多供应商运行时，经临时扩展支持审批与提问）

Gemini CLI 已完成接入位与 MCP 适配位，运行时仍处于预留阶段。

当前亮点

多套 Agent 运行时完整可用

  • Claude Code：基于官方 @anthropic-ai/claude-agent-sdk，可在运行时设置中选择版本安装
  • Codex：基于官方 codex app-server 子进程（stdio JSON-RPC 长连接），支持工具审批、Plan Mode 闭环与原生上下文压缩；第三方供应商经本地代理做协议翻译
  • OpenCode：基于官方 @opencode-ai/sdk，运行时同时安装 opencode-ai CLI，支持会话持久化与恢复、原生权限桥接、Plan/Build 双 Agent 切换、图片附件输入
  • pi：基于 pi RPC 的极简多供应商运行时，支持会话恢复、工具审批、AskUserQuestion 问答与 steer
  • 各 Agent 共用统一事件模型、工具卡片、权限审批 UI 和会话管理

权威 daemon 与可替换的桌面壳

  • 业务权威是独立的 Rust 进程 codemux-daemon：拥有 SQLite、会话、Agent 编排、Sidecar、MCP、Skills与定时任务，壳崩溃不影响权威
  • Electron 壳只做窗口、托盘、单实例、通知、自动更新与 Browser Host，并作为 supervisor 拉起/守护 daemon（版本配对仲裁）
  • 桌面 UI、浏览器/手机网页端与 CLI 都是 Daemon Client，统一走回环 Companion REST/WS + CodeMUX Event 协议，本机连接使用 Local Daemon Token
  • 前端只有一套产物：npm run build:web 产出 dist-web/，由 daemon 直接服务；同机浏览器走简化配对（壳内确认一次），手机/远程浏览器扫码配对后即可查看与驱动桌面会话；apps/cli 提供本机命令行客户端

面向真实编码流程，而不是单纯聊天

  • 项目分组 + 多会话管理
  • 流式对话、Thinking、Todo、工具调用卡片
  • 整轮 AI 输出折叠为「已处理 + 时长 + 步骤数」，可展开查看思考、读取、搜索、终端与子智能体的完整过程
  • 子智能体有独立时间线与实时预览面板
  • 变更文件预览、Diff 展示
  • 会话归档、置顶、重命名、恢复
  • 任意用户消息上可「回退」（只回对话 / 同时回滚文件 / 两者），也可从任意回复「分叉」出新会话
  • AskUserQuestion 交互卡片，支持选项选择与自由文本回答
  • 图片附件输入与预览；模型无视觉能力时可用兜底视觉模型解析后注入上下文
  • 流式生成时显示实时输出速度（xx.x tok/s）
  • 实时上下文使用进度，展示当前 token 占用与上下文窗口占比
  • 可导入 Claude Code / Codex / OpenCode 的外部 CLI 会话历史并归入对应项目

把 AI 工作流放进同一个桌面壳里

  • 内置 Review 面板查看 staged / unstaged 改动与 Diff
  • 内置 Terminal 面板在项目目录直接开 PTY 终端
  • 内置 浏览器 面板：沙箱 webview（独立 partition，可配 CDP），Agent 可被授权操作网页、选取网页元素加入对话
  • Git 分支管理：分支切换、新建分支、AI 辅助生成 Commit Message、Commit / Push 与创建 Pull Request
  • 右侧 Side Panel 支持多标签切换
  • 输入、代码审查、文件变更、终端、网页不用再来回切应用

工作任务看板：把任务交给 Agent 去跑

  • 四列看板：待办 / 进行中 / 等你处理 / 完成
  • 任务 = 标题 + 指令 + 项目 + Agent 与模型；启动后由 daemon 按项目配额排队，创建真实会话执行
  • 默认在 git worktree 隔离分支里干活，不污染当前工作区
  • 跑完进入「等你处理」，查看 Diff 统计后三选一：合并（可自定义提交信息）/ 直接完成 / 重新开始
  • 支持按项目筛选、列表 / 看板视图切换、归档与一键归档全部已完成

定时任务：按时自动开会话

  • 支持一次性、每日、每周、间隔等时点，到点自动新建会话并执行指令
  • 可绑定项目与 Agent，支持建议模板（如「每日提交简报」「每周回顾」「跟进监控」）
  • 每个任务有独立启停开关、立即执行、运行历史回看与时区显示
  • 仅在 CodeMUX 运行时触发（含托盘隐藏），不会补跑错过的任务

自定义快捷键

  • 内置 13 条命令（后退 / 前进、新建会话、打开设置、搜索、折叠侧边栏 / 侧面板、放大 / 缩小 / 恢复界面缩放、切换思考级别、停止生成、聚焦输入框）
  • 点键位即进入录制，拒绝无修饰键与系统保留键位，并检测键位冲突
  • 支持单项禁用、单项恢复默认与一键恢复全部默认
  • 键位按物理键匹配，与键盘布局无关；绑定存于 daemon 配置，所有客户端一致

多 Provider 与多模型管理

  • 「设置 → 模型配置」用一份统一的供应商列表管理多家上游，按名称搜索、逐个启停
  • 每个供应商可配置 API 密钥、Anthropic / OpenAI 兼容 / OpenAI Responses 三类端点与模型列表
  • 支持测试连通性、从接口拉取模型列表、添加 / 删除模型与 Token 单价
  • 支持 Codex 需要兼容代理 路由开关与 1M context 标记
  • 「设置 → 智能体运行时」为 Claude Code / Codex / OpenCode / pi 分别指定默认智能体、新建会话默认模型与默认权限
  • OpenCode 支持 @ai-sdk/openai、@ai-sdk/anthropic、@ai-sdk/openai-compatible、@ai-sdk/google、@ai-sdk/amazon-bedrock 等多 adapter
  • 运行时安装与升级都在设置内完成，不依赖系统全局 CLI；另有只读的「外部 CLI 诊断」

本地代理兼容 Codex

  • 内置本地代理路由
  • 用于兼容非原生 OpenAI Responses API 上游（Responses ↔ Chat 协议翻译）
  • 设置页可直接启动 / 停止
  • 状态栏可观察运行状态

MCP 与 Skills 都能在应用内统一管理

  • MCP 支持 stdio、http、sse
  • 支持 JSON 编辑、配置向导、探测、从本机工具导入
  • 内置 codemux-control MCP 承载浏览器与桌面两类工具（共 27 个），随「设置 → 浏览器控制」「电脑控制」两个开关增减，设置页直接显示当前可用工具数
  • 每个 MCP 可单独启用到 Claude Code / Codex / OpenCode / pi
  • Skills 以 ~/.codemux/skills/ 为单一数据源，Windows 下按 symlink → junction → copy 回退链处理
  • Skills 支持内置同步、预览、启用 / 禁用、卸载
  • 启用的 Skills 会自动注册到斜杠命令系统，每个 Skill 维护 4 个独立的 per-agent 启用开关

权限模式和计划模式是第一类能力

  • Claude、Codex、OpenCode 各自拥有独立的权限配置模型
  • 会话级保存权限配置和 plan mode
  • Codex 支持 sandbox / approval / network access 组合配置
  • Claude 支持不同 permission mode
  • OpenCode 保留原生权限语义，CodeMUX 负责展示、审批与响应转发，支持 once / always / reject 三档响应

使用统计与用量洞察

  • 365 天活跃热力图，按 token 消耗着色，悬停查看当日会话数与 token 明细
  • 每日 token 柱状图，分输入 / 缓存 / 输出堆叠展示
  • 按 Agent / 模型分布统计，支持时间窗口与 Agent 类型筛选
  • 概览卡片：会话总数、累计 token、缓存命中率

系统通知与提示音

  • 任务完成、需要权限审批、需要用户回答时自动触发系统通知
  • 应用非活跃状态下点击通知可唤醒主窗口（Windows 通过 Electron AppUserModelID + 单实例拦截实现）
  • 内置多种提示音（bell / chime / ding / success / task-complete），支持预览与切换

自动更新

  • 内置 electron-updater，启动时自动检查 GitHub Releases 最新版本
  • 支持用户确认后下载、退出时自动安装并重启
  • 侧边栏更新入口展示版本信息与进度

截图

新建会话与项目入口

新对话

主对话面板

对话面板

AI 过程与工具卡片

整轮 AI 输出可折叠为「已处理 + 时长 + 步骤数」，展开后是完整的思考、读取、搜索、终端与子智能体过程。

AI 过程与工具卡片

文件改动与 Diff

Diff 视图

内置浏览器

右侧面板内嵌沙箱浏览器，Agent 可被授权直接操作网页。

内置浏览器

工作任务看板

工单看板

定时任务

定时任务

模型与供应商配置

模型配置

MCP 管理

MCP 设置

Skills 管理

Skills 设置

自定义快捷键

快捷键设置

外观自定义

外观设置

适合谁

  • 经常用 Claude Code、Codex 或 OpenCode 做工程任务的开发者
  • 希望把多 provider、多项目、多会话统一管理的人
  • 想要可视化工具调用、Diff、终端与 Review 面板的人
  • 希望把 MCP / Skills 当作长期工作流能力来管理的重度用户
  • 关注 token 用量、成本与活跃度，想要长期统计洞察的人
  • 想把任务直接派给 Agent 在隔离分支上跑完、再统一验收合并的人

快速开始

环境要求

  • Node.js >= 18
  • Rust stable（编译 daemon）

Windows 通常还需要：

  • Visual Studio C++ Build Tools（Rust 工具链）

安装依赖

npm ci

cd apps/sidecar
npm ci
npm run build
cd ../..

npm run build:daemon

开发模式

npm run dev:desktop

一键启动：等 Vite（端口 1420）就绪后拉起 Electron 壳，daemon 由壳内 supervisor 自动拉起，退出时统一清理子进程。

如果只开发前端：

npm run dev

也可以分别手动跑 npm run dev（渲染层）与 npm run dev:electron（壳，需渲染层已在 1420 就绪）。

生产构建

npm run build:electron-installer

产物（NSIS 安装包 + latest.yml）输出到 apps/desktop/release/，详见桌面端发版指南。

常用检查命令

# 前端测试
npx vitest run

# sidecar 测试
cd apps/sidecar
npx vitest run

# Electron 壳类型检查
cd apps/desktop
npm run typecheck

# Rust（daemon crate）检查
cd crates/daemon
cargo check --all-targets --all-features
cargo fmt --all -- --check
cargo clippy --all-targets --all-features -- -D warnings

使用概览

1. 配置供应商

在「设置 → 模型配置」里维护一份统一的供应商列表，可新增、启停并搜索。每个供应商需要填写：

  • API 密钥
  • Anthropic / OpenAI 兼容 / OpenAI Responses 端点（按供应商实际协议填）
  • 模型列表（模型 ID 与显示名称，可从接口拉取）

如果目标上游不是原生 OpenAI Responses API，在该供应商上开启“Codex 需要兼容代理”。

2. 选择默认智能体

在「设置 → 智能体运行时」中为每个智能体选择默认模型与默认权限，并设定默认智能体。当前已可用运行时：

  • Claude Code
  • Codex
  • OpenCode
  • pi

同一页面还能安装 / 校验托管 Runtime、升级版本与回滚，并查看系统 PATH 上的外部 CLI 诊断。

2.1 启用内置浏览器（可选）

在「设置 → 浏览器控制」打开开关后，右侧面板会出现「浏览器」标签，同时内置的 codemux-control MCP 会注入浏览器类工具，会话即可直接操作网页。

3. 管理 MCP

在“MCP”设置中可以：

  • 新增 / 编辑 server
  • 使用向导生成配置
  • 对不同工具单独启用
  • 从本机已有工具配置导入
  • 执行连接探测

4. 管理 Skills

在“Skills”设置中可以：

  • 浏览并安装内置 Skills 与 GitHub Skills
  • 预览 Skill 内容
  • 为 Claude Code / Codex / OpenCode / pi 单独启用 / 禁用
  • 卸载已安装 Skills

Skills 以 ~/.codemux/skills/ 作为单一数据源；Windows 下按 symlink → junction → copy 回退链处理跨卷与权限问题。已启用的 Skills 会自动注册为斜杠命令。

5. 打开工作区侧边面板

进入项目会话后，可在右侧 Side Panel 打开：

  • 审查：查看并操作 Git 改动、切换分支、提交并推送，并可发起创建 Pull Request（GitHub / GitLab / Gitee）
  • 终端：在项目根目录打开内置终端
  • 浏览器：内嵌沙箱浏览器，可手动浏览，也可授权 Agent 接管操作网页

创建 Pull Request 的使用要求：

  • 当前分支必须是普通分支，并且相对 base 分支至少有一个已提交的 commit。
  • 工作区必须干净；未提交改动不会被自动 commit，需要先在审查面板提交。
  • GitHub 使用本机 gh 登录，GitLab 使用本机 glab 登录。
  • Gitee 需要在设置 → Git 中配置 Personal Access Token；Token 只保存到系统凭据存储。
  • 流程固定为检查、补全标题/正文、检查重复 PR、推送分支、创建 PR；推送或创建失败后可以安全重试。

6. 查看使用统计

在设置 → “使用统计”中可以：

  • 查看 365 天活跃热力图（按 token 消耗着色）
  • 切换时间窗口（7 / 30 / 90 / 365 天）与 Agent 类型筛选
  • 查看每日 token 堆叠柱状图与缓存命中率
  • 查看 Agent / 模型分布与累计会话数

7. 派发工作任务

在侧边栏的「工单」中新建任务，选择项目、Agent 与模型并写下指令即可启动。任务由 daemon 按项目配额排队，在隔离的 git worktree 分支里创建真实会话执行；完成后任务进入「等你处理」，可查看 Diff 统计并选择合并、标记完成或重新开始。

8. 配置定时任务

在侧边栏的「自动化」中按模板或从零创建定时任务，绑定项目与 Agent 后启用。到点会自动新建会话执行指令，并保留运行历史供回看。

9. 改键与外观

  • 「设置 → 快捷键」：点键位进入录制，可重绑、禁用或恢复默认
  • 「设置 → 外观」：主题、强调色、界面字体与字号、代码字号、圆角风格、幕布宽度、对比度

10. 从手机或另一台电脑继续

在同一局域网或远程环境下，用手机 / 浏览器扫码配对后即可查看并驱动桌面会话。配对使用 Pairing Token，业务权威始终在运行 CodeMUX 的那台机器上。

斜杠命令

所有会话都支持一组基础命令：

  • /new
  • /clear
  • /compact
  • /cost
  • /status

Claude 当前额外支持的常用命令包括：

  • /init
  • /review
  • /code-review
  • /security-review
  • /debug
  • /verify
  • /deep-research
  • /simplify
  • /batch
  • /loop
  • /run
  • /heapdump
  • /insights
  • /goal

Codex 当前额外支持：

  • /plan
  • /init
  • /review

OpenCode 通过 plan / build 双 Agent 切换支持计划模式，并在会话中复用上述通用命令与已注册 Skills 命令。

通用自定义命令：

  • /explain <文件路径>
  • /test
  • /fix [描述]
  • /refactor <目标>

已安装并启用的 Skills 也会注册为斜杠命令。

技术栈

层 技术
前端 React 18, TypeScript, Vite 6
UI Tailwind CSS v4, Radix UI, lucide-react, shadcn/ui
状态管理 Zustand
对话渲染 @assistant-ui/react, react-markdown, streamdown
代码 / Diff Monaco (@monaco-editor/react), diff, parse-diff, highlight.js
终端 @xterm/xterm, @xterm/addon-fit
桌面壳 Electron 33（窗口、托盘、单实例、通知、electron-updater、Browser Host）
后端 Rust 2021 daemon（codemux-daemon）: Tokio, Reqwest, Rusqlite，内嵌 Companion Server（回环 REST/WS）
客户端协议 Companion REST/WS + CodeMUX Event（桌面渲染层 / 浏览器与手机网页端 / CLI 共用）
本地数据库 SQLite
Sidecar Node.js + TypeScript
Agent SDK 由 CodeMUX 使用本机 npm 安装到托管 Runtime 目录：@anthropic-ai/claude-agent-sdk、@openai/codex（CLI，供 app-server 使用）、@opencode-ai/sdk
OpenCode AI Adapter @ai-sdk/openai, @ai-sdk/anthropic, @ai-sdk/openai-compatible, @ai-sdk/google, @ai-sdk/amazon-bedrock

配置与数据

应用主要数据保存在本地：

  • 会话 / 项目 / MCP / Skills 元数据：SQLite
  • 提供商、主题、默认智能体等：config.json
  • Claude Code 配置：~/.claude/settings.json（默认供应商直接复用，切换时自动备份）
  • Codex 配置：~/.codex/（保留登录与 vendor 信息）
  • OpenCode 配置：~/.config/opencode/opencode.json（默认不覆盖用户配置）
  • Skills 单一数据源：~/.codemux/skills/
  • 本机守护凭证（Local Daemon Token）与 daemon 运行状态（daemon-run-state.json）：应用数据目录（%APPDATA%/com.codemux.desktop 及平台等价目录）
  • Agent 原生历史：由各自运行时和 sidecar 管理

在设置 -> 常规中可以直接查看和打开配置目录。

架构概览

Rust daemon（codemux-daemon，权威进程）

  • 独立进程启动即监听回环，写 daemon-run-state.json（port / pid / version / managed_by）
  • 拥有 SQLite（会话 / 项目 / Timeline）、配置文件、Agent 编排、Sidecar 生命周期、MCP / Skills 适配、Provider Profile、Git、终端、文件系统与定时任务
  • 内嵌 Companion Server：回环 REST/WS + Local Daemon Token 鉴权，是唯一的客户端业务协议；局域网 / 中继暴露由用户显式开启
  • 广播 CodeMUX Event 与桌面 UI 事件（sessions-changed 等），并提供受控的浏览器自动化接缝

Electron 桌面壳（supervisor）

  • 承载窗口、托盘、单实例锁、原生对话框、通知（AppUserModelID）与 electron-updater
  • 按 supervisor 契约拉起 / 附着 / 重启 daemon（健康检查 + 版本配对仲裁），只管理自己拉起的 daemon
  • Browser Host：渲染层沙箱 <webview>（独立 partition，与应用 IPC 隔离），CDP 经 webContents.debugger 可用
  • 壳能力经 contextBridge（window.codemuxDesktop）暴露给渲染层；壳崩溃不影响 daemon

前端渲染层

  • React 渲染桌面 UI，Zustand 管理会话、设置、MCP、Skills、侧边面板等状态
  • 作为 Daemon Client 通过 Companion REST/WS 订阅 CodeMUX Event、驱动动作
  • @assistant-ui/react 作为对话运行时框架，自定义 Thread / Composer / Tool 卡片

Node.js sidecar

  • 封装 Claude Code、Codex、OpenCode 等 Agent 运行时
  • 处理会话启动、流式事件归一化、历史恢复、代理路由、权限桥接等逻辑
  • OpenCode 通过官方 SDK 启动独立 Server，建立 Client 与 Session，并通过 SSE 订阅事件

项目结构

codeMUX/
├─ src/                     # React 统一前端（桌面 UI、PC 浏览器、手机浏览器共用一套构建）
│  ├─ components/agent/     # 对话面板、工具卡片、权限卡片、上下文进度
│  ├─ components/settings/  # 设置页（Provider / MCP / Skills / 通知 / 使用统计 / 日志）
│  ├─ components/workspace/ # Review / Terminal / Browser 等侧边面板
│  ├─ components/automation/ # 定时任务面板与编辑器
│  ├─ components/worktask/  # 工作任务看板
│  ├─ stores/               # Zustand 状态（agent / session / mcp / skill 等）
│  └─ lib/                  # 工具函数（通知、权限、模型、上下文计算等）
├─ apps/
│  ├─ desktop/              # Electron 壳（main / preload / supervisor / Browser Host / updater）
│  ├─ sidecar/              # Node.js Agent Sidecar（Claude / Codex / OpenCode / pi 运行时）
│  └─ cli/                  # 本机命令行 Daemon Client
├─ crates/
│  └─ daemon/               # Rust daemon crate（Tauri 壳已移除，目录由 src-tauri/ 改名）
│     ├─ src/bin/           # codemux-daemon 入口
│     ├─ src/daemon/        # daemon 装配与生命周期
│     ├─ src/companion/     # Companion Server（REST/WS、鉴权、配对、浏览器自动化接缝）
│     ├─ src/agent/         # 会话生命周期、历史导入、Timeline 持久化
│     ├─ src/agent_runtime/ # Claude / Codex / OpenCode / pi 运行时抽象
│     ├─ src/mcp/ src/skills/  # MCP / Skills 各 Agent 适配器
│     ├─ src/model_providers/  # Model Provider 服务
│     └─ src/scheduled_tasks/  # 定时任务
├─ public/                  # 静态资源与截图
├─ scripts/                 # 开发 / 发布 / e2e / relay 脚本
├─ docs/                    # 设计文档、ADR 与实现说明
└─ README.md

更细的目录约定请参考 CONTRIBUTING.md 和仓库内的 AGENTS.md / 开发文档。

相关文档

当前状态

  • 架构：Electron 桌面壳 + 独立 Rust daemon（codemux-daemon），Tauri 壳已移除（daemon crate 位于 crates/daemon/，目录由 src-tauri/ 改名）
  • Claude Code：主力运行时，支持最完整
  • Codex：已集成并可用，包含本地代理兼容链路
  • OpenCode：已集成并可用，基于官方 @opencode-ai/sdk，从托管 Runtime 目录启动独立 Server
  • pi：已集成并可用，基于 pi RPC 的极简多供应商运行时
  • Gemini CLI：界面与适配位已预留，运行时待继续完善

许可证

本项目基于 MIT License 开源。

Made by kfumi