gait

Gait

Policy-as-code for AI agent tool calls.

Gait sits at the execution boundary between an agent decision and a real tool call. It evaluates structured intent, blocks non-allow decisions before side effects land, emits signed proof you can verify offline, and turns failures into deterministic CI regressions.

Offline-first. Fail-closed. Portable evidence.

Fast proof is not the same as hardened oss-prod readiness. Strict inline fail-closed enforcement starts only when you control the real tool-execution seam.

Docs: clyra-ai.github.io/gait | Install: docs/install.md | Examples: examples/integrations/ | Command docs: docs/README.md

In Brief

Gait is a local CLI and runtime boundary for tool-calling agents. It is not an agent framework, not a model host, and not a hosted dashboard.

Managed/preloaded agent note: if you cannot intercept tool execution before side effects, Gait still provides observe, verify, capture, and regress workflows. Strict inline fail-closed enforcement starts only when you control the execution boundary.

Install

Choose one install path. Prefer release binaries for onboarding and support flows, then confirm the installed version with gait version --json.

Release Installer

curl -fsSL https://raw.githubusercontent.com/Clyra-AI/gait/main/scripts/install.sh | bash

Homebrew

brew install Clyra-AI/tap/gait

Go Install

go install github.com/Clyra-AI/gait/cmd/gait@latest

Tagged module installs resolve the release version from Go build metadata. Local checkout builds remain contributor/dev builds and may still report 0.0.0-dev.

Start Here

Choose the path that matches what you need right now.

Fast 20-Second Proof

Use this when you want to validate the install, create one real artifact, and wire the first deterministic CI gate without integrating into an agent yet.

gait version --json
gait doctor --json
gait demo
gait verify run_demo --json
gait regress bootstrap --from run_demo --json --junit ./gait-out/junit.xml

This path gives you:

• a truthful install and environment check via gait doctor --json
• one signed demo artifact you can verify offline
• one deterministic regress gate you can drop into CI immediately

This is proof of install plus artifact contract. It does not put Gait in front of a live tool boundary yet.

Add Repo Policy To A Real Project

Use this when you want a repo-root policy file and a local contract check.

gait init --json
gait check --json

This path writes .gait.yaml, reports the live policy contract, and returns install-safe next commands.

It still does not enforce inline unless you wire Gait into a real wrapper, sidecar, middleware, or MCP boundary before the tool call executes.

Integrate At The Runtime Boundary

Use this when your agent already makes real tool calls and you want enforcement at the execution seam.

This is the first path that enables strict inline fail-closed enforcement. If you cannot intercept tool execution before side effects, stay on the proof, observe, capture, and regress paths instead of claiming runtime blocking.

Official and reference lanes:

• LangChain middleware lane (official): examples/integrations/langchain/
• OpenAI-style reference boundary demo: examples/integrations/openai_agents/

Other supported boundary paths:

• generic wrapper or sidecar calling gait gate eval before real execution
• MCP trust and transport boundary via gait mcp verify, gait mcp proxy, or gait mcp serve

No account. No API key. No hosted dependency.

Harden oss-prod Readiness Explicitly

Use this only after the fast proof and a real runtime boundary are already in place.

gait init --json
# From a repo checkout:
cp examples/config/oss_prod_template.yaml .gait/config.yaml

# Or, after a binary-only install:
curl -fsSL https://raw.githubusercontent.com/Clyra-AI/gait/main/examples/config/oss_prod_template.yaml -o .gait/config.yaml

gait check --json
gait doctor --production-readiness --json

In oss-prod, policies that set default_verdict: allow are rejected. Keep strict profiles on block or require_approval, then grant allow paths with explicit rules.

Do not describe a deployment as hardened oss-prod until that readiness check returns ok=true.

Why Gait

Agent frameworks decide what to do. Gait decides whether the tool action may execute.

Use Gait when you need to:

• enforce allow, block, or require_approval before a real side effect happens
• keep signed traces, packs, and callpacks as ticket-ready evidence
• convert incidents into deterministic CI regressions with stable exit codes
• add MCP trust preflight, context evidence, durable jobs, or voice gating on the same artifact contract

When To Use Gait

• Your agent can cause real side effects and you need allow, block, or require_approval at execution time.
• You want signed portable evidence for PRs, incidents, tickets, or audits.
• You need deterministic regressions that fail CI with stable exit behavior.
• You want one contract across wrappers, middleware, sidecars, and MCP boundaries.

When Not To Use Gait

• You do not have a real interception seam before tool execution.
• Your workflow has no tool-side effects and no evidence requirement.
• You only need hosted observability and do not need offline verification or deterministic regression.
• You need a vulnerability scanner, model host, or orchestration framework rather than an execution-boundary control layer.

