Agent Integrations (GXT wrapper)

OpenGantry is tool-agnostic and vendor-neutral — any agent that can run shell commands can participate in the GXT loop. Governance is local-first: missions, gates, and Gantry Git hook enforcement run in your repository, not through a hosted agent dashboard.

Audience: adopters wiring agents into their own repos. For contributing to OpenGantry itself, see docs/DEVELOPMENT.md.

Universal rule

1. Planner legislates a mission under .gitagent/missions/ (IDE chat: .gitagent/planner/MISSION-ARCHITECT.md — one copy-paste gantry legislate command).
2. Bootstrap mission-scoped runtime env before executor execution.
3. Append trace evidence to EXECUTOR_LOG.md.
4. Finish with gantry verify --mission <path> (full verify before merge / claiming done).

# Process-boundary wrap (subprocess executors — strongest TMVC trap)
gantry runtime exec --mission .gitagent/missions/MSN-0001.<slug>.yaml -- <your-agent-command>

# IDE terminal / manual shell (any tool)
source scripts/gxt-runtime-env.sh .gitagent/missions/MSN-0001.<slug>.yaml

# Orchestrator / CI JSON bootstrap
gantry runtime env --mission .gitagent/missions/MSN-0001.<slug>.yaml --json

On failure, read GXT_LAST_ERROR_FILE (from runtime env) for machine-oriented remediation. gxt_verify returns structured error_code, fix_hints, and next_actions for IDE agents. After gantry verify failures, consume gantry context-feed --json (or read .gitagent/tmp/NEXT_REMEDIATION.json directly) for the latest structured remediation snapshot — atomic swap writes; eventual consistency under concurrent repair loops. See .gitagent/planner/RUNTIME.md.

MCP tools (Cursor and other MCP clients)

Kernel library (v3.2.2+)

