Using AgentDock
Fleet and live pane
Start and stop the orchestrator, watch slots, message workers, attach a terminal.
The Fleet page is where you watch and steer a project's agents: the Code Sentinel orchestrator and the worker slots it dispatches. Open it from Project → Fleet.
AgentDock drives the orchestrator; it does not replace it. It starts and stops the orchestrator's tmux session, observes what the plugin writes, and offers a few typed controls. It never dispatches a specific issue or picks a slot's model. The orchestrator decides that. See The orchestrator.
The Fleet screen
The page has three parts:
- Runner banner. Shown when the project's runner is offline, with the command to bring it back. Controls that need the runner say so.
- Orchestrator card. Status (
running,idle,absentorunknown), a badge for where the facts come from, and four facts: Base, Slots (occupied / max), Last round and Session. Below them, the effective Profile, Model and Permission mode, and the controls. - Slots table. One row per slot with its issue, status, last checkpoint, pull request with checks, and age. Filter by status or issue, and turn on Show ended to include finished slots.
The source badge tells you how much to trust the data. events means a plugin event arrived in the last 24 hours and facts come from events.jsonl. scraped means facts are parsed from the orchestrator's markdown boards, briefs and reply files, which works with older plugins but is less precise. both means some fields still come from scraping.
Start, stop and status
Operators of the project see three buttons: Start…, Stop and Refresh status. Viewers see only Refresh status. When Start or Stop is disabled, the reason is written under the buttons with a link to the fix.
Start
Start… opens a dialog:
| Field | Meaning |
|---|---|
| Command | start begins a new round. next picks up the next queued issue |
| Profile | The runtime profile the orchestrator runs under, read-only here. Change it in Settings → Orchestrator |
| Model | Model alias or id passed as --model. Default opus |
| Permission mode | auto (default), acceptEdits, manual (prompts) or bypassPermissions |
On the runner this creates a tmux session named agentdock-orch-<owner>-<repo> in the project root and launches the profile's binary with the profile's environment:
claude --remote-control <session> -n <session> --model opus \
--permission-mode auto "/code-sentinel:orchestrator start"The command is an argument list, never a shell string. manual is passed to the CLI as --permission-mode default. Workers that the orchestrator dispatches inherit its environment, including CLAUDE_CONFIG_DIR.
Start is refused, with a reason, when the runner is offline, no profile is set (on the project or in Orchestrator settings), the orchestrator is already running, the profile is a Codex profile, or a stop budget for the project is used up.
bypassPermissions lets the orchestrator and its workers run without asking before tool use. Only an admin can choose it, either in Settings → Orchestrator or as a Start override, and the choice is audited. An operator's Start may inherit it from the project settings, because an admin set it there.
The orchestrator runs on Claude profiles. Starting it with a Codex profile is refused with unsupported_runtime. Codex workers and a Codex orchestrator are planned (milestone M4) and not built.
Stop
Stop kills only the orchestrator's own tmux session. Workers keep running, and no worktree, branch or slot is touched. Start it again later and it picks the board up. Anything the orchestrator was in the middle of typing is lost.
Status
Refresh status asks the runner for tmux presence, the pane classification and the start time. It does not type anything into the session.
Slot statuses
A slot's status is derived from its session, pane, worktree and pull request.
| Status | Meaning |
|---|---|
dispatched | The orchestrator wrote a brief, the worker's session has not appeared yet |
running | The session is alive and the agent is working |
idle | The session is alive but the agent is not working |
prompt | The pane shows a dialog or permission prompt that waits on a person |
quota | The pane shows the usage limit banner |
stale | The session is gone but the branch has unmerged work |
ended | The session is gone and the PR merged or the worktree is gone |
prompt and quota also raise notifications (pane.prompt, quota.hit). See Notifications.
The slot sheet
Click a slot to open its sheet. It has two tabs.
Details shows:
- Status, Brief (the orchestrator's instructions to the worker), Branch and Worktree;
- Pull request with its checks;
- Owns and Never, the file fence the worker is held to;
- Checkpoints: each report the worker wrote to
.orchestrator-reply.md, with its summary; - Terminal (admins, see below) and Control (operators).
Pane shows the worker's terminal, live.
The live pane
The pane is read-only and available to every member of the project, viewers included.
- The runner captures the
cs-<slot>tmux pane once a second only while someone is watching, and stops within about two seconds after the last viewer leaves. - It sends only what changed. The first frame carries up to 2000 lines of history.
- When the session ends, the last frame stays on screen marked as ended.
- At most 10 pane subscriptions run per runner and 20 viewers per slot.
Pane frames pass through the API to your browser and are not written to any table or log. Only "started watching" and "stopped watching" are audited.
Before sending, the runner masks strings that look like secrets: GitHub tokens (ghp_…, gho_…, ghs_… and similar), sk-… keys, Slack xox… tokens, AWS AKIA… key ids and PEM private key blocks become •••. This is best-effort pattern matching. Treat the pane as sensitive anyway.
Message a worker
In the slot sheet's Control section, type into Message worker and click Send message. The runner:
- writes your text to
.orchestrator-msg.mdin the slot's worktree, headedFrom: <your email> via AgentDockand a timestamp; - types
Read ./.orchestrator-msg.md and reply into ./.orchestrator-reply.mdinto the worker's pane, then presses Enter as a separate call.
This is the same channel the orchestrator uses. The limit is 16 KB of UTF-8. If the worker's session is not live, the file is still written and waits for the worker to resume; the result says it was not delivered.
A message bypasses the orchestrator, which only learns what was said when it next reads the board. Use it to unblock a worker, not to redirect the plan. The full text is kept in the command log; the audit record stores only a hash of it.
Stop a slot
Stop slot kills the worker's tmux session only. The worktree, branch and commits are kept, and the orchestrator resumes or cleans up the slot on its next pass. There is no "stop all slots" button: stop the orchestrator, then stop slots one by one.
Every Start, Stop, Stop slot and message is recorded as a command run with its outcome, and audited with the actor.
Terminal attach
Admins can open a real terminal on a slot, on the orchestrator (from the orchestrator card) or on a running skill (from its run page). Click Attach.
- It opens read-only (
tmux attach-session -r), so you can watch without resizing the agent's window or typing into it. - Take control reopens it read-write, and a danger banner reads "Your keystrokes go to a live agent session". Release goes back to read-only, Detach closes it.
- Use it to answer a permission prompt or a trust dialog that a worker is stuck on.
Limits and safeguards:
| Rule | Value |
|---|---|
| Who | Admins only. Operators and viewers use the read-only pane |
| Idle timeout | 15 minutes (TERMINAL_IDLE_TIMEOUT_SEC, default 900) |
| Maximum attach | 4 hours (TERMINAL_MAX_DURATION_SEC, default 14400) |
| Concurrency | 2 attaches per runner, 1 read-write attach per target |
| Audit | terminal.attached and terminal.detached with reason, duration and byte counts |
| Recording | None. Input and output bytes are never stored |
When you detach, time out or lose the connection, only your tmux attach client exits. The agent's session keeps running.
The runner machine needs POSIX (macOS or Linux) and tmux 3.2 or newer. A runner that cannot attach reports terminal: false and the Attach button is hidden. To forbid attaches on a machine, add terminal.attach to disabledCommands in its runner.json. See Runner reference.