cmux 详细介绍：开源项目架构、功能与实践指南

项目快照：manaflow-ai/cmux，约 27,256 个 Star，2,376 个 Fork；最新推送时间 2026-09-19T15:52:55Z。本文基于仓库公开资料撰写。

项目地址：https://github.com/manaflow-ai/cmux · https://cmux.com

项目速览（TL;DR）

cmux 是一个基于 Ghostty 的 macOS 原生终端应用，重点解决多工作区、分屏终端、AI 编程代理通知以及终端与浏览器协同操作的问题。根据 README，它使用 Swift 和 AppKit 构建，底层使用 libghostty 提供 GPU 加速渲染，并提供垂直标签、水平与垂直分屏、内置浏览器、SSH 工作区、Claude Code Teams 集成以及 CLI 和 socket API。

仓库当前默认分支为 main，GitHub 页面资料显示 Star 数为 27256、Fork 数为 2376，主要语言为 Swift。仓库页面的许可证元信息显示为 NOASSERTION，但仓库中的 LICENSE 文件明确写明，除文件级或随附声明另有说明外，项目材料采用 GPL-3.0-or-later；许可证边界应以仓库中的 LICENSE、第三方许可文件和文件级声明为准。

“A Ghostty-based macOS terminal with vertical tabs and notifications for AI coding agents”
来源：README

定位与目标用户

cmux 的定位不是单纯增加终端主题或快捷键，而是把多个终端会话、代码代理状态、项目上下文和浏览器操作放到同一个 macOS 应用中。它尤其关注同时运行多个 AI 编程代理时的注意力管理：代理需要人工确认时，窗格和标签会出现通知状态，用户可以从侧边栏集中查看待处理通知。

目标用户应当已经在 macOS 上使用 Ghostty 或类似终端工作流，并且需要长期维护多个项目、分支、远程会话或代理任务。对于只运行单个交互式 Shell、没有多窗格需求的用户，cmux 的工作区、通知和浏览器编排能力未必能带来相应收益。

适用的工作方式

• 同时运行多个代码仓库或多个 Git 分支，需要通过垂直标签和侧边栏区分工作区。
• 让 AI 编程代理执行较长任务，希望在代理需要关注时获得可见通知，而不必持续观察每个终端。
• 需要在终端旁打开项目文档、开发服务器或本地页面，并希望通过应用内浏览器进行分屏操作。
• 需要通过 SSH 进入远程机器，并将远程终端、远程网络中的浏览器页面和文件上传动作放到一个工作区内。

核心功能

cmux 的核心价值来自多个功能之间的联动：工作区负责组织会话，通知负责暴露状态，浏览器负责补足终端外的操作，CLI 与 socket API 则提供自动化入口。下面分别说明这些能力的触发条件、处理方式和依赖关系。

通知环与通知面板

当编码代理需要用户注意时，相关窗格会显示蓝色环，标签也会高亮。README 没有给出通知事件的完整协议、检测规则或可配置字段，因此不能据此推断具体代理命令、事件格式或超时策略。

侧边栏通知面板会集中展示待处理通知，并支持跳转到最近的未读通知。其输入是应用内部识别到的待处理状态，输出是窗格和标签上的视觉提示以及可导航的通知列表；详细的状态持久化方式和清除规则，官方仓库未提供该信息，建议以最新 README 和官方文档为准。

垂直标签、水平标签与分屏

侧边栏会展示 Git 分支、关联 Pull Request 的状态和编号、工作目录、监听端口以及最新通知文本。这些信息把终端会话的运行上下文直接放到工作区导航区域中，减少了仅依靠窗口标题区分任务的需要。

终端可以进行水平和垂直拆分。README 只明确说明了支持的布局能力，没有公开分屏数据结构、最大窗格数量或布局保存格式；因此，不能将该功能解读为存在固定的并发规模或性能保证。

内置浏览器

内置浏览器允许在终端旁分屏打开浏览内容，并提供可编程 API。README 说明该 API 是从 agent-browser 移植而来，但资料没有列出完整 API 签名、浏览器内核版本或支持的自动化动作清单。

浏览器窗格适合与终端任务形成对应关系，例如在一个项目工作区中同时保留 Shell、代码代理和项目页面。浏览器自动化依赖应用提供的脚本接口；若需要对网页执行会影响账号、数据或业务状态的操作，应先确认目标站点授权和组织内部规则。

浏览器数据导入

