agents-shipgate
Health Pass
- License — License: Apache-2.0
- Description — Repository has a description
- Active repo — Last push 0 days ago
- Community trust — 16 GitHub stars
Code Pass
- Code scan — Scanned 12 files during light audit, no dangerous patterns found
Permissions Pass
- Permissions — No dangerous permissions requested
No AI report is available for this listing yet.
The deterministic merge gate for AI-generated agent capability changes — a local-first, static Tool-Use Readiness review for MCP, OpenAPI, and SDK tool surfaces. Open-source CLI + GitHub Action.
Agents Shipgate
Your coding agent changed what your AI agent can do — Agents Shipgate tells you whether it can merge.
The deterministic merge gate for AI-generated agent capability changes.
Local-first and static by default — no agent execution, tool calls, LLM calls, or network access.
60 seconds: watch it block two PRs
Claude Code adds stripe.create_refund to your support agent and opens a
PR. The diff looks fine to a human skimming it. Should it merge?
uvx agents-shipgate fixture run ai_generated_refund_pr
→ merge_verdict: blocked — the new refund capability has no declared
approval policy and no idempotency evidence. The verifier explains both
blockers and routes the PR to a human.
Now the move every reviewer fears — the agent deletes the Shipgate CI
gate to make its PR pass:
uvx agents-shipgate fixture run agent_weakens_gate
→ merge_verdict: blocked, can_merge_without_human: false. The
gate-removal checks are suppression-immune: the cheapest reward-hack is
also the most visible one.
One engine decides (report.json.release_decision.decision); everything
else — merge_verdict, PR comments, Check Runs, Action outputs — is a
deterministic projection of it. Five-minute version:docs/mental-model.md.
Agents Shipgate is an open-source CLI and GitHub Action for local-first,
static Tool-Use Readiness review. It scans MCP, OpenAPI, OpenAI Agents SDK,
Anthropic Messages API, Google ADK, LangChain/LangGraph, CrewAI, OpenAI API,
Codex repo config, Codex plugin, and n8n artifacts, then writes a deterministic Tool-Use
Readiness Report before your agent gets production-like permissions.
Within agent release readiness, Agents Shipgate's wedge is Tool-Use
Readiness: the tool surface, schemas, scopes, approval policies, idempotency,
and blast radius reviewed at PR time.
Website: threemoonslab.com —
quickstart,
glossary,
check catalog, and
design partners.
Static-by-default — no agent execution, no LLM calls, no MCP server connections,
no scanner network calls, no scanner telemetry. Audited exceptions are pinned
in tests/test_adapter_static_only.py::ALLOWED_EXCEPTIONS.
Apache-2.0.
What your PR sees
When a PR changes what your agent can do, the GitHub Action posts the merge
verdict as a PR comment. This is the comment for the first demo PR above —
the coding-agent diff that adds stripe.create_refund to a support agent
(abridged from the verbatim pr-comment.md artifact):
Agents Shipgate result: block
Decision:
block· Risk:critical· Required reviewers:agent-platform,security
Impact Change Subject Why blocks release action added stripe.create_refundCapability added. blocks release action broadened stripe.create_refundhigh-risk effect financial_action added blocks release scope broadened stripe.create_refund:stripe:*scope added Required before merge — Actor: Human (human authority required — a coding
agent must not self-resolve):
- Declare an approval policy for
stripe.create_refundor remove this tool
from the release.- Declare
approval.required,safeguards.audit_log, andsafeguards.idempotencyfor this financial write action.- Replace wildcard/admin scopes with operation-specific scopes.
Then re-verify:
agents-shipgate verify --base origin/main --head HEAD --json
The same uvx agents-shipgate fixture run ai_generated_refund_pr command
above writes this comment verbatim to reports/pr-comment.md.
Verify-first quickstart
The core loop is verify-first: when a PR changes what your agent can do, run the
deterministic verifier on the diff and read its merge verdict before you merge.
First ask whether Shipgate applies to the current repo or diff:
agents-shipgate verify --preview --json
If the repo is not configured yet, install the manifest, advisory CI, and
agent-facing instructions:
agents-shipgate init --workspace . --write --ci --agent-instructions=default --json
Prefer to delegate? Paste the
coding-agent snippet into Claude Code,
Codex, or Cursor and let the agent wire the gate itself — the repo shipsAGENTS.md managed blocks, llms.txt, and structured error output for
exactly this path.
Then verify the committed PR/CI ref. Pass the base and head so the diff — the
capability delta and trust-root signals — is in scope (the verifier never
fetches; make the base ref available first, e.g. git fetch origin main):
agents-shipgate verify --workspace . --config shipgate.yaml \
--ci-mode advisory --format json --base origin/main --head HEAD
For local, uncommitted work, omit --base/--head so your working-tree edits
are scanned instead:
agents-shipgate verify --workspace . --config shipgate.yaml \
--ci-mode advisory --format json
The release gate is agents-shipgate-reports/report.json →release_decision.decision (blocked | review_required | insufficient_evidence | passed).
The PR/controller surface is agents-shipgate-reports/verifier.json →merge_verdict (mergeable | human_review_required | insufficient_evidence | blocked | unknown), a deterministic projection of the release decision. Readverifier.json first for merge_verdict, can_merge_without_human,first_next_action, fix_task, and capability_review.top_changes.
Zero-setup demos of both verdicts are in
60 seconds above; uvx runs them with no
persistent install. To install the CLI, use pipx install agents-shipgate
(then pipx upgrade agents-shipgate — a plain install is a no-op over a stale
build). Your agent project does not need Python 3.12; the CLI installs
separately. To verify your own repo and write the standardagents-shipgate-reports/ directory, see Verify your repo
below.

