Dock

Dock 可讓你將 TUI 控制項加入右側邊欄。每個控制項都是 JSON 中定義的命令，並會在自己的 Ghostty 終端區段中呈現。可用於 feed、日誌、佇列、git 狀態、開發伺服器，或團隊想放在每個 workspace 旁邊的任何 TUI。

設定

cmux 會依下列順序尋找 Dock 設定：

.cmux/dock.json 用於目前 repo、最近的上層專案，以及巢狀專案目錄。
~/.config/cmux/dock.json 用於你的個人預設 Dock，或沒有 repo 時使用。

如果專案設定和全域設定都存在，會以專案設定優先。巢狀專案設定會套用到其目錄樹。若沒有專案設定，Dock 會使用全域設定。若兩個檔案都不存在，Dock 會以空白狀態開啟。

專案 Dock 設定可以啟動命令。cmux 會在啟動控制項前要求你信任專案設定。

dock.json 範例

Dock 檔案是包含 controls 陣列的 JSON 物件。當你希望隊友共用同一個 Dock 時，請將專案控制項提交到 .cmux/dock.json。請把範例命令替換成此 repo 中實際存在的工具。

.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 終端中執行的命令。它會在你的 login shell 中啟動。
`cwd`	選用工作目錄。專案設定中的相對路徑會從專案根目錄解析，全域設定中的相對路徑會從家目錄解析。
`height`	選用的終端要求高度，單位為 points。沒有 height 的控制項會共用剩餘空間。
`env`	只傳遞給該控制項的選用環境變數。

與團隊分享

當命令屬於 repo 時，Dock 設計為可透過 source control 分享。

將 repo 專用控制項放入 .cmux/dock.json，並提交該檔案。
將個人控制項放在 ~/.config/cmux/dock.json，尤其是在 repo 外使用時，並且不要把該檔案加入共享的 source control。
不要將 secrets 放入 dock.json。請從 shell、本機 env 檔案或既有開發工具讀取 secrets。

請 agent 協助設定

當你希望 coding agent 建立 Dock 控制項時，請使用這段 prompt。它會要求 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.