01  Install in one line

npm i -g @imdeadpool/guardex
cd /path/to/your-repo
gx setup   # hooks, state, OMX / OpenSpec / caveman wiring — one shot

[!WARNING] Not affiliated with OpenAI, Anthropic, or Codex. Not an official tool.

[!IMPORTANT] GitGuardex is still being tested in real multi-agent repos. If something feels rough — especially around cleanup, finish, merge, or recovery flows — sorry. We're patching as we find things.

[!CAUTION] Recommended default: macOS or Linux with Codex CLI. OMX is primarily designed and actively tuned for that path. Native Windows and Codex App are not the default experience, may break or behave inconsistently, and currently receive less support.

The problem

I was running ~30 Codex agents in parallel and hit a wall: they kept working on the same files at the same time — especially tests — and started overwriting or deleting each other's changes. More agents meant less forward progress, not more.

| before · parallel collisions | after · isolated lanes + file locks | | --- | --- | | codex-01 → src/auth/login.ts · ⚠ clash | codex-01 → agent/codex/login-refactor · ● owned | | codex-02 → src/auth/login.ts · ⚠ clash | codex-02 → agent/codex/login-tests · ● owned | | codex-03 → test/auth.spec.ts · ⚠ clash | codex-03 → agent/codex/session-guard · ● owned | | claude-a → test/auth.spec.ts · ⚠ clash | claude-a → agent/claude/token-rotation · ● owned | | codex-04 → src/auth/session.ts · ◌ stalled | human → main (protected) · ● clean |

Solution

03  What it does

