@imdeadpool/guardex

guardian t-rex for multi-agent repos

Isolated worktrees, file locks, and PR-only merges for codex, claude, and human teammates working the same codebase at the same time.

Install · What it does · Workflow · gx status · Commands · Migration · Companions

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

_{THE PROMISE
"guard many agent. keep one repo clean."}

[!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.

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

06  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.
A root CLAUDE.md	Leaves it alone.

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

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

08  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

09  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.x

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.

10  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; 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.

_{— PRs and issues welcome · github.com/recodeee/gitguardex —}