Dock

Dock 允许你向右侧边栏添加 TUI 控件。每个控件都是 JSON 中定义的命令，并在自己独立的 Ghostty 终端区域中渲染。可用于 feed、日志、队列、git 状态、开发服务器，或团队希望放在每个 workspace 旁边的任何 TUI。

配置

cmux 按以下顺序查找 Dock 配置：

.cmux/dock.json 用于当前仓库、最近的父项目以及嵌套项目目录。
~/.config/cmux/dock.json 用于你的个人默认 Dock，或没有仓库时使用。

如果项目配置和全局配置都存在，项目配置优先生效。嵌套项目配置适用于其目录树。如果没有项目配置，Dock 会使用全局配置。如果两个文件都不存在，Dock 会以空状态打开。

项目 Dock 配置可以启动命令。cmux 会在启动控件前要求你信任项目配置。

dock.json 示例

Dock 文件是一个包含 controls 数组的 JSON 对象。当你希望队友共享同一个 Dock 时，把项目控件提交到 .cmux/dock.json。请把示例命令替换为该仓库中实际存在的工具。

.cmux/dock.json

{
  "controls": [
    {
      "id": "git",
      "title": "Git",
      "command": "lazygit",
      "height": 300
    },
    {
      "id": "logs",
      "title": "Logs",
      "command": "tail -f ./logs/development.log",
      "cwd": "."
    },
    {
      "id": "feed",
      "title": "Feed",
      "command": "cmux feed tui --opentui",
      "height": 320
    }
  ]
}

字段

字段	说明
`id`	控件的稳定唯一标识符。保持简短，不要复用于其他命令。
`title`	显示在 Dock 标题栏中的标签。
`command`	在 Dock 终端中运行的命令。它会在你的登录 shell 中启动。
`cwd`	可选工作目录。项目配置中的相对路径从项目根目录解析，全局配置中的相对路径从主目录解析。
`height`	可选的终端请求高度，单位为点。没有 height 的控件共享剩余空间。
`env`	只传递给该控件的可选环境变量。

与团队共享

当命令属于仓库时，Dock 适合通过源代码管理共享。

将仓库专用控件放入 .cmux/dock.json 并提交该文件。
将个人控件放在 ~/.config/cmux/dock.json 中，尤其是在仓库之外使用时，并且不要把该文件加入共享的源码管理。
不要把密钥放入 dock.json。从 shell、本地 env 文件或现有开发工具中读取密钥。

让 agent 帮你设置

当你希望编码 agent 创建 Dock 控件时使用此提示。它会要求 agent 运行 `cmux docs dock`、检查项目，并在猜测前先提问。

Agent prompt

Set up cmux Dock controls for the current context.

First, learn the feature before editing:
1. Run `cmux docs dock` if the cmux CLI is available. If it is not, read https://cmux.com/docs/dock.
2. Inspect the repository or current directory to understand the project type, scripts, package manager, dev servers, logs, task runners, test commands, and any existing TUI tools.
3. If the desired Dock is ambiguous, ask the user what they want monitored or controlled before writing files.

Dock is cmux's right-sidebar terminal control area. A Dock config is JSON with a top-level `controls` array. Each control runs a command in its own Ghostty-backed terminal section using the user's login shell. Controls are useful for project dashboards, git/status views, dev server or build status, test watchers, log tails, queues, local services, or a custom TUI such as `cmux feed tui --opentui` when that feed is useful.

Choose where to write the config:
- In a repository or project directory, create or edit `.cmux/dock.json` so teammates can share it.
- For a personal default outside a repo, create or edit `~/.config/cmux/dock.json`.
- If both exist, project `.cmux/dock.json` is more specific for that project. Nested project configs apply to that directory tree; use the nearest relevant project config instead of writing unrelated controls globally.
- If there is no repo and no clear project root, use the global config only after confirming the user wants a personal Dock.

Schema:
{
  "controls": [
    {
      "id": "short-stable-id",
      "title": "Human label",
      "command": "safe command to run",
      "cwd": "optional/path",
      "height": 220,
      "env": { "NAME": "value" }
    }
  ]
}

Rules:
- Keep ids stable, lowercase, and unique.
- Use `cwd` for subdirectories; relative paths resolve from the config base.
- Use `height` only when a control needs a fixed amount of vertical space.
- Use `env` only for non-secret values needed by one control.
- Do not put secrets, tokens, or machine-specific private paths in a shared project config.
- Prefer commands that are safe to start repeatedly and make sense in a terminal.
- Do not invent unavailable scripts. Read package files, Makefiles, Procfiles, README docs, config files, and existing tooling first.
- Keep shared project Docks portable for teammates. Put personal or machine-specific controls in the global Dock.

Deliverable:
- Create or update the appropriate dock.json.
- Preserve existing useful controls unless the user asked to replace them.
- Validate that the JSON parses.
- Summarize what each control does and any commands the user should review before trusting the Dock config.