cmux 可以从 Chrome、Firefox、Arc 以及其他二十多个浏览器导入 Cookie、历史记录和会话，使浏览器窗格能够以已有登录状态启动。该能力的输入是本机浏览器数据，输出是 cmux 浏览器窗格可使用的浏览上下文。

资料没有说明导入范围是否可逐项选择、数据保存位置、加密方式、清理命令或跨用户迁移规则。由于 Cookie 和会话令牌属于敏感认证材料，启用前应检查本机访问权限、备份策略和组织的凭据管理要求。

SSH 工作区

执行 cmux ssh user@remote 会为远程机器创建一个工作区；通过 --command 可以在第一个远程终端中执行初始命令。README 还说明，浏览器窗格会通过远程网络路由，因此远程机器上的 localhost 可以在对应浏览器上下文中工作。

将图片拖入远程会话时，cmux 会通过 SCP 上传。这个行为的输入是本地拖入的图片和已建立的远程 SSH 会话，输出是远程机器上的上传文件；资料没有提供目标路径选择、覆盖策略、认证方式或主机密钥管理细节，使用时应以 SSH 客户端和官方文档的实际行为为准。

Claude Code Teams

执行 cmux claude-teams 可以启动 Claude Code 的 teammate mode。各个 teammate 会以原生分屏出现，并在侧边栏显示元数据和通知；README 明确指出这一工作流不需要 tmux。

该功能的依赖关系是 cmux 提供工作区与分屏承载，Claude Code 提供 teammate mode，通知机制负责暴露子任务状态。资料没有说明 Claude Code 的安装方法、版本要求、团队规模限制或 API 凭据配置，因此这些内容不能从仓库资料中补充推断。

自定义命令与程序化控制

项目支持通过项目级 cmux.json 定义自定义命令，并从命令面板启动。它还提供 CLI 和 socket API，用于创建工作区、拆分窗格、发送按键以及自动化浏览器。

这些能力适合将重复的项目启动流程变成可审查的命令入口，例如把项目工作区初始化、终端分屏和浏览器打开动作组合起来。README 没有给出 cmux.json 的完整字段表，也没有列出 socket 地址、认证方式或请求格式，不能在此虚构接口示例。

系统架构与关键模块

从公开资料可以确认，cmux 是 Swift 编写的 macOS 原生应用，采用 AppKit 而不是 Electron；终端渲染由 libghostty 支撑，外围功能则围绕工作区、标签、分屏、通知、浏览器和自动化接口组织。仓库没有提供足够资料证明存在固定的模块目录、进程拓扑或 IPC 消息定义，因此下面只描述已公开的边界。

原生应用层

Swift 和 AppKit 负责 macOS 应用的窗口、侧边栏、标签和原生交互。README 将其描述为 Native macOS app，并强调不是 Electron，但没有公布最低 macOS 版本、Xcode 版本、构建方案或签名流程；这些运行与开发要求，官方仓库未提供该信息，建议以最新 README 为准。

终端渲染层

cmux 基于 Ghostty，并通过 libghostty 实现 GPU 加速渲染。它还会读取用户现有的 ~/.config/ghostty/config，用于主题、字体和颜色配置，因此已有 Ghostty 配置可以成为终端外观的一部分。

“兼容 Ghostty 配置”不等于所有 Ghostty 配置项都已在 cmux 中验证兼容。README 只明确列出主题、字体和颜色读取能力，其他配置键的支持范围、冲突优先级和错误处理方式均未提供。

工作区与自动化层

工作区将终端窗格、浏览器窗格和侧边栏元数据组合起来。CLI 和 socket API 位于应用外部控制面，能够创建工作区、拆分窗格、发送按键和自动化浏览器；自定义命令则从项目配置和命令面板连接到这套控制能力。

仓库资料没有说明 CLI 是否通过单独守护进程工作，也没有说明 socket API 是否仅限本机。将其用于自动化前，应在实际版本中核对监听范围、权限控制和错误返回行为。

依赖与运行环境

明确可核查的运行环境是 macOS，因为 README 提供 macOS DMG 下载入口，项目描述也将其定义为 macOS terminal。Swift 是仓库主要语言，应用使用 AppKit 和 libghostty；官方资料未给出最低 macOS 版本、CPU 架构支持矩阵或最低内存要求。