The Boundary Contract

Every integration path should implement the same rule:

1. Normalize a real tool action into structured intent.
2. Ask Gait for a verdict.
3. Execute the side effect only when verdict == "allow".
4. Keep the signed trace, runpack, or pack.

def dispatch_tool(tool_call):
    decision = gait_evaluate(tool_call)
    if decision["verdict"] != "allow":
        return {"executed": False, "verdict": decision["verdict"]}
    return {"executed": True, "result": execute_real_tool(tool_call)}

This is the core contract across wrappers, middleware, sidecars, and MCP boundaries.

For hardened high-risk execution paths, pass explicit execution context with the intent instead of relying on wrapper-local memory alone: agent_id, run_id, workflow_id, repo, environment, credential provenance, and broker receipt evidence are all now first-class authorization inputs. See docs/contracts/action_context.md, docs/contracts/agent_identity.md, docs/contracts/credential_provenance.md, and docs/contracts/broker_receipt.md. The baseline-highrisk templates treat covered write and deploy paths as JIT-only by default: AWS STS, GitHub OIDC, and Vault-style dynamic credentials are accepted when scoped and time-bounded, while standing PATs, IAM users, inherited environment credentials, and unknown provenance block with explicit reason codes. Gate policies can also define deterministic freeze windows for production-impacting actions and replay them with gait gate eval --evaluation-time <rfc3339> --json.

Proposed Action Contract boundary

Gait can explicitly validate one Wrkr proposed_action_contract artifact and activate it only through a current-selection manifest and an explicit authority/key boundary:

gait contract validate --proposal proposal.json --json
gait contract activate --proposal proposal.json --selection fixture-manifest.json \
  --policy-digest sha256:<64-hex> --principal principal:owner \
  --authority-ref approval:owner --target target:deploy \
  --environment production --mode context_only --private-key gait-private.key \
  --valid-from 2026-07-19T00:00:00Z --lifecycle-out lifecycle.jsonl --json
gait contract verify --activation activated.json --proposal proposal.json --public-key gait-public.key --json
gait contract consume proposal.json --selection fixture-manifest.json
gait effects grade --snapshot effect_snapshot.json --contract effect_contract.json --trusted-collector-key collector.pub --expected-action-digest sha256:<64-hex> [--expected-activation-digest sha256:<64-hex>] [--expected-proof-digest sha256:<64-hex>] [--junit effects.xml] --json

For the pre-execution runtime projection, use deterministic classification and fail-closed readiness checks. Readiness requires an explicit UTC evaluation time, policy digest, policy-named validator producer(s), validator public key(s), and fresh digest-bound evidence; lifecycle records retain separate Proof correlation references. It never executes a tool or claims an observed effect:

gait contract classify --proposal proposal.json --json
gait contract readiness --proposal proposal.json \
  --policy-digest sha256:<64-hex> \
  --trusted-validators gait-policy-validator \
  --trusted-validator-key gait-policy-validator=validator.pub.b64 \
  --evaluation-time 2026-07-19T12:00:00Z --json
gait contract explain --proposal proposal.json --json

Proposals remain report-only evidence. Activation is a distinct signed activated_action_contract artifact binding the immutable proposal digest and revision, policy digest, principal/authority refs, target/environment, mode, validity, and explicit exceptions. Production signing requires an explicit Ed25519 private key; development signing is test-only and marked in the artifact. See docs/contracts/action_contract_activation.md. High-risk proc.exec and generated-code paths can now carry structured sandbox metadata so Gate can validate bounded network, filesystem, timeout, and privilege posture without ingesting raw environment contents. Gate can also apply schema-backed kill-switch state for emergency stop coverage across matching agents, identities, tools, targets, paths, workspaces, and environments.

Post-execution evidence is explicit and signed. gait action-contract lifecycle-result requires separate --trace-public-key and --public-key values, an --evaluation-time, and either --result-digest or the Go-hashed structured --result-file; it accepts the same trusted-validator flags used by Gate and rejects non-allow or readiness-mismatched traces. The Python adapter authenticates the signed lifecycle prefix with gait action-contract lifecycle-verify before invoking an executor. gait containment stop emits a signed control/lifecycle sequence and accepts an explicit --occurrence-time for deterministic evidence timestamps. It also emits a reference-only receipt for an explicit boundary. The local-only adapter name gait-local-kill-switch is required when no external revocation command is configured; unconfigured external boundaries are reported partial. The opt-in gait effects compose runner is bounded to an explicit Compose project and paths, never installs dependencies, and skips PostgreSQL observation unless a collector is configured. MCP proxy and bridge calls accept the same pre-execution controls through --chain-policy, --chain-state, --chain-candidate, --chain-state-out, and --circuit-input; control blocks still emit signed traces. For machine consumers, gait gate eval --explain --json now returns a schema-backed explanation object instead of prose-only guidance. Provider-style JIT broker receipts for AWS STS, GitHub OIDC, Vault, GCP, Azure, and Okta/CyberArk-style flows can now normalize into the shared broker evidence contract with offline stub recipes under examples/credential-brokers/. For staged rollout, named trust-graduation policies now cover observe, dry-run, read-only allow, approval-gated write, brokered write, and blocked destructive phases under examples/policy/trust_graduation/. Authorization evidence can now be packed as an authorization bundle through gait pack build --type authorization --from <authorization_bundle.json> and verified offline with gait pack verify.

