Get started

Step zero

Cage one agent run first

Start your agent inside the cage. While the session runs, it restores CI workflows, .env files, git hooks and git config as they change and refuses git pushes of them; lockfile changes are listed, not reverted. It restores rather than blocks, and doesn't restore git history. To cover your own paths too (tests, migrations, keys), run gantry cage suggest --write, review the proposal and commit it as .cage.yaml; it can only add protection.


            $
            npx @jeger-ai/opengantry-cage -- claude
          
            $
            npx @jeger-ai/opengantry-cage -- aider

When you want scope enforced during the run, signed task contracts and CI verification, continue below.

Install

Install the CLI

OpenGantry is a local CLI (gantry) — no hosted dashboard required. Use curl or PowerShell if Node.js is not on your PATH yet (they bootstrap Node 24 LTS). npm, pnpm, and bun need Node 24+ already installed. Cage an agent covers step zero only.

What do you want to install? Cage an agent Full CLI

Run the agent you already use inside the cage. It restores CI configs, .env files and git hooks/config while the session runs. No setup, no manifest. Needs Node 24+.


            $
            npx @jeger-ai/opengantry-cage -- claude


            $
            pnpm dlx @jeger-ai/opengantry-cage -- claude


            $
            npm install -g @jeger-ai/opengantry-cage
          
            $
            gantry-cage -- claude

Missions, gantry verify, MCP and hooks, with the cage included as gantry cage. curl and PowerShell bootstrap Node 24 if it is missing.


            $
            curl -fsSL https://opengantry.ai/install.sh | sh


            $
            powershell -c "irm https://opengantry.ai/install.ps1 | iex"


            $
            npm install -g @jeger-ai/opengantry


            $
            pnpm add -g @jeger-ai/opengantry


            $
            bun add -g @jeger-ai/opengantry

Confirm the binary and substrate readiness:


            $
            gantry --version
          
            $
            gantry doctor

Bootstrap

Bootstrap your repo

From your project root (empty repo or existing codebase), scaffold the GXT substrate. The tutorial walks the first change graph; headless CI uses gantry init --yes --no-ci.


            $
            gantry init --tutorial
          
            $
            git config core.hooksPath .githooks
          
            $
            gantry planner set "$(git config user.email)"
          
            $
            gantry doctor

gantry init writes the foreman map, planner rules, example mission, hooks, and integration stubs. gantry planner set allowlists your email for legislative commits. gantry doctor catches missing hooks, digest drift, and config issues before you legislate. After init, you can ask your agent to finish bootstrap from .gitagent/planner/AGENT-SETUP.md instead of running every command yourself.

`.gitagent/missions/`

Mission YAML — scope, gate_command, interrogation record

`.gitagent/foreman/MANIFEST.json`

Skill routing, TMVC roots, risk tiers

`.gitagent/planner/RULES.md`

Planner law and verification rules

`.githooks/`

Pre-commit and pre-push enforcement

`EXECUTOR_LOG.md`

Verbatim gate output quotes for verify

Roles

How OpenGantry is used

Every change follows the same contract: legislate scope → execute inside it across your orchestration graph → verify with structured output at each gate. The roles can be different people, workers, or agent passes — verify must not be the same actor who edited without trace evidence.

Every change is a small graph: legislate → commit → pin → execute → verify. One IDE session is a single-node graph; orchestration buses add parallel workers on the same mission YAML. Step 6 below (audit) is the reviewer grep after verify passes.

Planner

Legislates mission YAML — TMVC roots, forbidden zones, and gate_command. Commits with [MSN-XXXX] before any executor runs. Allowlisted via GANTRY_PLANNER_EMAILS.

Executor

Human or agent. Edits only inside the pinned mission scope. Appends verbatim PASS quotes from gate output to EXECUTOR_LOG.md — not summaries.

Verifier

gantry verify — separate from whoever edited. Runs gates, checks trace mapping, and emits pass or structured findings[]. Fail closed; no chat override.

Day-to-day: pin the active mission, run work, log PASS quotes, verify before push. Your existing CI gate becomes the gate_command — OpenGantry adds scope, trace, and machine-readable failures.


            $
            gantry pin .gitagent/missions/MSN-0042.ship-feature.yaml
          
            $
            eval "$(gantry runtime env)"
          
            $
            npm test
          
            $
            gantry verify --json

You do not need to type this sequence every time. With Cursor MCP ( gxt_pin_mission, gxt_verify, gxt_runtime_exec) or the setup skill, your agent can pin, run gates, append trace quotes, and verify after you approve the mission — same artifacts, less copy-paste. Point .cursor/mcp.json command at ./scripts/mcp-launcher.sh. That file is byte-identical for the OpenGantry specimen and for adopters. There is no mcp.json parity exemption. Do not point Cursor at a raw node binary. See the integration guide.

Walkthrough

Your first mission — step by step

What OpenGantry enforces on each change. Steps are for learning the chain — or delegate to your agent via MCP (gxt_*) or the setup skill after you approve scope.

Legislate scope and gates

Define TMVC roots and gate_command in mission YAML before any edits.

What your agent needs