仓库根目录的 package.json 表明，项目还包含 JavaScript、TypeScript 和 Web 相关工具链。该文件列出的运行依赖包括 React 19.2.3、React DOM 19.2.3、Solid 1.9.13、ProseMirror 相关包、@opentui/core、Vercel，以及开发依赖 Biome 2.5.0、esbuild 0.27.0、Tailwind CSS 4.3.0 和其 CLI。

快速开始

最快的验证路径是下载官方 DMG、在 macOS 中启动应用，再创建一个工作区或远程 SSH 工作区。README 提供了最新 DMG 下载地址，但没有给出命令行安装器、Homebrew 配方或从源码构建的完整步骤。

安装

使用浏览器打开 README 中提供的官方 DMG 地址，完成 macOS 应用安装。下载地址如下，实际版本由该地址对应的最新 release 决定；本文不虚构具体 release 版本号。

open "https://github.com/manaflow-ai/cmux/releases/latest/download/cmux-macos.dmg"

上面的命令使用 macOS 的 open 打开官方 DMG 下载地址。安装后从应用程序目录启动 cmux；官方仓库未提供应用包名称、安装路径或首次启动参数。

运行与验证

启动应用后，可以先创建本地终端工作区，观察侧边栏、垂直标签和分屏入口是否出现。若需要验证 README 明确记录的 SSH 工作区命令，可在已获授权的远程主机上执行以下命令。

cmux ssh user@remote

其中 user@remote 是 SSH 用户名和远程主机占位符，不是固定账号或固定域名。验证结果应包括：cmux 创建远程工作区，并在其中显示第一个远程终端；远程主机、账号和认证材料应由使用者自行提供，不要将真实凭据写入脚本或公开仓库。

最小功能闭环

1. 安装并启动 macOS DMG 中的 cmux 应用。
2. 创建本地终端工作区，确认侧边栏能够显示工作区与窗格。
3. 在已授权环境中执行 cmux ssh user@remote，确认远程工作区创建成功。
4. 在工作区内拆分终端，或从命令面板启动一个项目自定义命令，检查侧边栏中的目录、分支或通知信息。

如果本机没有可用的远程主机，也可以只完成前三步中的本地应用启动和本地工作区验证。README 没有提供专门的健康检查命令、版本查询命令或自动化测试命令，因此不能用未公开的 CLI 参数替代上述验证。

配置说明

已公开的配置入口主要分为 Ghostty 配置、项目自定义命令和 JavaScript 工具项目配置。能够确认的字段和默认值如下；对于没有在资料中出现的字段，统一标记为“未提供”，不根据依赖名称推断其配置格式。

Ghostty 配置边界

cmux 会读取现有的 Ghostty 配置，用于主题、字体和颜色。资料没有说明是否支持通过 cmux 界面覆盖这些值，也没有列出配置解析失败时的错误表现，因此调整配置前应保留原文件副本，并以当前版本实际结果为准。

package.json 脚本

如果参与仓库开发，可以根据 package.json 中已公开的脚本运行检查或测试。下面的命令只调用资料中真实出现的脚本名称，不额外假定包管理器、依赖安装命令或 Swift 构建命令。

bun run agent-session-web:test
bun run biome:check

这些命令需要仓库现有开发环境和对应工具可用。package.json 没有列出 Bun 的版本、Swift 工具链版本或安装步骤，缺少这些条件时，官方仓库未提供该信息，建议以最新 README 和项目贡献文档为准。

进阶用法

进阶使用的重点是把工作区组织能力与项目自动化结合，而不是单独堆叠终端窗口。CLI、socket API、项目自定义命令和浏览器窗格可以形成可重复的开发入口，但具体组合应建立在已核对的接口文档之上。

使用初始远程命令

SSH 工作区支持在第一个远程终端启动时执行初始命令。README 给出的形式如下，示例中的命令和主机仍需替换为已授权环境中的实际值。

cmux ssh user@remote --command 'omp "investigate auth"'

user@remote 是远程连接目标，omp "investigate auth" 是 README 中给出的初始命令示例。资料没有解释 omp 属于哪一个外部程序，也没有说明其安装方式，因此不能把它列为 cmux 自带命令。

组织代理任务

对于 Claude Code Teams，可以使用 README 中的命令启动 teammate mode：

cmux claude-teams

该命令的实际前置条件是本机已经具备可运行 Claude Code 的环境，但仓库资料没有给出其安装步骤、认证方式或版本要求。使用时应把团队任务拆分、权限范围和代码写入目录限制在已授权项目中，并通过侧边栏通知确认子任务状态。

自定义命令的设计建议

