openhop: Instructions file for Codex

AGENTS.md

Instructions for AI agents (Claude Code, Cursor, Cline, Codex, OpenAI Swe-agent, etc.) working in this repo.

Humans: this is a companion to README.md — that file has the install walkthrough, screenshots, and feature list. Read it first if you're new here.

---

What this is

OpenHop is a YAML-driven data-flow visualizer. Authors describe a flow in YAML, push it with the openhop CLI, and the UI animates data pixels traveling between nodes on a pixel-art canvas.

• packages/server — Fastify API (:8787), Zod-validated flow store, Swagger at /docs.
• packages/web — React + React Flow + ELK layout. Served by Vite at :8788.
• packages/cli — openhop command (esbuild-bundled, no runtime TS).
• packages/shared — Zod schemas + types, imported by all three.
• skills/openhop/SKILL.md — the canonical authoring guide for any SKILL-compatible agent. If you're being asked to author a flow, load that file first.
• examples/ — reference flows (order-flow.yaml is the canonical example; type-variants.yaml exercises every node type).

Run locally

npm install            # installs deps + bundles packages/cli/dist/index.js
npm run dev            # API on :8787, UI on :8788

Smoke test before you do anything else:

curl -s http://localhost:8787/health        # expect {"status":"ok"}

The dev server hot-reloads on edits under packages/web/src. Server edits restart via tsx watch.

CLI

(cd packages/cli && npm link)   # one-time: makes `openhop` global
openhop push <file.yaml>        # push a flow
openhop list                    # list all flows
openhop patch <id> <file.yaml>  # update a flow
openhop remove <id>             # delete

All commands accept -s <url> to target a non-default server.

Typecheck / build

# per-package
npx tsc --noEmit -p packages/shared
npx tsc --noEmit -p packages/server
npx tsc --noEmit -p packages/web
npx tsc --noEmit -p packages/cli

# CLI bundle (runs automatically via `prepare` on install)
npm run build -w @openhop/cli