How to read your first result
For PR verification, read verifier.json.merge_verdict first:
| Merge verdict | Meaning | Next step |
|---|---|---|
blocked |
Active, unaccepted blockers exist. | Fix blockers or remove the risky capability. |
insufficient_evidence |
Static evidence is too weak to gate release confidently. | Add better sources and rerun; do not auto-merge. |
human_review_required |
A person must review accepted debt, trust-root changes, or authority-bearing gaps. | Surface the required review; a coding agent must not self-approve it. |
mergeable |
No active blocker or review signal was found. | Keep verifier/report artifacts with the PR record. |
unknown |
Verify could not produce a reliable head scan or diff context. | Fix setup, fetch the base ref, or rerun with usable inputs. |
Then read report.json.release_decision.decision, the source-of-truth gate:
| Decision | Meaning | Next step |
|---|---|---|
blocked |
Active, unaccepted blockers exist. | Fix the blockers or remove the risky tool surface. |
insufficient_evidence |
The scan cannot confidently gate release from the available static evidence. This does not prove the agent is unsafe. | Provide clearer sources such as an MCP export, OpenAPI spec, explicit local tool inventory, or broader OpenAI SDK source path, then rerun. |
review_required |
Human review is needed, often for accepted debt or evidence gaps below the blocked threshold. | Review the listed items before promotion. |
passed |
No active blocker or review signal was found. | Keep the report artifact with the PR/release record. |
Common review signals include missing confirmation, missing idempotency
evidence, broad-scope permissions, prohibited-action policy gaps, and
trust-root changes such as weakened CI or manifest policy.
Not sure if Shipgate applies?
Run the zero-install detector from the repo you are reviewing. It is a
stdlib-only first touch for engineers and coding agents that need a yes/no
relevance signal before installing anything:
curl -sSL https://raw.githubusercontent.com/ThreeMoonsLab/agents-shipgate/main/tools/shipgate-detect.py \
| python3 - --workspace . --json
Continue to Verify your repo when the output hasis_agent_project: true, non-empty suggested_sources, non-emptycodex_plugin_candidates, or the workspace already has shipgate.yaml.
Sample reports
Open a report first if you want to see the output shape before installing:
| Sample | Markdown | JSON |
|---|---|---|
support_refund_agent |
report.md |
report.json |
simple_openai_api_agent |
report.md |
report.json |
simple_langchain_agent |
report.md |
report.json |
The support_refund_agent fixture also includes a reviewer-shaped Release
Evidence Packet in packet.md,packet.json, andpacket.html.
Copy this into your coding agent
Add a Tool-Use Readiness release gate for this tool-using AI agent with Agents Shipgate.
Run:
agents-shipgate verify --preview --json
If Shipgate is relevant, run:
agents-shipgate init --workspace . --write --ci --agent-instructions=default --json
agents-shipgate verify --workspace . --config shipgate.yaml \
--base origin/main --head HEAD --ci-mode advisory --format json
For local uncommitted work, omit `--base`/`--head`. For committed PR/CI refs,
make the base ref available first because `verify` never fetches. Read
`agents-shipgate-reports/verifier.json` first and lead with `merge_verdict`,
`can_merge_without_human`, `first_next_action`, `fix_task`, and
`capability_review.top_changes`, then read
`agents-shipgate-reports/report.json` for `release_decision.decision`. Do not
claim completion when `merge_verdict` is `blocked`, `insufficient_evidence`, or
`human_review_required` unless the user explicitly accepts human review. Do not auto-assert approval. Do not auto-assert confirmation, idempotency,
broad-scope safety, prohibited-action enforcement, runtime-trace proof,
suppressions, waivers, baselines, or policy weakening. Never remove Shipgate CI
or weaken agent instructions just to make the verifier pass.
Use with your coding agent
Claude Code — two commands wire the full surface:
pipx install agents-shipgate
agents-shipgate init --workspace . --write --claude-code
init --claude-code writes the CLAUDE.md managed block, the
auto-discoverable .claude/skills/agents-shipgate/ skill, and the Claude Code
hooks: a cheap trigger check after Edit|Write|MultiEdit and the full verifier
at Stop, so capability changes are re-checked before the agent reports work
complete — even on long sessions where instruction files lose attention. CI
stays authoritative; the hooks are the local feedback loop. Inside Claude Code,
agent mode auto-enables, so a zero-flag agents-shipgate verify prints the
compact agent result. Slash command, skill internals, and manual paths:docs/agents/use-with-claude-code.md.
Codex — install the skill-only plugin from this repo's marketplace, or
write the repo-scoped kit directly:
codex plugin marketplace add ThreeMoonsLab/agents-shipgate # plugin path
agents-shipgate init --workspace . --write --agent-instructions=agents-md,codex-skill # committed path
Then invoke $agents-shipgate in a fresh thread. The plugin supplies
workflows, not the scanner binary — install the CLI (pipx install agents-shipgate && pipx upgrade agents-shipgate) where Codex runs commands and
require >=0.13.0. Marketplace details, kit overrides, and the beta-migration
steps: docs/agents/use-with-codex.md.
Cursor — init --agent-instructions=cursor writes the auto-attach rule;
see docs/agents/use-with-cursor.md.
Who this is for
- Agent builders — review MCP, OpenAPI, and SDK tool definitions before merging changes that expand the tool surface.
- Platform teams — add release gates for approval, scope, idempotency, and baseline drift to PR review.
- Security and GRC reviewers — get static release evidence without running agents or importing user code.
Use this when
Run Agents Shipgate when a PR adds or changes agent tool surfaces or the policy
evidence around them:
- MCP exports, OpenAPI specs, or local tool inventories.
- OpenAI Agents SDK, Google ADK, LangChain/LangGraph, CrewAI, Anthropic
Messages API, or OpenAI API artifact tool definitions. - Codex repo config such as
.codex/config.tomlor.codex/hooks.json. - Prompts, permission scopes, approval policies, confirmation policies,
prohibited actions, orshipgate.yaml. - GitHub Actions or CI release gates for a tool-using AI agent.
Verify your repo
agents-shipgate verify --preview --json
agents-shipgate init --workspace . --write --ci --agent-instructions=default --json
# Replace any CHANGE_ME placeholders reported by init.
agents-shipgate verify --workspace . --config shipgate.yaml \
--base origin/main --head HEAD --ci-mode advisory --format json
For local uncommitted work, omit --base/--head. For committed PR/CI refs,
make the base ref available first because verify never fetches. Verify writesagents-shipgate-reports/verifier.json, pr-comment.md, the head capability
lock, and the normal report.{md,json,sarif} / packet artifacts when a scan is
required. If the base scan can be materialized, verify also writesbase.capabilities.lock.json plus capability-lock-diff.{json,md}, and the PR
comment includes a compact semantic capability diff summary. Lead withmerge_verdict, can_merge_without_human, first_next_action, and the capability diff orcapability_review.top_changes; use release_decision.decision as the release
gate.
Install alternatives (your agent project does not need Python 3.12 — install the CLI separately):
python -m pip install -U "agents-shipgate>=0.13" # global pip
uv tool install --upgrade agents-shipgate # via uv
agents-shipgate --version # require >=0.13.0
Adopt in one turn (scan helper)
The verifier-first loop above is the product entry path. For a scan-oriented
first adoption pass, agents-shipgate bootstrap runs all four steps in one
command, or run them individually:
agents-shipgate detect --json # 1. classify
agents-shipgate init --write --ci --json # 2. manifest + workflow
agents-shipgate scan -c shipgate.yaml --suggest-patches --format json # 3. scan + suggest
agents-shipgate apply-patches --from agents-shipgate-reports/report.json \
--confidence high --apply # 4. apply safe trivial fixes
apply-patches is dry-run by default and refuses to mutate anything outside
the manifest's directory. Agent-driven recipes:docs/agent-recipes.md; framework-by-framework
minimal manifests: docs/minimal-real-configs.md.
Use in CI
The public Action is listed on the
GitHub Action Marketplace.
Drop this full advisory workflow into .github/workflows/agents-shipgate.yml —
it runs on every PR, posts a summary comment, uploads artifacts, and never
fails the job (same file asexamples/github-actions/01-advisory-pr-comment.yml):
name: Agents Shipgate (advisory)
on:
pull_request:
permissions:
contents: read
pull-requests: write
jobs:
shipgate:
runs-on: ubuntu-latest
timeout-minutes: 10
steps:
- uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
with:
fetch-depth: 0
- uses: ThreeMoonsLab/[email protected]
with:
ci_mode: advisory
diff_base: target
check_annotations: 'true'
pr_comment: 'true'
The PR comment is fixed into a human summary plus agent instruction block, withmerge_verdict, the semantic capability diff when available, required next
action, and artifact links:

