From bdf660a2e6bf8fae661fc100f71571fc4e91760e Mon Sep 17 00:00:00 2001 From: NagyVikt Date: Wed, 29 Apr 2026 22:04:28 +0200 Subject: [PATCH] Explain cockpit agent orchestration Document the dmux-style cockpit workflow so users can start, inspect, and finish guarded Codex and Claude lanes without bypassing GitGuardex safety. Constraint: README must stay concise; long command walkthroughs live in docs/agents-cockpit.md. Rejected: Add screenshots or binary assets | text docs cover the workflow and avoid repository weight. Confidence: high Scope-risk: narrow Tested: node --test test/agents-start-dry-run.test.js test/agents-inspect.test.js test/agents-finish.test.js test/cockpit-command.test.js test/metadata.test.js Not-tested: rendered README preview --- README.md | 55 +++++++++--- docs/agents-cockpit.md | 198 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 243 insertions(+), 10 deletions(-) create mode 100644 docs/agents-cockpit.md 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//-