Dock

Dock은 오른쪽 사이드바에 TUI 컨트롤을 추가할 수 있게 해줍니다. 각 컨트롤은 JSON에 정의된 명령이며 Ghostty 기반의 전용 터미널 섹션에 표시됩니다. 피드, 로그, 큐, git 상태, 개발 서버 또는 팀이 모든 워크스페이스 옆에 두고 싶은 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 터미널에서 실행할 명령입니다. 로그인 셸 안에서 시작됩니다.
`cwd`	선택적 작업 디렉터리입니다. 상대 경로는 프로젝트 설정에서는 프로젝트 루트에서, 전역 설정에서는 홈 디렉터리에서 해석됩니다.
`height`	포인트 단위의 선택적 터미널 높이입니다. height가 없는 컨트롤은 남은 공간을 나눠 씁니다.
`env`	해당 컨트롤에만 전달되는 선택적 환경 변수입니다.

팀과 공유하기

Dock은 명령이 저장소에 속할 때 소스 컨트롤로 공유하도록 설계되었습니다.

저장소 전용 컨트롤은 .cmux/dock.json에 넣고 파일을 커밋하세요.
개인 컨트롤은 특히 저장소 밖에서는 ~/.config/cmux/dock.json에 넣고, 이 파일은 공유 소스 관리에 포함하지 마세요.
dock.json에 시크릿을 넣지 마세요. 셸, 로컬 env 파일 또는 기존 개발 도구에서 시크릿을 읽으세요.

에이전트에게 설정 요청하기

코딩 에이전트가 Dock 컨트롤을 만들게 하려면 이 프롬프트를 사용하세요. 에이전트에게 `cmux docs dock`을 실행하고 프로젝트를 살펴본 뒤 추측하기 전에 질문하라고 지시합니다.

에이전트 프롬프트

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.