recodeee · NagyVikt · Apr 29, 2026 · Apr 29, 2026
@@ -25,10 +25,11 @@ Package summary ([about_description.txt](./about_description.txt)): Guardian T-R
   <a href="#01--install-in-one-line">Install</a> ·
   <a href="#03--what-it-does">What it does</a> ·
   <a href="#04--daily-workflow">Workflow</a> ·
-  <a href="#05--what-gx-shows-first">gx status</a> ·
-  <a href="#07--commands">Commands</a> ·
-  <a href="#08--v6--v7-migration">Migration</a> ·
-  <a href="#10--companion-tools">Companions</a>
+  <a href="#05--dmux-style-multi-agent-cockpit">Cockpit</a> ·
+  <a href="#06--what-gx-shows-first">gx status</a> ·
+  <a href="#08--commands">Commands</a> ·
+  <a href="#09--v6--v7-migration">Migration</a> ·
+  <a href="#11--companion-tools">Companions</a>
 </p>
 
 ---
@@ -136,7 +137,29 @@ gx branch finish --branch "$(git rev-parse --abbrev-ref HEAD)" \
 
 ---
 
-## `05` &nbsp;What `gx` shows first
+## `05` &nbsp;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` &nbsp;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` &nbsp;How `AGENTS.md` is handled
+## `07` &nbsp;How `AGENTS.md` is handled
 
 > [!IMPORTANT]
 > **GitGuardex never overwrites your guidance.** Only content between
@@ -188,7 +211,7 @@ the compact layout everywhere.
 
 ---
 
-## `07` &nbsp;Commands
+## `08` &nbsp;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 "<task>" --agent codex` | Start an isolated Codex lane for a task. |
+| `gx agents start "<task>" --agent claude` | Start an isolated Claude Code lane for a task. |
+| `gx agents status` | Show repo agent service status. |
+| `gx agents files --branch <agent/...>` | List files changed by one agent lane. |
+| `gx agents diff --branch <agent/...>` | Show the diff for one agent lane. |
+| `gx agents finish --branch <agent/...>` | 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` &nbsp;v6 → v7 migration
+## `09` &nbsp;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` &nbsp;Known rough edges
+## `10` &nbsp;Known rough edges
 
 Being honest about where this still has issues:
 
@@ -317,7 +352,7 @@ Being honest about where this still has issues:
 
 ---
 
-## `10` &nbsp;Companion tools
+## `11` &nbsp;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`

@@ -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/<agent>/<task-slug>-<time>`
+branches.
+
+## Inspect running work
+
+Show agent service status:
+
+```bash
+gx agents status
+```
+
+List changed files for one lane:
+
+```bash
+gx agents files --branch agent/codex/fix-auth-tests-2026-04-29-21-30
+gx agents files --branch agent/codex/fix-auth-tests-2026-04-29-21-30 --json
+```
+
+Show one lane's diff against its recorded base branch:
+
+```bash
+gx agents diff --branch agent/codex/fix-auth-tests-2026-04-29-21-30
+gx agents diff --branch agent/codex/fix-auth-tests-2026-04-29-21-30 --json
+```
+
+Show files locked by one lane:
+
+```bash
+gx agents locks --branch agent/codex/fix-auth-tests-2026-04-29-21-30
+gx agents locks --branch agent/codex/fix-auth-tests-2026-04-29-21-30 --json
+```
+
+These inspection commands are lane-scoped. They require `--branch` so a
+human or cockpit pane must choose which sandbox to inspect.
+
+## Finish a lane
+
+Finish by branch:
+
+```bash
+gx agents finish --branch agent/codex/fix-auth-tests-2026-04-29-21-30 --base main
+```
+
+Finish by session id when a session record is available:
+
+```bash
+gx agents finish --session session-finish-1 --base main
+```
+
+`gx agents finish` delegates to the existing Guardex finish flow for the
+selected session branch. The normal finish path commits the sandbox,
+pushes the branch, opens or updates a PR, waits for merge when requested
+by finish flags, and prunes the worktree.
+
+For a PR-only handoff without waiting for merge:
+
+```bash
+gx agents finish \
+  --branch agent/codex/fix-auth-tests-2026-04-29-21-30 \
+  --no-wait-for-merge \
+  --no-cleanup
+```
+
+Use that only when the lane must remain open for review. The default
+team completion path should still end in merged PR evidence and worktree
+cleanup.
+
+## Safety model
+
+GitGuardex orchestration is built on the same safety model as the lower
+level branch workflow:
+
+- Isolated worktrees: each task runs in its own filesystem sandbox under
+  `.omx/agent-worktrees` or `.omc/agent-worktrees`.
+- File locks: `--claim <path>` claims files immediately after branch
+  creation, and `gx agents locks --branch <agent/...>` shows ownership.
+- Protected base branches: `main`, `dev`, and `master` stay protected by
+  hooks; agents work on `agent/*` branches instead.
+- PR-only finish: completed agent work flows through PR creation,
+  merge-state verification, and cleanup instead of direct base commits.
+
+The cockpit does not weaken these rules. It gives a control pane and
+shorter commands for the same guarded lifecycle.
+
+## Common flows
+
+Codex implementation lane:
+
+```bash
+gx cockpit --session guardex
+gx agents start "implement checkout retry" \
+  --agent codex \
+  --base main \
+  --claim src/checkout/retry.js \
+  --claim test/checkout-retry.test.js
+gx agents files --branch agent/codex/implement-checkout-retry-2026-04-29-21-30
+gx agents diff --branch agent/codex/implement-checkout-retry-2026-04-29-21-30
+gx agents finish --branch agent/codex/implement-checkout-retry-2026-04-29-21-30 --base main
+```
+
+Claude documentation lane:
+
+```bash
+gx cockpit --session guardex-docs --attach
+gx agents start "refresh onboarding docs" \
+  --agent claude \
+  --base main \
+  --claim README.md \
+  --claim docs/onboarding.md
+gx agents files --branch agent/claude/refresh-onboarding-docs-2026-04-29-21-31
+gx agents diff --branch agent/claude/refresh-onboarding-docs-2026-04-29-21-31
+gx agents finish --branch agent/claude/refresh-onboarding-docs-2026-04-29-21-31 --base main
+```
+
+## Migration note
+
+If you have used dmux-style terminal orchestration, treat GitGuardex as
+a guarded orchestration layer, not a terminal multiplexer clone. The
+cockpit helps you see and drive multiple agents, but the product
+boundary remains repo safety: isolated sandboxes, file ownership, base
+branch protection, and PR-only completion.