@imdeadpool/guardex

GitGuardex

Safe parallel work for Codex, Claude, and humans.
One task → one worktree → one PR → one clean merge.

Install · Why · Capabilities · VS Code view · Workflow · Code assist · Commands

Install

npm i -g @imdeadpool/guardex
cd /path/to/your-repo
gx setup
gx onboard   # optional 2-minute tour

Requires Node.js 18+, Git, and GitHub CLI (gh). Recommended on macOS or Linux; use WSL on Windows.

[!WARNING] GitGuardex is an independent project. It is not affiliated with OpenAI, Anthropic, or Codex.

The problem

Parallel agents can edit the same files, overwrite tests, or commit directly to main. More agents can create more conflicts instead of more progress.

What GitGuardex can do

Isolate and coordinate	Ship with evidence	Recover without loss
One agent/* branch and worktree per task.	Preflight, CI, and optional AI review block risky merges.	Dirty, locked, blocked, and uncertain lanes are preserved.
Shared file claims prevent silent overwrites.	The recorded base keeps unattended finishes on the correct target.	Successful lanes are merged, then their temporary branch and worktree are removed.
Protected branches stay behind a PR boundary.	Billing-aware fallbacks waive only explicitly named checks.	Cleanup fails closed instead of deleting work it cannot prove safe.

Implementation evidence and shipped hardening

• Correct base targeting — persist and validate each lane's base so an unattended finish cannot use another checkout's target. (#745, #750, #751)
• Billing-aware CI fallback — waive only named checks that GitHub could not start because of billing, while keeping repository preflight mandatory. (#743)
• OpenSpec progress reconciliation — merge conflicting tasks.md progress deterministically and validate it before continuing. (#753)
• Reusable successful preflight — reuse proof only while the source HEAD, base commit, command, and script stay unchanged; billing-waiver preflights are never cached. (#757)
• Fail-closed cleanup — preserve dirty, locked, open-PR, blocked, or uncertain lanes; close idle clean worktrees without deleting their branches. (#741, #744, #746, #752)
• Workspace hygiene — safely remove successful detached lanes, avoid stale VS Code worktree providers, and keep gx branch finish --help free of repository side effects. (#742, #747, #748, #754)

See every lane in VS Code

Create an explicit multi-root workspace when you want every managed worktree to appear as its own Source Control repository:

gx setup --vscode-worktree-view
code ../<repo>-branches.code-workspace

The generated workspace enables Git subfolder discovery, worktree detection, and an empty repository-scan exclusion list. This is opt-in: GitGuardex does not rewrite your repository's .gitignore or loosen the default single-repository workspace. Disable future generation with --no-vscode-worktree-view.

Daily workflow

# 1. Start an isolated lane
gx branch start "fix-auth" "codex"

# 2. Inside the printed worktree, claim what you will edit
gx locks claim --branch "$(git branch --show-current)" src/auth.ts test/auth.test.ts

# 3. Implement and verify
npm test

# 4. Commit, open a PR, merge, and clean up
gx branch finish --via-pr --wait-for-merge --cleanup

For a small change that you already verified locally, use the explicit fast profile:

gx branch finish --fast

--fast still opens a PR and uses squash merge, but skips the local preflight, AI review, and review autofix. Repository branch protection and required CI checks still control whether GitHub accepts the merge. Do not use fast mode for security-sensitive, migration, dependency, or broad refactor changes.

Code-assist review gate

Add --gate-review to review the PR before merge. Add --gate-autofix to let the agent repair blocking findings and run the review again.

gx branch finish --via-pr --wait-for-merge --cleanup \
  --gate-review --gate-autofix

High and critical findings block the merge. The review is posted directly on the PR as a readable severity, location, and finding table.

_{Real example: Wireless_KFB_Project PR #165 · open the full-size screenshot}

Essential commands

Command	Purpose
gx / gx status	Show repo safety and the next action.
gx setup	Install or refresh Guardex in a repo.
gx doctor	Repair Guardex drift.
gx branch start "task" "agent"	Create an isolated task lane.
gx locks claim --branch <branch> <files...>	Claim files before editing.
gx branch finish --via-pr --wait-for-merge --cleanup	Ship safely through a PR.
gx branch finish --fast	Squash-merge a locally verified small change without local preflight or AI review.
gx agents status	Show active agent lanes.
gx agents send --session <id> --message <text>	Deliver safely to an idle agent or queue for its next turn.
gx agents inbox [--ack <message-id>]	Read or acknowledge the authenticated standalone message queue.
gx cleanup	Prune merged or stale worktrees.

Need the terminal cockpit? Run gx cockpit; see the cockpit guide. Run gx --help for every command.

Advanced setup and maintainer notes

AGENTS.md safety block

GitGuardex preserves your instructions. It only manages content between:

<!-- multiagent-safety:START -->
<!-- multiagent-safety:END -->

Agent skills

npx skills add recodee/gitguardex
npx skills add recodee/   # browse the namespace

gx setup does not auto-run npx skills add .... If the picker does not show a separate guardex skill, that is expected; use the gitguardex skill.

Package releases

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.

Release notes

v8.x

v8.4.0

• Added authenticated agent messaging that delivers live when safe and queues durably when Nodeterm or tmux delivery is unavailable.
• Added worktree-shared CLI and MCP inbox operations for reading and acknowledging queued agent messages.
• Improved stale Codex worktree recovery and VS Code visibility for managed worktrees.

v8.3.0

• Added adaptive direct-main agent work and branch-targeted gx sync.
• Made worktree cleanup safer by preserving active or locked lanes while pruning only eligible merged or opted-in clean lanes.
• Persisted and validated explicit finish bases, recognized SHA-256 null object IDs, and prevented stale VS Code worktree providers.

v8.2.0

• Reduced agent preflight and finish token overhead.
• Preserved dirty worktrees during stale-worktree cleanup and exposed command-specific cleanup help.
• Added the owning tmux pane and worktree to file-lock conflict output.

v8.1.1

• Prevented gx doctor from pruning dirty detached or managed worktrees during stale-worktree repair.

v8.1.0

• Added shared Git lock state so independent clones coordinate file ownership.
• Aligned npm repository metadata with opencue/gitguardex for trusted OIDC publishing.

v8.0.0

• Added gx branch finish --fast for small tasks that should use the PR + squash-merge path without repeating local preflight or opt-in AI review.
• Removed the legacy cr.yml AI-review workflow; repository policy and explicit Guardex review gates now control merge readiness.

v7.x

v7.1.1

• Bumped @imdeadpool/guardex from 7.1.0 to 7.1.1 so the current main payload can publish under a fresh npm version after 7.1.0 reached the registry.
• Direct maintainer npm publish now checks npm during prepublishOnly and bumps package release metadata to the next unpublished patch version when the committed version is already published. GitHub Actions release publishes keep the committed metadata so packed and signed assets stay aligned.

Issues · Contributing · Security