External runtimes (iii workers, daemons, custom middleware) can call OpenGantry in-process without deep-importing dist/cli/lib/*:

import {
  evaluateScope,
  verifyMission,
  mintVerdictToken,
  verifyVerdictToken,
} from "@jeger-ai/opengantry/kernel";

Breaking in v3.2.2: only . (CLI) and ./kernel resolve from the package. Migrate any deep imports before upgrading. Reference integration: examples/iii-integration/.

Enforcement boundary (where the cage is ironclad)

IDE agent file edits are not TMVC-trapped unless the tool runs inside runtime exec. Docs here optimize context injection and workflow — not generic “be careful” advice.

External IDE skills (edge quarantine)

Third-party agent skill packs (Cursor SKILL.md, community rule collections, dependency-aware generators) are local IDE preferences — not OpenGantry routing skills and not GXT law.

Zero-trust: Git cannot attest how a line was produced. All incoming diffs are validated the same way. Do not add subjective coding-style packs to AGENTS.md, .gitagent/, or gantry init templates.

Local wiring (adopters): copy tool-specific examples only on the developer machine — e.g. Cursor: .cursor/external-skills.local.mdc (see specimen .cursor/external-skills.local.example.mdc). Cline: .clinerules/*.local.md. Keep GXT pointer files (gxt.md, CLAUDE.md) linking canonical law only.

Optional [SKILL-EXEC] stamps: executors may append one-line context to EXECUTOR_LOG.md for human PR triage:

[SKILL-EXEC] skill_key=<provider::skill> tool=<tool_name> scope=<path_or_glob>

Missing stamps are not verify failures. Stamps are not cryptographic proof and must not replace mission trace PASS quotes.

Remote handoff (Planner push → remote agent)

Enterprise async pattern:

1. Planner (local): gantry legislate … --msn MSN-NNNN → tune mission → git commit -m "[MSN-NNNN] legislate …" (must modify mission file).
2. Planner push: pre-push runs gantry verify --mission … --pre-push — legislative stubs pass after git-proof only (placeholder trace_rows or empty).
3. Remote worker: source scripts/gxt-runtime-env.sh <mission> → execute → append gate output to EXECUTOR_LOG.md.
4. Verifier (before merge): full gantry verify --mission <path> (gate + trace).

Unlegislated mission files (no Planner [MSN-NNNN] stamp) still fail pre-push.

CI receipt ingestion (GitHub Actions)

M1 control-plane ingestion uses gantry verify --export to emit a hub envelope after verify completes (pass or fail). The workflow ingests the envelope before failing the job so failed gates still land in the ledger (ADR-0037).

Copy templates/.github/workflows/gxt-attest-ingest.yml to .github/workflows/ in your spoke repo.

Repository settings

Execution order (critical)

1. Checkout PR head with fetch-depth: 0 (git-proof + planner stamp need history).
2. Set runner-verified identity — never git log committer email:
   • GANTRY_SIGNER_PRINCIPAL=github:<user_id>:<login> from github.event.pull_request.user
   • GANTRY_SIGNER_PRINCIPAL_KIND=github_actor
   • GANTRY_BRANCH_NAME from github.event.pull_request.head.ref
3. gantry verify --mission … --ci --export envelope.json with continue-on-error: true
4. POST $PLANE_INGEST_URL/api/v1/attestations/ingest with Bearer token
5. Fail the job if verify failed (ingestion already recorded)

Local export (debug)

export GANTRY_ORG_ID=org-example
export GANTRY_ORG_PEPPER='<secret>'
gantry verify --mission .gitagent/missions/MSN-NNNN.<slug>.yaml --export /tmp/envelope.json

See opengantry-plane docs/DEPLOYMENT.md for plane provisioning.

Canonical context files

Point every tool at the same GXT law — do not duplicate prose:

gantry init scaffolds AGENTS.md, .gitagent/ARCHITECTURE.pointer.json (agent discovery for code layout), docs/ARCHITECTURE.md (default file target), selected IDE pointer files, runtime scripts, and composes docs/INTEGRATIONS.md (human adopter IDE setup — not LLM context) from shipped recipe fragments.

Shared session variables

Deprecated compat: scripts/gxt-cursor-env.sh sources gxt-runtime-env.sh with a stderr notice.

Closed-loop checklist (all tools)

1. gantry init + export GANTRY_PLANNER_EMAILS="$(git config user.email)" + gantry doctor
2. gantry legislate "<intent>" --msn MSN-NNNN --skill-key <key> → Planner [MSN-NNNN] commit
3. Bootstrap: source scripts/gxt-runtime-env.sh .gitagent/missions/<file>.yaml
4. Executor executes; append PASS quotes to EXECUTOR_LOG.md
5. gantry verify --mission .gitagent/missions/<file>.yaml
6. git push (pre-push uses --pre-push handoff semantics)

Diagnostic context feed (verify repair loops)

When gantry verify fails, OpenGantry writes a machine-readable snapshot to .gitagent/tmp/NEXT_REMEDIATION.json (gitignored). IDE wrappers and agent rules can read this before the next prompt cycle:

gantry context-feed --json    # latest failure payload (empty when none)
gantry context-feed --clear   # atomic tombstone clear after remediation

Writes use temp-file + rename swap to avoid read/write races during automated test-and-repair loops.

Compatibility matrix

Related tools (not duplicate matrix rows):

• Gemini Code Assist — VS Code/JetBrains plugin; use the same three canonical files; distinct from the Antigravity agent-first IDE.
• OpenAI Codex API (2021–2023) — deprecated code-completion API; not OpenAI Codex CLI (2025+ terminal/IDE agent documented above).

Vendor CLIs change; the wrap line and context files do not.

Per-tool closed loop

Cursor

• Context injection: .cursor/rules/opengantry-gxt-substrate.mdc (alwaysApply: true); .cursor/hooks.json — sessionStart mission scope + beforeShellExecution fallback guard.
• MCP bridge: .cursor/mcp.json — gantry mcp serve exposes gxt_* tools for zero-copy-paste legislation.
• Mission Architect: /gantry macro (do not use /plan — Cursor native Plan Mode); implicit activation when user asks to write/edit code with no pinned mission. Follow .gitagent/planner/MISSION-ARCHITECT.md.
• Two-step legislation (Yolo-safe): gxt_interrogate → operator answers in chat → gxt_draft_legislation (server recomputes gaps) → human chat approval → gxt_execute_legislation → Planner git commit → gxt_check_signature → gxt_pin_mission. gxt_start_orchestration halts with INTERROGATION_REQUIRED until interrogation is complete (see GXT_LAST_ERROR_FILE).
• Host tool policy: Cursor may require approval per tool call or auto-run all tools (“Yolo mode”). MCP draft/execute is the primary governance gate — not host settings alone.
• Session bootstrap:

scripts/gxt-pin-mission.sh .gitagent/missions/MSN-0001.<slug>.yaml   # once per feature
source scripts/gxt-runtime-env.sh   # integrated terminal (uses pinned mission)

• Enforcement: Advisory for Agent edits; MCP two-step gate for legislation; shell hook fallback for raw gantry legislate / law/manifest writes; use runtime exec for headless CLI/SDK runs.
• Gotcha: Enable hooks and MCP in Cursor Settings; restart if they do not load (Output → Hooks). Pin a mission before starting Agent work — unpinned sessions get a legislate reminder only.

Substrate lifecycle: After npm install @jeger-ai/opengantry@latest, run gantry upgrade → review .gitagent/.upgrade-tmp/ → Planner-commit the upgrade mission YAML → gantry upgrade --apply --mission …. MCP: gxt_upgrade_plan / gxt_upgrade_apply.

Headless:

gantry runtime exec --mission .gitagent/missions/MSN-0001.<slug>.yaml -- cursor agent "<task>"

Claude Code

• Context injection: Minimal CLAUDE.md pointing at AGENTS.md, RULES.md, MANIFEST.json (keep under ~200 lines).
• Session bootstrap (shell wrapper — no project hooks):

scripts/gxt-pin-mission.sh .gitagent/missions/MSN-0001.<slug>.yaml
scripts/gxt-shell-agent.sh claude .gitagent/missions/MSN-0001.<slug>.yaml
gantry runtime exec --mission .gitagent/missions/MSN-0001.<slug>.yaml -- claude "<task>"

• Enforcement: Advisory in interactive session; process-boundary when wrapped with runtime exec or gxt-shell-agent.sh.
• Gotcha: Claude Code does not execute project hook directories — use the shell wrapper. Link canonical files — do not copy full RULES into CLAUDE.md.

OpenAI Codex CLI

• Context injection: Root AGENTS.md (loaded automatically after gantry init). Optional .codex/config.toml for project defaults (sandbox, approval policy). Do not duplicate RULES/MANIFEST — link via AGENTS.md.
• Session bootstrap (shell wrapper — no project hooks):

scripts/gxt-pin-mission.sh .gitagent/missions/MSN-0001.<slug>.yaml
scripts/gxt-shell-agent.sh codex .gitagent/missions/MSN-0001.<slug>.yaml
# headless / CI:
gantry runtime exec --mission .gitagent/missions/MSN-0001.<slug>.yaml -- codex exec "<task>"

• Enforcement: Advisory in interactive TUI/IDE extension; process-boundary when wrapped with runtime exec or gxt-shell-agent.sh. Codex’s own sandbox is separate from GXT TMVC.
• Gotcha: Codex CLI does not scan project hook folders. Codex sandbox/approval settings govern Codex — not GXT forbidden zones.

OpenCode

• Context injection: Repo-root AGENTS.md (native after gantry init); optional:

{ "instructions": ["AGENTS.md", ".gitagent/planner/RULES.md"] }

• Session bootstrap (shell wrapper — no project hooks):

scripts/gxt-pin-mission.sh .gitagent/missions/MSN-0001.<slug>.yaml
scripts/gxt-shell-agent.sh opencode .gitagent/missions/MSN-0001.<slug>.yaml

• Enforcement: Advisory; opencode.json permissions are separate from GXT TMVC.
• Gotcha: OpenCode does not execute project hook directories. OpenCode prefers AGENTS.md over CLAUDE.md when both exist.

JetBrains Junie

• Context injection: .junie/AGENTS.md (same bullets as root AGENTS.md).
• Session bootstrap: IDE terminal → source scripts/gxt-runtime-env.sh <mission>.
• Enforcement: Advisory (guidelines); no process trap for in-IDE edits.
• Gotcha: Use .junie/AGENTS.md, not generic AI Assistant project rules, for Junie-specific loading.

Google Antigravity

• Context injection: Root AGENTS.md; optional .agent/rules/gxt.md with always_on pointing at canonical files.
• Session bootstrap: source scripts/gxt-runtime-env.sh <mission> or gantry runtime exec … -- <command>.
• Enforcement: Advisory for Editor/Manager views; process-boundary for wrapped CLI runs.
• Gotcha: Rules load order includes GEMINI.md → AGENTS.md → .agent/rules/ — keep GXT pointers in AGENTS.md.

Cline

• Context injection: .clinerules/gxt.md; root AGENTS.md appears in Rules panel.
• Session bootstrap: VS Code terminal → source scripts/gxt-runtime-env.sh <mission>.
• Enforcement: Advisory; toggle rules in Cline panel without deleting files.
• Gotcha: Cline also reads .cursorrules legacy paths — prefer .clinerules/gxt.md for GXT-specific policy.

Aider

• Context injection: .aider.conf.yml:

read:
  - AGENTS.md
  - .gitagent/planner/RULES.md
  - .gitagent/foreman/MANIFEST.json

• Session bootstrap:

gantry runtime exec --mission .gitagent/missions/MSN-0001.<slug>.yaml -- aider --message "<task>"

• Enforcement: Process-boundary when wrapped — strongest TMVC trap among common IDE-adjacent tools.
• Gotcha: Run from repo root; read: paths resolve from CWD.

OpenHands

• Context injection: .openhands/microagents/gxt.md pointing at canonical GXT files.
• Session bootstrap: source scripts/gxt-runtime-env.sh <mission> then run OpenHands against the repo.
• Enforcement: Advisory for in-IDE edits; process-boundary when wrapped with runtime exec.
• Gotcha: Keep microagent prose minimal — link AGENTS.md, do not duplicate RULES.

Troubleshooting

Mission git-proof details: .gitagent/missions/README.md.

Adopter bootstrap: docs/ADOPTION.md. Runtime contract: .gitagent/planner/RUNTIME.md.