Agent Connections: Codex, Claude Code, Cursor, OpenClaw, Hermes

Zap is agent-native by design: every recipe is a portable skill directory with machine-readable frontmatter, and every CLI command emits structured JSON. Any agent that can run shell commands and read a URL can bootstrap a Zap project, author new recipes, and dispatch runs. This page walks through connecting each supported agent — Codex, Claude Code, Cursor, OpenClaw, Hermes, and any generic MCP-capable client — to the Zap skill registry and CLI.

This page focuses on the connection layer: how each agent finds Zap and executes it. For the agent behavioral contract (read SKILL.md first, keep spend opt-in, etc.), see Agent Setup. For the tools the Eve runtime exposes to agents, see Agent Overview.

The Skill Download URLs

Every agent bootstraps from the same three endpoints. Point your agent at these before any other configuration:

Endpoint	Purpose
`https://zap.wzrd.tech/api/skills`	Full manifest of every registered skill (JSON).
`https://zap.wzrd.tech/api/skills/zap`	Core Zap framework skill — recipe grammar, CLI usage, run contract.
`https://zap.wzrd.tech/api/skills/zap-authoring`	Authoring skill — schema fields, prompt conventions, validation rules.
`https://zap.wzrd.tech/api/skills/{slug}`	Any published recipe skill by slug.
`https://zap.wzrd.tech/api/skills/{slug}?format=json`	Same skill as a structured JSON envelope.

Appending ?format=json returns { skill, hash, files: [{ path, content }] } instead of raw Markdown — preferable for programmatic ingestion.

# Fetch the master manifest
curl -s https://zap.wzrd.tech/api/skills | jq

# Pull a specific skill as JSON
curl -s https://zap.wzrd.tech/api/skills/zap-authoring?format=json | jq

CLI Contract

All agents drive Zap through the same CLI. Two commands are enough for a full flow:

# Validate any recipe in the current project
npx @wzrdtech/zap@0.1.0 validate

# Run a recipe (defaults to mock — zero cost)
npx @wzrdtech/zap@0.1.0 run agent/skills/zap-<slug>/Zap.md --json

Agents should always pass --json so output is machine-parseable. The result envelope contains runId, status, zapUrl, and a per-step breakdown — no additional API is needed to observe progress.

Per-Agent Setup

OpenAI Codex CLI

Codex reads project instructions from AGENTS.md at the repo root. zap init writes this file automatically. To point Codex at the remote registry as well, add a zap section to your Codex configuration or paste the following into a session prompt:

Use the Zap skills from https://zap.wzrd.tech/api/skills.
Read AGENTS.md and agent/skills/zap-authoring/SKILL.md before editing any Zap.md.
Validate with:  npx @wzrdtech/zap@0.1.0 validate
Run mock with:  npx @wzrdtech/zap@0.1.0 run agent/skills/zap-<slug>/Zap.md --json
Never pass --live without explicit user approval.

Codex will use the CLI directly through its shell tool; no MCP server is required.

Anthropic Claude Code

Claude Code auto-loads AGENTS.md and CLAUDE.md from the workspace root. zap init writes AGENTS.md. For explicit registry access, add the following to .claude/settings.json or paste as a slash-command prompt:

Zap project. Sources of truth:
  - AGENTS.md
  - agent/skills/zap/SKILL.md
  - agent/skills/zap-authoring/SKILL.md

Remote registry: https://zap.wzrd.tech/api/skills

Before committing any recipe change, run:
  npx @wzrdtech/zap@0.1.0 validate
  npx @wzrdtech/zap@0.1.0 lint

Default provider is mock. Do not switch to gmi/fal without explicit user consent.

Claude Code invokes the Zap CLI through its bash tool. Live runs remain opt-in.

Cursor

Add a rule file at .cursor/rules/zap.mdc so every conversation in the workspace shares the same Zap context:

---
description: Zap generative-video recipe conventions
globs: agent/skills/**, Zap.md, prompts/**
alwaysApply: true
---

Treat Zap.md frontmatter as executable metadata — do not move fields to prose.
Prompts live in `prompts/*.md` under each skill directory.
Default `defaults.provider: mock` for all scaffolded recipes.
Validate with `npx @wzrdtech/zap@0.1.0 validate` before committing.
Skill registry: https://zap.wzrd.tech/api/skills

Cursor’s Composer will pick up the rule automatically when editing any file inside agent/skills/.

OpenClaw

OpenClaw treats each agent/skills/zap-*/ directory as a portable capability. Register the Zap workspace root in your OpenClaw agent config and point it at the reference docs:

# openclaw.yaml
workspace:
  root: ./
  skills_dir: agent/skills