项目自定义命令适合封装项目级重复操作，例如启动开发会话、打开相关页面或建立固定分屏布局。由于 README 没有提供 cmux.json 示例，不能给出未经验证的 JSON 字段；建议先查阅官方文档中的 Custom Commands 页面，再将命令提交到项目仓库进行代码审查。

可观测性与运维

cmux 面向交互式开发工作流，其公开可见的运行状态主要来自侧边栏元数据和通知系统，而不是 README 中定义的监控指标体系。当前资料没有提供日志目录、日志级别、指标端点、崩溃上报策略、健康检查接口或服务等级承诺。

运维排查可以从可见状态入手：检查工作区是否存在、窗格是否显示、侧边栏中的工作目录和分支是否正确、通知是否进入未读列表，以及远程浏览器是否能访问预期的 localhost。若问题涉及 socket API、浏览器会话导入或远程网络路由，应记录 cmux 版本、macOS 环境和可复现步骤，但不要在问题报告中上传 Cookie、SSH 私钥或业务数据。

项目的性能资料仅说明使用 GPU 加速渲染、原生 Swift 和 AppKit，README 未提供启动时间、内存占用、并发窗格数或渲染基准。任何性能结论都不应超出这些公开描述；根据本文作者的经验判断，实际资源占用应通过目标机器上的本地测试评估，而不是引用未发布的数字。

安全与合规边界

cmux 涉及 SSH 远程访问、浏览器 Cookie 和会话导入、网页自动化、AI 编程代理以及文件上传，因此安全边界取决于输入数据和执行目标。以下内容只适用于拥有明确授权的本机、远程主机、网站账号和代码仓库，不提供面向未授权目标的访问、攻击或绕过检测方法。

凭据与隐私

• 浏览器导入功能会处理 Cookie、历史记录和会话数据，使用前应确认导入范围、存储位置和访问权限。
• SSH 工作区涉及远程主机、主机密钥和认证材料；不要将私钥、口令或短期令牌写入 cmux.json、脚本或公开 issue。
• 拖拽图片到远程会话会触发 SCP 上传，上传前应确认目标路径、文件内容和远程主机归属。
• 浏览器自动化可能读取或提交账号可见的数据，运行自动化前应获得网站所有者或组织的授权。
• AI 编程代理可能读取项目文件并执行终端命令，应为代理配置最小必要目录和权限，并审查其生成的变更。

隔离与审计

README 没有说明 cmux 是否提供沙箱、容器隔离、浏览器站点白名单、socket API 认证或细粒度权限控制，因此不能把应用默认视为安全隔离边界。高敏感项目应在单独的 macOS 用户、测试仓库或组织批准的隔离环境中验证。

当项目需要满足隐私、数据驻留、审计或供应链要求时，应额外检查第三方依赖、第三方许可证、浏览器数据处理方式和代理服务条款。资料未提供合规认证、SLA、CVE 修复承诺或企业审计报告。

许可证与商用条款

LICENSE 文件写明，除文件或随附声明另有规定外，cmux 项目贡献材料采用 GNU General Public License version 3 or later，即 GPL-3.0-or-later。LICENSE 同时说明其他贡献者和第三方仍保留其材料的版权，具体文件可能受不同的许可和声明约束。

GPL-3.0-or-later 允许在许可条件下复制、修改、分发和使用软件，包括商业使用场景；但分发修改版本或组合产品时，必须遵守适用的 GPL 条款、版权声明、许可证文本、源代码提供义务及其他相关条件。这里的“可以商用”不等于可以删除版权声明、闭源分发受 GPL 约束的修改部分，具体义务应结合分发方式和组合组件判断。

LICENSE 还提到，Manaflow 可能仅针对其控制必要权利的材料另行提供商业条款；该等商业条款不会自动重新许可第三方材料或外部贡献。产品如果组合了 cmux 材料和第三方材料，仍需同时遵守适用的第三方许可和通知要求，具体以仓库的 THIRD_PARTY_LICENSES.md、文件级声明及 LICENSE 为准。

GitHub 元信息显示为 NOASSERTION，这与仓库 LICENSE 中的 GPL-3.0-or-later 文本并列存在。进行再分发、闭源集成或商业授权前，应以仓库 LICENSE 和相关文件级许可为准，并让具备资质的法律顾问审查具体方案。

局限性与已知限制

公开资料足以说明产品方向和主要能力，但不足以构成完整的工程规格。以下限制是资料缺失或功能边界的明确记录，不应扩展为对未公开行为的推断。

