diff --git a/README.md b/README.md
index 0cd89b20..da64e784 100644
--- a/README.md
+++ b/README.md
@@ -25,10 +25,11 @@ Package summary ([about_description.txt](./about_description.txt)): Guardian T-R
Install ·
What it does ·
Workflow ·
- gx status ·
- Commands ·
- Migration ·
- Companions
+ Cockpit ·
+ gx status ·
+ Commands ·
+ Migration ·
+ Companions
---
@@ -136,7 +137,29 @@ gx branch finish --branch "$(git rev-parse --abbrev-ref HEAD)" \
---
-## `05` What `gx` shows first
+## `05` dmux-style multi-agent cockpit
+
+GitGuardex now has a dmux-style cockpit for starting, inspecting, and
+finishing isolated agent lanes from one terminal workspace. It is not a
+dmux clone: GitGuardex keeps safety as the core and adds orchestration
+on top of isolated worktrees, file locks, protected base branches, and
+PR-only finish.
+
+```bash
+gx cockpit
+gx agents start "fix auth tests" --agent codex --base main --claim test/auth.test.js
+gx agents start "update setup docs" --agent claude --base main --claim README.md
+gx agents status
+gx agents files --branch agent/codex/fix-auth-tests-2026-04-29-21-30
+gx agents diff --branch agent/claude/update-setup-docs-2026-04-29-21-31
+gx agents finish --branch agent/codex/fix-auth-tests-2026-04-29-21-30
+```
+
+Long-form guide: [docs/agents-cockpit.md](./docs/agents-cockpit.md).
+
+---
+
+## `06` What `gx` shows first
Before you branch, repair, or start agents, run plain `gx`. It gives you
a one-screen status for the CLI, global helpers, repo safety service,
@@ -171,7 +194,7 @@ the compact layout everywhere.
---
-## `06` How `AGENTS.md` is handled
+## `07` How `AGENTS.md` is handled
> [!IMPORTANT]
> **GitGuardex never overwrites your guidance.** Only content between
@@ -188,7 +211,7 @@ the compact layout everywhere.
---
-## `07` Commands
+## `08` Commands
### Core
@@ -210,6 +233,18 @@ the compact layout everywhere.
| `gx sync` | Sync current agent branch against base. |
| `gx release` | Update the GitHub release from README notes. |
+### Multi-agent cockpit
+
+| command | does |
+| --- | --- |
+| `gx cockpit` | Create or attach to a repo tmux cockpit session with a status pane. |
+| `gx agents start "" --agent codex` | Start an isolated Codex lane for a task. |
+| `gx agents start "" --agent claude` | Start an isolated Claude Code lane for a task. |
+| `gx agents status` | Show repo agent service status. |
+| `gx agents files --branch ` | List files changed by one agent lane. |
+| `gx agents diff --branch ` | Show the diff for one agent lane. |
+| `gx agents finish --branch ` | Finish one agent session through the existing PR flow. |
+
```bash
gx release # create/update the current GitHub release from README notes
```
@@ -228,7 +263,7 @@ gx protect reset # back to: dev · main · master
---
-## `08` v6 → v7 migration
+## `09` v6 → v7 migration
Five commands were consolidated into flags. Old names still work and
print a deprecation notice; they'll be removed in v8.
@@ -246,7 +281,7 @@ print a deprecation notice; they'll be removed in v8.
---
-## `09` Known rough edges
+## `10` Known rough edges
Being honest about where this still has issues:
@@ -317,7 +352,7 @@ Being honest about where this still has issues:
---
-## `10` Companion tools
+## `11` Companion tools
All optional — but if you're running many agents, you probably want them.
`gx status` auto-detects each one and reports it in the `Global services`
diff --git a/docs/agents-cockpit.md b/docs/agents-cockpit.md
new file mode 100644
index 00000000..31ddb872
--- /dev/null
+++ b/docs/agents-cockpit.md
@@ -0,0 +1,198 @@
+# dmux-style multi-agent cockpit
+
+GitGuardex cockpit gives one terminal workspace for launching and
+inspecting multiple guarded agent lanes. It borrows the practical shape
+of a dmux-style control surface, but it is not a dmux clone. GitGuardex
+keeps safety as the core and adds orchestration around the existing
+branch, worktree, lock, and PR finish model.
+
+## Mental model
+
+Each task gets its own `agent/*` branch and worktree. The cockpit and
+`gx agents ...` commands are control surfaces over those lanes:
+
+1. Start a lane with `gx agents start`.
+2. Inspect status, changed files, locks, and diffs.
+3. Let the agent work inside its sandbox.
+4. Finish through the PR-only merge and cleanup flow.
+
+The base checkout stays protected. Agents do not work directly on
+`main`, `dev`, or `master`.
+
+## Start the cockpit
+
+```bash
+gx cockpit
+```
+
+By default this creates or reuses a tmux session named `guardex` in the
+repo root and opens a control pane running:
+
+```bash
+gx agents status
+```
+
+Useful variants:
+
+```bash
+gx cockpit --session guardex-dev
+gx cockpit --session guardex-dev --attach
+gx cockpit --target /path/to/repo
+```
+
+`gx cockpit` requires tmux. If tmux is missing, GitGuardex exits with a
+clear install-and-retry error instead of falling back to a half-working
+session.
+
+## Start agent lanes
+
+Start Codex:
+
+```bash
+gx agents start "fix auth tests" \
+ --agent codex \
+ --base main \
+ --claim test/auth.test.js \
+ --claim src/auth/session.js
+```
+
+Start Claude Code:
+
+```bash
+gx agents start "update setup docs" \
+ --agent claude \
+ --base main \
+ --claim README.md \
+ --claim docs/agents-cockpit.md
+```
+
+Dry-run first when you want to see the branch, worktree, and launch
+command without creating anything:
+
+```bash
+gx agents start "fix auth tests" --agent codex --base main --dry-run
+gx agents start "update setup docs" --agent claude --base main --dry-run
+```
+
+Codex lanes use `.omx/agent-worktrees`. Claude lanes use
+`.omc/agent-worktrees`. Both produce `agent//-