Runtime Integration Paths

OpenAI Agents Reference Demo

This is the fastest in-repo reference demo for the runtime boundary contract: a local wrapper at the tool boundary with deterministic allow, block, and approval quickstarts. It is not a package-backed official SDK lane.

python3 examples/integrations/openai_agents/quickstart.py --scenario allow
python3 examples/integrations/openai_agents/quickstart.py --scenario block
python3 examples/integrations/openai_agents/quickstart.py --scenario require_approval

See examples/integrations/openai_agents/.

LangChain

The official LangChain surface is middleware with optional callback correlation. Enforcement happens in wrap_tool_call; callbacks are additive only.

run_session(...) and other Python run-capture helpers delegate digest completion to gait run record in Go rather than hashing artifact fields in Python. Normalize set values to JSON lists before calling the SDK; unsupported non-JSON values now fail deterministically instead of being coerced into digest-affecting output.

gait run record defaults to capture_mode=reference: it computes args_digest and result_digest, keeps refs and receipts deterministic, and strips raw intents[].args and results[].result from the serialized runpack. Use --capture-mode raw only when you explicitly want sensitive payload retention; JSON output warns when raw capture is selected.

(cd sdk/python && uv sync --extra langchain --extra dev)
(cd sdk/python && uv run --python 3.13 --extra langchain python ../../examples/integrations/langchain/quickstart.py --scenario allow)

See examples/integrations/langchain/ and docs/sdk/python.md.

Generic Wrapper Or Sidecar

If your framework is not an official lane, put Gait at the dispatcher boundary and call gait gate eval immediately before the real side effect.

See docs/agent_integration_boundary.md, docs/integration_checklist.md, and examples/sidecar/README.md.

Bounded Wrapper Commands

gait test, gait enforce, and gait trace are real commands, but they are bounded wrappers for explicit Gait-aware integrations that emit trace references. They do not auto-instrument arbitrary runtimes.

gait trace --json -- <child command...>
gait test --json -- <child command...>
gait enforce --json -- <child command...>

Simple End-To-End Scenario

See docs/scenarios/simple_agent_tool_boundary.md and the reference wrapper quickstart at examples/integrations/openai_agents/quickstart.py.

Policy Onboarding

The repo-root policy contract is .gait.yaml.

gait init --json writes the starter file. gait check --json validates it and reports the live contract.

Minimal shape:

schema_id: gait.gate.policy
schema_version: 1.0.0
default_verdict: block
mcp_trust:
  enabled: true
  snapshot: ./examples/integrations/mcp_trust/trust_snapshot.json
rules:
  - name: require-approval-tool-write
    priority: 20
    effect: require_approval
    match:
      tool_names: [tool.write]

Policy docs:

• docs/policy_authoring.md
• schemas/v1/gate/policy.schema.json

Regress And CI

Gait turns incidents into deterministic CI gates.

One-command bootstrap path:

gait regress bootstrap --from run_demo --json --junit ./gait-out/junit.xml

Explicit handoff path:

gait capture --from run_demo --json
gait regress add --from ./gait-out/capture.json --json
gait regress run --json --junit ./gait-out/junit.xml

CI adoption assets:

• GitHub Actions template: .github/workflows/adoption-regress-template.yml
• GitLab, Jenkins, CircleCI, and hook guidance: docs/ci_regress_kit.md
• One-PR rollout guide: docs/adopt_in_one_pr.md

Stable regress exits:

• 0 pass
• 5 deterministic regression failure

Stable exit codes:

• 0 success
• 1 internal or runtime failure
• 2 verification failure
• 3 policy block
• 4 approval required
• 5 deterministic regression failure
• 6 invalid input
• 7 dependency missing
• 8 unsafe operation blocked

MCP Trust

Gait can preflight and enforce MCP trust at the connection boundary.

Current shipped model:

