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.

---

02  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

---

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

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.

---

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.

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.
cavemem — npm i -g cavemem	Local persistent memory for agents via SQLite + MCP. Retains compressed history across runs.
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 —}