• 仅明确提供 macOS DMG 下载入口，未提供 Windows、Linux 或移动平台支持信息。
• 未提供最低 macOS 版本、CPU 架构矩阵、内存要求和性能基准。
• 未提供 CLI 全部命令、socket API 请求格式、认证模型和错误码。
• 未提供 cmux.json 的完整 schema、字段默认值和校验规则。
• 未提供通知事件来源、清除条件、持久化策略以及与具体 AI 编程代理的通用适配协议。
• 未提供浏览器导入的详细权限模型、数据落盘位置和清理流程。
• 未提供 SSH 认证配置、远程浏览器路由实现细节、SCP 目标路径规则和失败重试策略。
• 未提供 SLA、官方支持响应时间、长期维护承诺或安全漏洞响应流程。

适合谁 / 不适合谁

适合与否主要取决于工作流是否需要多会话组织和代理状态管理，而不是单看终端渲染能力。下面的判断信号可用于在引入前做小范围验证。

适合谁

• 每天需要同时维护多个 Git 分支、项目目录和终端会话，并希望通过侧边栏查看上下文。
• 使用 AI 编程代理处理耗时任务，需要蓝色通知环、标签高亮和通知面板提醒。
• 在 macOS 上已经使用 Ghostty 配置，希望继续复用主题、字体和颜色设置。
• 需要把终端、远程 SSH 会话、浏览器页面和本地开发端口放进同一个工作区。
• 愿意通过 CLI、socket API 或 cmux.json 将项目启动流程自动化，并能自行核对未公开细节。

不适合谁

• 主要工作环境不是 macOS，且要求项目提供 Windows 或 Linux 的官方运行方案。
• 只需要一个简单终端窗口，不使用分屏、垂直标签、通知或浏览器协同功能。
• 组织禁止桌面应用导入浏览器 Cookie、历史记录或会话数据，且没有替代认证流程。
• 需要公开、稳定且有完整版本承诺的自动化 API，但当前资料无法满足对 socket 协议、错误码或 SLA 的要求。
• 项目要求明确的企业支持、合规认证或已验证的高并发性能指标，而仓库资料没有提供这些承诺。

常见问题与排查（FAQ / Troubleshooting）

排查应优先区分安装问题、应用界面问题、远程连接问题和浏览器数据问题。资料没有提供统一诊断命令，因此以下方法以可观察现象和已公开命令为基础。

无法确认应用是否支持当前系统，怎么办

README 只提供 macOS 应用和 DMG 下载入口，没有列出最低 macOS 版本或 CPU 架构要求。应查看最新 release 说明和官方文档；若仍无明确答案，官方仓库未提供该信息，不应依据其他项目的系统要求进行推断。

SSH 工作区没有创建成功，怎么办

先确认命令格式为 cmux ssh user@remote，并检查目标主机、用户名、网络和 SSH 本身是否可用。不要在公开日志中粘贴私钥、口令或完整认证错误上下文；cmux 的具体错误输出、重试策略和认证参数未在资料中说明。

远程 localhost 无法在浏览器窗格访问，怎么办

README 说明浏览器窗格会通过远程网络路由，使 localhost 可以工作，但没有给出端口参数或诊断接口。应先确认服务确实运行在远程机器上，再确认访问地址使用的是远程服务实际监听的地址；若仍失败，查看当前版本文档和 issue 中的具体实现说明。

通知没有出现，怎么办

确认任务确实由 cmux 支持的工作区或代理流程启动，并检查窗格、标签和通知面板三个位置。通知触发事件、代理兼容范围和清除规则未在 README 中完整公开，因此不能通过未记录的环境变量或命令行参数强行启用。

为什么不能直接给出 cmux.json 示例

README 只确认存在项目级 cmux.json 和自定义命令功能，没有提供字段结构或示例文件。为避免写出无法验证的配置，实际使用应以官方 Custom Commands 文档和仓库当前版本样例为准。

项目地址与资源

以下链接均来自仓库资料或 README 中出现的官方站点，适合用于下载、查阅文档、了解项目动态和参与社区讨论。

• cmux GitHub 仓库
• cmux 官网与文档
• cmux 最新 macOS DMG 下载
• cmux Custom Commands 文档
• cmux Keyboard Shortcuts 文档
• The Zen of cmux 文章
• cmux Demo video
• cmux Discord 社区
• Manaflow 官方 X 账号
• agent-browser 项目