references:
  - path: docs/reference/schema.md
  - path: docs/reference/cli.md
  - url: https://zap.wzrd.tech/api/skills
tools:
  shell:
    allow:
      - "npx @wzrdtech/zap@0.1.0 validate"
      - "npx @wzrdtech/zap@0.1.0 run *"
      - "npx @wzrdtech/zap@0.1.0 status *"

OpenClaw discovers new skills by scanning agent/skills/ for SKILL.md files and enqueues CLI commands through the allow-listed shell tool.

Hermes

Hermes uses a manifest-driven skill loader. Point it at the remote Zap skill manifest so it can hydrate the local agent/skills/ directory on first run:

{
  "skillSources": [
    { "type": "http", "url": "https://zap.wzrd.tech/api/skills" }
  ],
  "cli": {
    "validate": "npx @wzrdtech/zap@0.1.0 validate",
    "run":      "npx @wzrdtech/zap@0.1.0 run {recipe} --json",
    "status":   "npx @wzrdtech/zap@0.1.0 status {runId}"
  },
  "policies": {
    "defaultProvider": "mock",
    "requireExplicitLive": true
  }
}

Hermes hydrates missing skills by fetching each ?format=json endpoint and writing files under agent/skills/.

Any MCP-capable client

For any agent that isn’t listed above, provide these three pieces:

Registry URL: https://zap.wzrd.tech/api/skills
CLI entry point: npx @wzrdtech/zap@0.1.0
Behavioral contract: the six rules in Agent Setup

The agent needs shell execution and HTTP fetch. No custom MCP server is required — the Zap CLI is itself the machine interface.

Handshake Flow

Every supported agent follows the same startup sequence. If your agent isn’t listed above, replicate this flow:

Fetch the skill manifest

curl -s https://zap.wzrd.tech/api/skills

The response lists every published skill with its hash, path, and downloadUrl. Cache the manifest and diff against local agent/skills/ on subsequent starts to detect drift.

Read the core framework skill

curl -s https://zap.wzrd.tech/api/skills/zap

This is the master Zap SKILL — recipe grammar, CLI vocabulary, and the mock-first execution model.

Read the authoring skill before editing recipes

curl -s https://zap.wzrd.tech/api/skills/zap-authoring

Contains schema field reference, prompt conventions, and validation rules. Load it into context before any Zap.md edit.

Validate and run

npx @wzrdtech/zap@0.1.0 validate
npx @wzrdtech/zap@0.1.0 run agent/skills/zap-<slug>/Zap.md --json

Mock is the default. Only pass --live after the user has approved the quoted spend.

Live-Run Handshake

When a creator asks for a real (paid) run, every agent must follow the same three-step handshake:

Show the quote

Run in mock first with --json and surface the quoteUsd field to the user. Do not proceed if the quote exceeds budget.cap_usd.

Confirm credentials are present

For CLI runs, verify GMI_API_KEY (or the required provider key) is exported. For web runs, verify the creator has connected a wallet and uploaded keys via Auth & Secrets.

Dispatch with --live and capture the runId

npx @wzrdtech/zap@0.1.0 run agent/skills/zap-<slug>/Zap.md --live --json --input KEY=value

Persist the returned runId so status can be polled with zap status <runId> or GET /runs/<runId>.

Never hardcode provider keys in a session prompt, agent config, or committed file. Store keys in the user’s shell environment (GMI_API_KEY), Supabase vault (for web runs), or a secrets manager — never in a .mdc, AGENTS.md, or JSON config that lives in the repo.

Agent Setup — the behavioral contract every agent must follow.
Agent Overview — Eve tools, pipeline grammar, and the primitive vs deterministic distinction.
Providers — the seven BYOK secret types and provider routing.
GMI Cloud (BYOK) — real live-run instructions for the primary video provider.

Legacy 0.3.1 Recipes

Core Concepts

Web App

Providers

Agent Framework

Deployment

Reference

Browser Use

Agent Connections: Codex, Claude Code, Cursor, OpenClaw, Hermes

The Skill Download URLs

CLI Contract

Per-Agent Setup

OpenAI Codex CLI

Anthropic Claude Code

Cursor

OpenClaw

Hermes

Any MCP-capable client

Handshake Flow

Live-Run Handshake

​The Skill Download URLs

​CLI Contract

​Per-Agent Setup

​OpenAI Codex CLI

​Anthropic Claude Code

​Cursor

​OpenClaw

​Hermes

​Any MCP-capable client

​Handshake Flow

​Live-Run Handshake

​Related

The Skill Download URLs

CLI Contract

Per-Agent Setup

OpenAI Codex CLI

Anthropic Claude Code

Cursor

OpenClaw

Hermes

Any MCP-capable client

Handshake Flow

Live-Run Handshake

Related