The action delegates to agents-shipgate verify and never fetches — keepfetch-depth: 0 on checkout. After adoption, choose an explicit merge policy:07-block-on-blocked-verdict.yml
blocks only when merge_verdict == blocked;08-require-mergeable.yml
requires can_merge_without_human == true;11-fail-on-insufficient-evidence.yml
fails only on insufficient_evidence. Strict / baseline / SARIF / Check Run /
multi-config recipes live inexamples/github-actions/; the full input and
output catalog is in action.yml. Use the decision output for
CI gating and merge_verdict / can_merge_without_human for PR-controller
routing.
CI is advisory by default. Strict mode exits 20 only on unsuppressed critical
findings; for existing projects, save a baseline first so strict CI fails only
on new findings:
agents-shipgate scan --config shipgate.yaml --ci-mode strict
agents-shipgate baseline save --config shipgate.yaml --out .agents-shipgate/baseline.json
agents-shipgate scan --config shipgate.yaml --baseline .agents-shipgate/baseline.json --ci-mode strict
Severity and failure thresholds are configurable in the manifest
(checks.severity_overrides, ci.fail_on) — seedocs/baseline.md anddocs/integrations.md for GitLab, CircleCI, Jenkins,
and pre-commit equivalents.
What it scans
| Input | Status |
|---|---|
| Model Context Protocol (MCP) exports | Supported |
| OpenAPI 3.x specs | Supported |
| OpenAI Agents SDK Python files/directories | Supported |
| Anthropic Messages API artifacts | Supported |
| Google ADK Python and YAML config | Supported |
| LangChain/LangGraph static Python inputs | Supported |
| CrewAI static Python inputs | Supported |
| n8n workflow JSON and source-control stubs | Supported |
| OpenAI API artifacts | Supported |
| Codex repo config | Supported |
| Codex plugin packages and marketplaces | Supported |
What it produces
When a PR changes what your agent can do, the verify loop writes these
artifacts — in read order:
agents-shipgate-reports/verifier.json— the primary, agent-facing artifact. A coding agent readsmerge_verdict(mergeable | human_review_required | insufficient_evidence | blocked | unknown),can_merge_without_human,first_next_action, andfix_taskto decide whether to continue, repair, or stop for a human. Seedocs/agent-contract-current.mdfor the field contract.agents-shipgate-reports/pr-comment.md— the human PR surface: the same verdict and semantic capability diff when available, shaped for a reviewer.agents-shipgate-reports/capabilities.lock.json+agents-shipgate-reports/base.capabilities.lock.json+agents-shipgate-reports/capability-lock-diff.{json,md}— the capability review primitive. Verify always emits the head lock after a successful scan; it emits the base lock and diff when the base scan can be materialized, falling back to the reviewed committed lock at.agents-shipgate/capabilities.lock.jsonif needed.- Gate source of truth —
report.json.release_decision.decision(passed | review_required | insufficient_evidence | blocked).merge_verdictis a deterministic projection of it; the report stays the one decision engine. - Tool-Use Readiness Report (supporting) —
agents-shipgate-reports/report.{md,json,sarif}. Markdown for human release review, JSON for tools and coding agents, SARIF for GitHub code-scanning workflows. This is the underlying check domain the verdict summarizes. - Release Evidence Packet (supporting) —
agents-shipgate-reports/packet.{md,json,html}(andpacket.pdfwith the[pdf]extras). Reviewer-shaped synthesis with fixed sections, including the compact evidence matrix plus tool-surface and action-surface diffs when available. Packet outputs are locally redacted by default; see STABILITY.md §Release Evidence Packet.
Exit codes
| Code | Meaning |
|---|---|
0 |
Pass (advisory mode or strict-no-blockers) |
2 |
Manifest config error |
3 |
Input parse error (file missing, malformed, path traversal blocked) |
4 |
Other Agents Shipgate error |
20 |
Strict-mode gate failure |
For coding agents
Human readers can skip this section; it exists so coding agents can find the
repo's machine-readable contracts quickly.
Agents Shipgate is designed to be agent-friendly. If you're a coding agent (Claude Code, Codex, Cursor, Aider) reading this repo:
llms.txt— short index of every machine-readable surface, one fetch.llms-full.txt— long-form concatenation ofAGENTS.md+ recipes + checks + concepts + autofix policy, in one document. Built byscripts/build-llms-full.py..well-known/agents-shipgate.json— discovery metadata (tagline, install commands, schema URLs, gating signal, exit codes, trigger-catalog URL).docs/triggers.json— machine-readable mirror of the AGENTS.md trigger table. Apply the rules to a PR diff to decide whether to proposeagents-shipgate detect. Schema is stable for0.x.tools/shipgate-detect.py— zero-install, stdlib-only detector.curl … | python3 - --workspace . --jsonreturns the same structural verdict asagents-shipgate detect --json. Pinned to the canonical CLI bytests/test_zero_install_detector.py. Seedocs/zero-install.md.agents-shipgate contract --json— verify the installed CLI's local contract before relying on hard-coded schema or gating assumptions.docs/agent-contract-current.md— single source of truth for the current schema versions and which JSON fields to read. Updated whenever the contract bumps; other agent-facing surfaces link here instead of restating the contract.docs/agent-native-merge-contract.md— the agent-native protocol map: the eight contracts (trigger, capability change, merge verdict, repair, forbidden action, human authority, trust root, attestation) each mapped to the artifact that implements it.docs/capability-standard.md— stable non-gating capability lock/diff standard for external integrations and research tooling.docs/product-hardening-gap-closure.md— closure map for root dogfooding, the governance case catalog, policy-pack tests, trace evidence, and runtime-inventory boundaries.benchmark/agent-pr-governance/+docs/governance-benchmark.md— stable research benchmark for unsafe-merge prevention, authority routing, and verifier explanation quality.AGENTS.md— canonical agent-facing instructions: install, run, common tasks, JSON-mode flags, error semanticsSTABILITY.md— what won't break across0.xversionsdocs/target-repo-agent-snippets.md— copyable snippets for adding Shipgate trigger rules to downstream agent reposdocs/agent-adoption-harness.md— manual protocol for checking whether coding agents discover and use Shipgatebenchmark/— frozen archetypes, prompts, setup variants, and a public leaderboard CSV. Closes the loop on adoption-readiness changes.docs/zero-install.md— single-file detector,uvx, and GitHub Action paths for evaluating Shipgate without a local install.prompts/— reusable prompts for common workflowsskills/agents-shipgate/+.claude/commands/shipgate.md— self-contained Claude Code skill (bundled prompts and CI recipe) and/shipgateslash command. Seedocs/agents/use-with-claude-code.mdto install in your own project.agents-shipgate install-hooks --target claude-code --write— deterministic Claude Code hooks: a PreToolUse trust-root guard, a cheap trigger check afterEdit|Write|MultiEdit, and a fullverifyatStop, so the gate runs even when instruction files lose attention on long sessions. Seedocs/agents/use-with-claude-code.md.agents-shipgate mcp-serve([mcp]extra) — read-only stdio MCP server exposingshipgate.check,shipgate.preflight,shipgate.explain, andshipgate.capabilitiesfor agents without comfortable shell access. It is static-only and not a general MCP permission broker. Seedocs/mcp-server.md.docs/ai-search-summary.md— human-readable summary for AI search, answer engines, and coding agentsdocs/manifest-v0.1.json+docs/report-schema.v0.26.json+docs/preflight-schema.v0.1.json— JSON Schemas for live editor validation and agent routing (current; emitted reports carryreport_schema_version: "0.26", preflight emitspreflight_schema_version: "0.1"). v0.26 adds structured evidence gaps (release_decision.evidence_coverage.evidence_gaps[]) plus the advisorysuggested-inventory.jsonskeleton; gate behavior is unchanged. Readrelease_decision.decisionfor release gating,agent_summary.first_recommended_actionfor the next agent step, andreviewer_summary.first_recommended_surfacefor the human-review entry point. The per-version additive history lives indocs/agent-contract-current.mdandSTABILITY.md.docs/capability-lock-schema.v0.2.json+docs/capability-lock-diff-schema.v0.3.json— stable schemas for the static capability envelope and semantic diff emitted byagents-shipgate capabilityand, in PR workflows, byagents-shipgate verify; non-gating and separate fromreport.json.docs/attestation-schema.v0.2.json— deterministic local attestation schema; v0.2 binds verifier artifacts plus capability lock/diff hashes when present.docs/governance-benchmark-catalog-schema.v0.2.json+docs/governance-benchmark-result-schema.v0.2.json— stable schemas for the research benchmark catalog and deterministic result artifact.docs/checks.json— machine-readable check catalog
Every command has a --json form. Errors emit a structured next_action line on stderr when agent mode is active — set AGENTS_SHIPGATE_AGENT_MODE=1, or rely on auto-detection inside a coding-agent harness (Claude Code exports CLAUDECODE=1, Cursor CURSOR_TRACE_ID). AGENTS_SHIPGATE_AGENT_MODE=0 forces it off.
Why this exists
Once an AI agent can refund, email, cancel, deploy, or modify a record, every tool change becomes a release event. Code review catches code; eval suites catch behavior; observability catches runtime. None of them answer the release question: given the tool surface declared in this PR, do we have explicit approval policies, scope coverage, idempotency evidence, and review readiness for every action?
Agents Shipgate produces a deterministic answer to that question, before promotion.
The current product promise is deliberately narrow: a deterministic, local-first,
static merge gate for AI-generated agent capability changes — the Tool-Use
Readiness review run at PR time. Broader lifecycle ideas are future roadmap
work, not claims this scanner makes today.
Findings Gallery
The bundled support-refund fixture demonstrates the kind of release risks Agents Shipgate is designed to surface:
## Release Decision
Decision: blocked
Reason: 2 active findings block release.
Blockers: 2
Review items: 16
Fail policy: would_fail_ci=false (exit 0)
Top findings:
1. stripe.create_refund lacks a declared approval policy
2. stripe.create_refund lacks idempotency evidence
3. Manifest declares broad permission scopes
stripe.create_refundlacks a declared approval policy, so a financial action could ship without an explicit human review gate.stripe.create_refund.amountlacks a maximum bound, weakening blast-radius control.stripe.create_refundlacks idempotency evidence while retry behavior is known, risking duplicate refunds.wildcard_mcp_tools.*exposes a wildcard tool surface, making review incomplete.gmail.send_customer_emailoverlaps a prohibited external-communication action without a matching confirmation policy.
See it block a PR
The fastest way to understand what changes for a reviewer: walk through a Golden PR. Each one ships a sample manifest, the resulting report, the release decision, and the recommended PR-comment summary an agent should post.
openai-agents-sdk-refund-agent— refund agent addsstripe.create_refund. Shipgate decidesblockedbecause approval policy and idempotency evidence are missing. Includes the recommended Markdown PR-comment template.golden-pr-from-coding-agent.md— the artifact a coding agent should produce after running the verify-first flow: PR comment,merge_verdict,capability_review, and human/coding-agent next action.mcp-only-tool-server— MCP server with no Python framework imports; demonstrates the MCP-only adoption path.openapi-support-agent— OpenAPI-described tool surface; shows scope-coverage findings.
Why Not Just...
| Alternative | Gap Agents Shipgate Covers |
|---|---|
| Unit tests | Tests usually validate code paths, not the released tool surface and declared policies. |
| Code review | Reviewers miss generated specs, MCP exports, broad scopes, and missing approval policies. |
| Runtime traces | Useful later, but they arrive after behavior exists. Agents Shipgate runs before promotion. |
| Nothing | Tool-surface drift becomes a production surprise. |
For named comparisons against specific evaluators and platforms, see the
marketing-site versus pages:
vs evals,
vs promptfoo,
vs Braintrust,
vs LangSmith, and
vs observability platforms.
Framework notes
Framework adapters (Google ADK, LangChain/LangGraph, CrewAI, OpenAI Agents
SDK) parse Python AST only — they never import framework packages or user
modules. Dynamic or prebuilt toolsets produce warnings orinsufficient_evidence findings unless you provide explicit MCP, OpenAPI, or
local tool-inventory inputs. Framework-by-framework minimal manifests, with
runnable sample repos for each adapter, live indocs/minimal-real-configs.md.
Organization-specific release rules ship as local declarative YAML
policy packs (checks.policy_packs in the manifest, or--policy-pack on the CLI) — static data, no code import.
Limitations
Agents Shipgate is a static, manifest-first scanner. It is intentionally narrow:
- It does not run agents, call tools, invoke LLMs, or verify model availability by default (static-by-default; see Trust Model and
ALLOWED_EXCEPTIONS). - It does not verify runtime behavior, latency, prompt quality, or routing decisions.
- It does not replace dynamic security testing or human security review of the underlying systems.
- It only inspects what is declared in
shipgate.yaml, local OpenAPI specs, MCP exports, Anthropic/OpenAI API artifacts, optional SDK AST metadata, static Google ADK/LangChain/CrewAI/n8n inputs, Codex repo config, and static Codex plugin package metadata; tools that are not declared or statically discoverable are not scanned. - The manifest remains
version: "0.1"so existing configs keep working. Current reports carryreport_schema_version: "0.26"(additive structured evidence gaps over v0.25's opt-in local trace/provenance evidence) while preserving the stable payload contract documented in the report schema.
See ROADMAP.md for what is planned next.
Trust Model
Agents Shipgate does not import user code, run agents, call tools, call LLMs, connect to MCP servers, make network calls, or collect telemetry by default.
See Trust model and Security policy for the default local-only guarantees and disclosure process.
Pricing And Open Source Stance
Agents Shipgate is and will remain free OSS for individuals and teams running it on their own infrastructure. The core manifest-first scanner, built-in checks, Markdown report, and JSON report are intended to remain open source. We do not collect telemetry and do not require an account.
If hosted dashboards, SSO, org-wide baselines, approval workflows, or trace-based evidence emerge, they should live in a separate optional product rather than moving core OSS functionality behind a paywall.
Teams shipping production-like tool-using agents can apply to the
Three Moons Lab design partner program
— the marketing page mirrorsdocs/design-partners.md in the repo and includes a
prefilled email CTA for review criteria and contact. The current pilot runbook
is docs/design-partner-verifier-pilot.md:
bring one AI-generated agent PR, run the verifier loop, and export redacted
feedback (agents-shipgate feedback export --from agents-shipgate-reports/verifier.json --redact --out shipgate-feedback.json —
never raw report evidence).
Docs
The marketing site at threemoonslab.com carries
the same canonical concepts in human-readable, search-optimised form:
quickstart,
check catalog,
glossary,
blog, and
design partners. The in-repo docs
below are the canonical contract; the marketing pages are sized for first-time
readers and AI search ingest.
- The 5-minute mental model
- MCP and host-permission governance
- MCP server mode
- Tool-Use Readiness release gate category
- Manifest v0.1
- Check catalog
- Policy packs
- Baseline workflow
- JSON report schema v0.26
- Capability standard
- Capability lock schema v0.2
- Capability lock diff schema v0.3
- Governance benchmark
- Feedback export schema v0.1
- Privacy and redaction
- Terms
- Trust model
- AI search summary
- Design partners
- Design partner verifier pilot
- Runtime inventory design note
- Troubleshooting
- Integration recipes
- Distribution plan
- JSON report schema v0.2
- JSON report schema v0.1
Reviews (0)
Sign in to leave a review.
Leave a reviewNo results found