• Isolated agent/* branch + worktree per task. Agents never share a working directory. Your visible local branch never changes mid-run.
• Explicit file lock claiming. An agent declares the files it's editing before it edits them. Claimed files can't be clobbered by another lane.
• Deletion guard. Claimed files can't be removed by another agent — no more ghost-deleted tests between runs.
• Protected-base safety. main, dev, master are blocked by default. Agents must go through PRs.
• Auto-merges agent configs. oh-my-codex, oh-my-claudecode, caveman mode, and OpenSpec all get applied automatically per worktree.
• Repair / doctor flow. When drift happens (and it will), gx doctor gets you back to a clean, verified state.
• Auto-finish on session exit. Codex exits → Guardex commits sandbox changes, syncs against base, retries once if base moved, and opens a PR.
• Monorepo + nested repos. Setup walks into every nested .git. Submodules and sandboxes are skipped automatically.

04  Daily workflow

Per new agent task — four steps, every time:

| 01 start isolated lane | 02 claim files | 03 implement + verify | 04 finish | | --- | --- | --- | --- | | Spawns agent/role/task branch + its own worktree. | Declare what you're touching. Other agents are blocked from these paths. | Run tests inside the sandbox — not against the live base branch. | Commit, push, open PR, wait for merge, prune the sandbox. |

# 1) start isolated branch/worktree
gx branch start "task-name" "agent-name"

# 2) claim the files you're going to touch
gx locks claim --branch "$(git rev-parse --abbrev-ref HEAD)" <file...>

# 3) implement + verify
npm test

# 4) finish — commit + push + PR + merge + cleanup
gx branch finish --branch "$(git rev-parse --abbrev-ref HEAD)" \
    --base main --via-pr --wait-for-merge --cleanup

[!TIP] Launching Codex through Guardex runs finish automatically when the session exits — auto-commits, retries once if the base moved mid-run, then pushes and opens the PR.

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.

gx cockpit
gx agents start "fix auth tests" --agent codex --base main --claim test/auth.test.js
gx agents start "fix auth tests" --panel --codex-accounts 3 --base main
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.

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, current repo path, and active branch.

$ gx

  ▮▮  gitguardex   v7.0.31
  ─────────────────────────────────────────────────────────────
  repo      /Users/you/code/your-repo
  branch    agent/codex/login-refactor  (sandbox of main)
  hooks     ● installed   pre-commit · pre-push · post-merge
  locks     ● 4 files claimed   by 3 agents
  service   ● running      review-bot · cleanup

  COMPANIONS
  ● oh-my-codex                    active
  ● oh-my-claude-sisyphus          active
  ● @fission-ai/openspec           active
  ● colony                         active
  ● cavekit                        optional · not installed
  ● gh                             authenticated

  NEXT   › gx branch start "task" "agent"
         › gx doctor   (if anything drifts)

Compact by default in a TTY. Pass --verbose for the full services list and grouped help tree, or set GUARDEX_COMPACT_STATUS=1 to force the compact layout everywhere.

07  How AGENTS.md is handled

[!IMPORTANT] GitGuardex never overwrites your guidance. Only content between these markers is managed: <!-- multiagent-safety:START --> … <!-- multiagent-safety:END -->. Everything outside that block is preserved byte-for-byte.

| Your repo has… | gx setup / gx doctor does… | | --- | --- | | AGENTS.md with markers | Refreshes only the managed block. | | AGENTS.md without markers | Appends the managed block to the end. | | No AGENTS.md | Creates it with the managed block, then links CLAUDE.md to it. | | No root CLAUDE.md | Creates a CLAUDE.md symlink to AGENTS.md. | | A root CLAUDE.md | Leaves it alone. |

08  Commands

Core

| command | does | | --- | --- | | gx status | Health check (the default when you type gx). | | gx status --strict | Exit non-zero on findings. | | gx setup | Full bootstrap. | | gx setup --repair | Repair only. | | gx setup --install-only | Scaffold templates, skip global installs. | | gx doctor | Repair + verify (auto-sandboxes on protected main). |

Lifecycle

| command | does | | --- | --- | | gx finish --all | Commit + PR + merge every ready agent/* branch. | | gx cleanup | Prune merged / stale branches and worktrees. | | 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. |

gx release  # create/update the current GitHub release from README notes

gx release is the maintainer path for package releases. It reads README.md, finds the last published GitHub release, and writes one grouped GitHub release body.

Protected branches

gx protect list
gx protect add release staging
gx protect remove release
gx protect set main release hotfix
gx protect reset   # back to: dev · main · master

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.

| v6 | v7 | | --- | --- | | gx init | gx setup | | gx install | gx setup --install-only | | gx fix | gx setup --repair | | gx scan | gx status --strict | | gx copy-prompt | gx prompt | | gx copy-commands | gx prompt --exec | | gx print-agents-snippet | gx prompt --snippet | | gx review | gx agents start |

10  Known rough edges

Being honest about where this still has issues:

• Usage limit mid-task. When an agent hits its Codex / Claude usage limit partway through, another agent may need to take over the same sandbox and run the remaining finish / cleanup steps.
• Conflict-stuck probes. Fixed in v7.0.2 — earlier versions could leak __source-probe-* worktrees when the sync-guard rebase hit conflicts.
• Windows. Most of the hook surface assumes a POSIX shell. Use WSL or symlink-enabled git.

Release notes

v7.0.42

• Bumped @imdeadpool/guardex from 7.0.41 to 7.0.42 so the current main payload can publish under a fresh npm version after 7.0.41 reached the registry.
• Improves the agent-session and cockpit workflow: gx agents start/status now share canonical session storage, agent lanes can be previewed, claimed, finished by session, and launched through safer supported-agent metadata, and cockpit can render live session state through tmux-backed panes.
• Hardens setup and status hygiene by ignoring local .codex/ state during setup/doctor, avoiding generic OpenSpec dirty-worktree reuse, and pruning stale agent sessions from user-facing status surfaces.

v7.0.41

• Bumped @imdeadpool/guardex from 7.0.40 to 7.0.41 so the current main payload can publish under a fresh npm version after the v7.0.40 GitHub release landed without a matching npm registry package.
• Ships the Colony companion setup as the default global companion surface: colony maps to @imdeadpool/colony-cli, README setup documents colony install --ide ..., and status tests/images expect Colony instead of cavemem.

v7.0.40

• Bumped @imdeadpool/guardex from 7.0.39 to 7.0.40 so the current main payload can publish under a fresh npm version after 7.0.39 reached the registry.
• No new CLI command behavior is introduced in this release lane.

v7.0.39

• Bumped @imdeadpool/guardex from 7.0.38 to 7.0.39 so the current main payload can publish under a fresh npm version after 7.0.38 reached the registry.
• No new CLI command behavior is introduced in this release lane.

v7.0.38

• Bumped @imdeadpool/guardex from 7.0.37 to 7.0.38 so the current main payload can publish under a fresh npm version after 7.0.37 reached the registry.
• No new CLI command behavior is introduced in this release lane.

v7.0.37

• Bumped @imdeadpool/guardex from 7.0.36 to 7.0.37 so the current package can publish under a fresh npm version after 7.0.36 reached the registry.
• Synced the shipped Active Agents template with the canonical VS Code extension source so Colony task counts and details install with the package.
• No new CLI command behavior is introduced in this release lane.

v7.0.36

• Bumped @imdeadpool/guardex from 7.0.35 to 7.0.36 so the latest branch-finish cwd-prune fix can ship under a fresh npm version after PR #424.
• No new CLI command surface is introduced in this release lane.

v7.0.35

• Bumped @imdeadpool/guardex from 7.0.34 to 7.0.35 so the current merged main payload can publish on a fresh npm version after PR #420.
• Refreshed README release/skills metadata and shipped Active Agents template parity so the current main payload passes release verification.
• No new CLI command behavior is introduced in this release lane.

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 block.

Install repo skills with npx skills add recodee/gitguardex; the npm package also ships the root skills/ catalog so the npx installer can read the GitGuardex skill from the published tarball. npx skills add recodee/ opens the recodee namespace. gx setup does not auto-run npx skills add .... If the picker does not show a separate guardex skill, that is expected.

| Tool | What it does | Stars | | --- | --- | --- | | oh-my-codex — npm i -g oh-my-codex | Codex config + skills framework. Merged into every agent worktree so each spawned Codex starts with the same tuned config. | | | oh-my-claudecode — npm i -g oh-my-claude-sisyphus@latest | Claude-side mirror of oh-my-codex. Skills, commands, and defaults for every Claude Code session. | | | OpenSpec — npm i -g @fission-ai/openspec | Structured plan / change / apply / archive flow so long agent runs don't drift off-task. | | | Colony — npm i -g @imdeadpool/colony-cli | Multi-agent task coordination and handoff routing. After install, register runtimes with colony install --ide codex, colony install --ide claude-code, colony install --ide cursor, colony install --ide gemini-cli, or colony install --ide opencode, then verify with colony status. | | | cavekit — npx skills add JuliusBrussee/cavekit | Spec-driven build loop with spec, build, check, caveman, backprop skills bundled in. | | | caveman — npx skills add JuliusBrussee/caveman | Ultra-compressed response mode for Claude / Codex. Less output-token churn on long reviews and debug loops. | | | codex-account-switcher — npm i -g @imdeadpool/codex-account-switcher | Multi-identity Codex account switcher. Auto-registers accounts on codex login; switch with one command. | | | GitHub CLI (gh) — see cli.github.com | Required for PR / merge automation. gx branch finish --via-pr --wait-for-merge depends on it. If ghx is on PATH, Guardex uses that GitHub CLI cache proxy automatically; set GUARDEX_GH_BIN=gh to force direct gh. | |