Gather intent, MSN-NNNN, skill-key, and a real gate command (tests, lint, typecheck).
No application edits until step 2 — mission law must land in Git first.
MCP: gxt_start_orchestration or gxt_draft_legislation → human approves scope in chat.
Cursor .cursor/mcp.json command is ./scripts/mcp-launcher.sh. Specimen and adopter files are byte-identical. There is no mcp.json parity exemption.


            $
            gantry legislate "Fix login spinner loading state" --msn MSN-0001 --skill-key gantry --gate-command "npm test"

Confirm tmvc_roots in .gitagent/missions/MSN-0001.fix-login-spinner.yaml (e.g. src/features/auth/**). Interactive alternative: gantry start with the same MSN flags.

Planner commits the mission

Legislative authorization lives in Git, not chat.

What your agent needs

Planner-only commit: subject [MSN-XXXX], mission file in the diff.
git user.email must be in GANTRY_PLANNER_EMAILS.
MCP: gxt_execute_legislation after approval — then Planner git commit.


            $
            git add .gitagent/missions/
          
            $
            git commit -m "[MSN-0001] legislate fix login spinner"

Pin mission and load runtime

Set the active MSN for this session.

What your agent needs

Pin the exact mission file path; unpin when switching MSN.
Load runtime env (or use runtime exec) so TMVC and hooks apply to subprocesses.
MCP: gxt_pin_mission, gxt_runtime_env, or gxt_runtime_exec.


            $
            gantry pin .gitagent/missions/MSN-0001.fix-login-spinner.yaml
          
            $
            eval "$(gantry runtime env)"

Execute within scope

Edit inside TMVC; record verbatim gate output.

What your agent needs

Only touch paths in tmvc_roots; run gate_command locally.
Append verbatim PASS lines to EXECUTOR_LOG.md — summaries fail verify (Rule 4.4).
Commit EXECUTOR_LOG.md before claiming pass.


            $
            npm test

Example trace line:

PASS MSN-0001 DoD 1: npm test — 42 passing

Verify and read the verdict

Independent gate + trace check — fail closed.

What your agent needs

Run gantry verify or gxt_verify; use gantry context-feed --json for compact findings[] (offending_file, hint, gate_log_path).
After verify: run gantry report for a localhost triage dashboard — see what failed, whether ABORT tripped the repair loop, and open findings/gate logs without re-running gates.
Use gantry verify --json when you need the full debug envelope including stdout/stderr.
On failure: fix scope or trace, commit, re-run — chat cannot override verify.


            $
            gantry verify
          
            $
            gantry report
          
            $
            gantry context-feed --json
          
            $
            gantry verify --json

How to read the localhost dashboard: /features/#fail-closed.

Audit the chain

What a reviewer can grep without IDE chat.

What your agent needs

Bundle: legislation commit, mission YAML, EXECUTOR_LOG quotes, verify output.
gantry status --json for pin state and last errors.


            $
            git log --grep='MSN-0001' --oneline
          
            $
            gantry status --json
          
            $
            cat .gitagent/missions/MSN-0001.fix-login-spinner.yaml

Assessor detail: /audit/ and /docs/compliance-iso/.

Enterprise

Org policy, ledger, and cross-repo gates

Optional steps. The spoke still enforces; skip these for a single-repo start.

Pin an org policy repo

Tighten-only floor from a signed git bundle.

What your agent needs

Create a dedicated policy repo with ORG-POLICY.yaml (see examples/org-policy/).
Write .gitagent/foreman/POLICY.pointer.json and run gantry policy pull.
Doctor and verify stay offline after the pin.


            $
            gantry policy pull
          
            $
            gantry policy status --json

IDE

Wire your agent harness

gantry init scaffolds hooks, MCP (gxt_* tools), rules, and .gitagent/planner/AGENT-SETUP.md. Once wired, you describe intent in chat — the agent legislates, pins, runs gates, and verifies. You approve scope and Planner commits; you do not need to copy-paste every command from the step-by-step guide.


            $
            gantry doctor
          
            $
            gantry pin .gitagent/missions/MSN-0001.fix-login-spinner.yaml

Integration guide Cursor, Claude Code, headless runners, and CI handoff.

Optional

Discover before you legislate

Brownfield repo? Scan conventions first — discovery writes .gitagent/discovery-proposal.json with file:line evidence. Blueprint turns confirmed findings into TARGET_ARCHITECTURE.yaml and verification_plan.json. Nothing becomes law until you accept it.


            $
            gantry init --discover --domain code
          
            $
            gantry blueprint --domain code --yes


            $
            gantry init --discover --domain content
          
            $
            gantry blueprint --domain content --yes

5-minute kata Adoption runbook IDE integrations Domain adapters Agent graph Content governance example

GitHub · npm · First-5-minute kata

Cage one agent run first

Install the CLI

Bootstrap your repo

`.gitagent/missions/`

`.gitagent/foreman/MANIFEST.json`

`.gitagent/planner/RULES.md`

`.githooks/`

`EXECUTOR_LOG.md`

How OpenGantry is used

Planner

Executor

Verifier

Your first mission — step by step

Legislate scope and gates

Planner commits the mission

Pin mission and load runtime

Execute within scope

Verify and read the verdict

Audit the chain

Org policy, ledger, and cross-repo gates

Pin an org policy repo

Enable the compliance ledger

Wire cross-repo deps in CI

Wire your agent harness

Discover before you legislate

Next steps