• external scanners or registries produce a local trust snapshot
• gait mcp verify, gait mcp proxy, and gait mcp serve consume that local file
• Gait enforces the decision at the boundary; it does not replace the scanner
• duplicate normalized server_id / server_name entries invalidate the snapshot, and required high-risk trust paths fail closed on that ambiguity

This is the right split with tools such as Snyk: external tooling finds the issue, and Gait enforces the runtime response.

See examples/integrations/mcp_trust/README.md, docs/mcp_capability_matrix.md, and docs/external_tool_registry_policy.md.

Gait Vs Observability

Gait is complementary to observability products such as LangSmith, Langfuse, and AgentOps.

• LangSmith, Langfuse, and AgentOps focus on hosted tracing, analytics, and after-the-fact inspection.
• Gait evaluates structured action intent, enforces at the execution boundary, and emits signed artifacts you can reuse in CI and incident response.
• The practical model is camera plus gate: use observability to inspect, and use Gait to block or gate high-risk tool actions before they land.

What Gait Does Not Do

• Gait is not an agent framework, orchestrator, model host, or hosted dashboard.
• Gait does not auto-instrument arbitrary runtimes without an interception seam.
• Gait is not a vulnerability scanner.
• Gait does not replace your tracing, analytics, SIEM, or scanner stack.

What Ships In OSS

• Gate: structured policy evaluation with fail-closed enforcement
• Evidence: signed traces, runpacks, packs, and callpacks
• Regress: deterministic incident-to-CI workflows
• Durable jobs: checkpointed long-running work with pause, resume, cancel, and approvals
• MCP trust: trust preflight plus proxy, bridge, and serve boundaries
• Voice and context evidence: fail-closed gating for spoken commitments and missing-context high-risk actions

Compliance And Evidence

Every Gait decision can produce signed proof artifacts that map to operational and audit evidence.

• gait verify, gait pack verify, and gait trace verify work offline
• packs use Ed25519 signatures plus SHA-256 manifests

Release tags also publish an authoritative Action Contract evidence bundle. It is generated at release time from the peeled tag commit, signed with a domain-separated Ed25519 key derived from immutable release identity (never a checked-in private key), and accompanied by its manifest, public key, typed evidence, referenced schemas, checksums, and provenance. The bundle is distinct from the checked-in fixture-only conformance corpus and must verify with go run ./scripts/action_contract_authoritative_bundle_generator --verify <bundle.zip> --checksums <signed-checksums.txt>; the embedded public key alone is not a trust anchor.

• duplicate ZIP entry names are treated as verification failures rather than ambiguous soft passes
• artifacts are deterministic, versioned, and designed for PRs, incidents, change control, and audits

Framework mapping and evidence docs:

• docs/contracts/primitive_contract.md
• docs/contracts/packspec_v1.md
• docs/contracts/intent_receipt_conformance.md
• docs/failure_taxonomy_exit_codes.md

Learn More

• Install: docs/install.md
• Policy authoring: docs/policy_authoring.md
• Integration checklist: docs/integration_checklist.md
• Boundary guide: docs/agent_integration_boundary.md
• Python SDK: docs/sdk/python.md
• MCP capability matrix: docs/mcp_capability_matrix.md
• CI regress kit: docs/ci_regress_kit.md
• Docs index: docs/README.md

Command Surface

gait init|check                                    Repo policy bootstrap and validation
gait gate eval                                     Policy evaluation + signed trace
gait test|enforce                                  Bounded wrappers for explicit Gait-aware integrations
gait capture                                       Persist portable capture receipt from explicit source
gait regress add|init|bootstrap|run                Incident -> CI gate
gait mcp verify|proxy|bridge|serve                 MCP trust preflight and transport adapters
gait trace|trace verify                            Observe-only wrapper and trace integrity verification
gait demo|verify                                   First artifact and offline verification
gait pack build|verify|inspect|diff|export         Unified pack operations
gait job submit|status|checkpoint|pause|resume     Durable job lifecycle
gait job stop|approve|cancel|inspect               Emergency stop, approval, and inspection
gait voice token mint|verify                       Voice commitment gating
gait voice pack build|verify|inspect|diff          Voice callpack operations
gait doctor [--production-readiness] [adoption]    Diagnostics + readiness
gait policy init|validate|fmt|simulate|test        Policy authoring workflows
gait keys init|rotate|verify                       Signing key lifecycle
gait ui                                            Local playground
gait version [--json] [--explain]                  Print version

Feedback

Issues: github.com/Clyra-AI/gait/issues | Security: SECURITY.md | Contributing: CONTRIBUTING.md | Code of conduct: CODE_OF_CONDUCT.md