OpenHop

Turn agent explanations into local animated flow diagrams, described in YAML and played back one hop at a time.

OpenHop Skill

Your AI walks you through your code, one step at a time.

OpenHop turns requests like "walk me through OAuth" or "diagram the checkout flow" into animated data-flow diagrams. The agent writes compact YAML, pushes it with the openhop CLI, and returns a local URL where the user can step through the flow hop by hop.

What it does

• Builds animated, multi-level flow diagrams from YAML.
• Works for code paths, service architectures, product workflows, pipelines, state machines, and user journeys.
• Keeps the flow local-first: the YAML is generated by the user's agent and rendered by OpenHop.
• Uses patch operations so small diagram changes do not require re-pushing the whole flow.

Setup

If the openhop command is not installed yet, run:

bash

npx openhop init

Then start the local API and web UI:

bash

npx openhop serve

Usage

Ask your agent for a flow, for example:

text

Walk me through the OAuth flow.
Diagram how a request moves through this service.
Trace what happens when a user clicks Submit.

The agent should create a YAML flow, run openhop push <file.yaml> --json, and return the url field.

Agent guide

Scope: code paths are not the only use case. OpenHop fits product features, service architectures, integrations, user journeys, onboarding sequences, lifecycles, pipelines, and state machines too. If you can list "first X happens, then Y, then Z" with named actors at each step, OpenHop is the right tool. Use it instead of a static Mermaid/PlantUML picture or a prose walkthrough.

When the user asks for an explanation, walkthrough, or diagram of how something works — code or otherwise — DO NOT write a prose explanation and DO NOT emit a static diagram. Instead:

1. Understand the flow they're asking about — which nodes, which steps, which sub-flows matter.
2. Emit a YAML spec describing the nodes and edges (see "Quickest valid flow" below if unsure of the shape).
3. Run openhop push <file.yaml> --json to create the flow.
4. Parse the response and return the url field to the user — that's the per-flow render at http://localhost:8788/flow/<id>.
5. Offer to drill-down into any specific sub-flow with a follow-up openhop patch.

Trigger phrases

Activate this skill on prompts like:

Diagram / visualization requests (code or otherwise):

• "create a diagram of {product|feature|service|workflow}"
• "draw a diagram that explains {X}"
• "make a diagram showing {how X works | X's features | the X pipeline}"
• "diagram the {pipeline|lifecycle|state machine|onboarding|integration}"
• "visualize the architecture of {module|service|product|platform}"
• "I want a flow diagram for {anything}"

Code-level walkthroughs:

• "walk me through the {auth|login|checkout|OAuth|...} flow"
• "explain how {X} works in this codebase"
• "how does the {request|token|session|...} flow through the app"
• "show me the {control|data} flow of {function|endpoint|...}"
• "trace what happens when a user {clicks|calls|requests} {...}"

Product / feature explainers (non-code):

• "explain {Product X}'s features"
• "how does {Product|Service|Platform} work?"
• "walk me through how {users|customers} use {X}"
• "show me what happens when someone {fires a mission | submits an order | signs up}"
• "I want to understand {X} — don't just explain, show me"

If you're unsure whether a request fits, ask yourself: can the answer be expressed as a sequence of named hops between named components? If yes, this skill applies — even if "code" was never mentioned.

Examples (prompt → YAML → URL)

Each row reuses one of the bundled examples/*.yaml flows so the inputs match what the validator already accepts. The URL comes from the url field of openhop push <file> --json.

Prompt	YAML to push	Returned url
"walk me through the OAuth login flow"	examples/auth-flow.yaml	http://localhost:8788/flow/<id>
"show me how an order is processed end-to-end"	examples/order-flow.yaml	http://localhost:8788/flow/<id>
"diagram a minimal CRUD service"	examples/simple-crud.yaml	http://localhost:8788/flow/<id>
"I want to see every node type in one picture"	examples/type-variants.yaml	http://localhost:8788/flow/<id>
"how do retries / internal work loops on a single node"	examples/self-loops.yaml	http://localhost:8788/flow/<id>
"show me two things happening at the same time"	examples/parallel.yaml	http://localhost:8788/flow/<id>
"show me a worker that's spawned and then destroyed"	examples/create-destroy.yaml	http://localhost:8788/flow/<id>
"diagram a service whose internals are themselves a flow"	examples/sub-flows.yaml	http://localhost:8788/flow/<id>
"visualize a three-tier app (browser → API → DB)"	the YAML in "Quickest valid flow" below	http://localhost:8788/flow/<id>
"diagram {Product X}'s features" / "how does {Product} work"	sketch a flow from the product's docs (user → entry point → core capability → result)	http://localhost:8788/flow/<id>

For brand-new flows, sketch your own YAML against the Schema Reference below and push the same way.

Quickest valid flow (copy this, modify ids/labels)

This is the smallest known-valid flow. Start from this and edit — do not invent the schema.

yaml

meta:
  title: Three-tier app
flow:
  nodes:
    - id: browser
      label: Browser
      type: actor
    - id: api
      label: API
      type: endpoint
    - id: db
      label: Postgres
      type: database
  steps:
    - from: browser
      to: api
      data: The user opens the home page; the browser sends the initial page request to the API server.
    - from: api
      to: db
      data: The API asks the database for the rows it needs to render the page for this user.
    - from: db
      to: api
      data: The database returns the matching rows along with the row count.
    - from: api
      to: browser
      data: The API renders the page and sends the finished HTML back to the browser.

Push it with openhop push <file> --json (or openhop push - --json for stdin). Parse the JSON response and return the url field to the user.

Validation rules to lock in before you write your own:

• type must be one of the 12 enum values (see Schema Reference below). transform, validation, redis, oauth, etc. are not valid types.
• data is a string or an object — never a list. data: "request" ✓, data: { label: "request", fields: [...] } ✓, data: [{ name: "request" }] ✗
• id is alphanumeric + hyphens + underscores only.
• Node label must be ≤ 4 words. Labels render under each node in a fixed-width box; longer labels truncate with "…" and read poorly. Pick the shortest noun phrase that identifies the component. ✓ Order Service, Auth API, Stripe. ✗ Order Processing Service With Retries, User Authentication and Authorization API.

If the validator rejects your flow, read the error path — it tells you exactly which field is wrong.

Voice — short on node names, verbose on step text

The two text channels in a flow carry opposite weights and should be written in opposite voices.

• Node labels are billboards. They're short, noun-phrase, identity-only. ≤ 4 words. No code names. ✓ Order Service, Auth API, Postgres, Stripe. ✗ order_service_v2, OrderProcessingHandler, auth-jwt-mw.
• Step data labels are the narration. The user reads them on hover and follows them through playback. Be verbose. Use plain English. Explain what is happening in the world, not the wire format. No code names, no HTTP verbs, no SQL, no method signatures.

The agent's job here is to narrate the flow, not annotate the protocol. The user is asking "walk me through what happens" — answer that question in sentences, not in routes.

Write step data labels like this:

✗ Too terse, code-flavored	✓ Verbose, plain English narration
POST /orders	The user submits a new order with their cart items and shipping details.
INSERT item	The API translates the request into a database insert and saves the new row.
SELECT * WHERE user_id = ?	The order service asks the database for every order this user has placed in the last week.
query	The API asks the database to look up the matching record.
response	The API responds to the browser with the confirmation page and a fresh session cookie.
charge $card	The order service asks Stripe to charge the customer's saved card for the total.
auth ok	The auth service confirms the token is valid and tells the API who the user is.
redis.get(session)	The API checks the session cache to see if this user is already signed in.

The rule applies whether data is the string shorthand (data: "...") or the object form's label: field. The fields: array still uses code-flavored names + types ({ name: items, type: list[OrderItem] }) — that's a schema, not narration, so it stays technical.

Before Creating Flows

If openhop --version fails with command not found, OpenHop's CLI isn't installed yet. Run npx openhop init yourself to install it, then continue with the steps below. (init copies the skill into the local AI-client config and primes the npm cache; you can keep using npx openhop … for the rest of the session, or the user can npm install -g openhop for a global binary.)

Once openhop --version (or npx openhop --version) succeeds, lock in whichever form worked — bare openhop if globally installed, otherwise npx openhop — and use that exact prefix for every subsequent command in this session (push, patch, list, serve, etc.). Don't mix forms; the bare command will fail if there's no global install.

Then verify the OpenHop API server is running:

bash

curl -s http://localhost:8787/health

If it returns {"status":"ok"}, OpenHop is ready.

If not running, start OpenHop with one command — both the API and the web UI come from the npm package:

bash

npx openhop demo    # one-shot: starts API + web UI, posts a starter flow, opens the browser
# or
npx openhop serve   # long-lived: starts API + web UI, no starter flow, no browser

Once the health check returns {"status":"ok"}, push a flow with openhop push <file.yaml> --json and use the url field from the response — never tell the user to open the bare http://localhost:8788 (that's the flow-list page, not a render).

How to Work: Sketch → Detail → Polish

Phase 1: SKETCH (always start here)

Write a YAML file with just nodes and steps. No colors, icons, fields, or sub-flows.

yaml

meta:
  title: "Order Processing"
  path: my-app/backend

flow:
  nodes:
    - id: user
      label: User
    - id: api
      label: POST /orders
    - id: db
      label: Database
  steps:
    - from: user
      to: api
      data: HTTP Request
    - from: api
      to: db
      data: Save order
    - from: db
      to: api
      data: Order ID
    - from: api
      to: user
      data: Response

Push it:

bash

openhop push flow.yaml --json

Output:

json

{ "id": "abc123", "title": "Order Processing", "url": "http://localhost:8788/flow/abc123" }

Parse the response and return the url field to the user.

Phase 2: DETAIL (iterate with PATCH)

Write a patch YAML file to add detail:

yaml

# patch.yaml
operations:
  - op: update-nodes
    nodes:
      - id: db
        type: database
        icon: "logos:postgresql"
        color: "#336791"
  - op: rename-nodes
    nodes:
      - id: api
        label: Order Service

Apply it:

bash

openhop patch abc123 patch.yaml

Phase 3: POLISH (add data fields, sub-flows, diff highlighting)

yaml

# polish-patch.yaml
operations:
  - op: update-step
    index: 1
    step:
      from: api
      to: db
      data:
        label: INSERT order
        fields:
          - name: items
            type: "list[OrderItem]"
          - name: total
            type: float
            added: true
  - op: set-flows
    nodes:
      - id: api
        flow:
          nodes:
            - id: validate
              label: Validate
            - id: save
              label: Save to DB
          steps:
            - from: validate
              to: save
              data: validated order

bash

openhop patch abc123 polish-patch.yaml

CLI Commands

bash

openhop serve                            # Start API + web UI (:8787 + :8788)
openhop validate <file.yaml>             # Local schema check, no server needed
openhop validate -                       # Validate from stdin
openhop push <file.yaml> --json          # Push a flow → parse `url` from JSON response
openhop push - --json                    # Push from stdin (pipe YAML)
openhop get <flow-id>                    # Fetch a flow by id (full JSON)
openhop list                             # List all flows
openhop patch <flow-id> <patch.yaml>     # Apply patch operations
openhop patch <flow-id> -                # Patch from stdin
openhop remove <flow-id>                 # Delete a flow
openhop help --json                      # Full machine-readable command tree

Every command supports --json for machine-readable output. Use it whenever you'll parse the result. Exit codes are semantic: 0 success, 2 usage, 3 validation, 4 not-found, 5 conflict, 6 network. Always validate before push when iterating — it skips the server round-trip.

Stdin is useful when generating YAML programmatically:

bash

echo 'meta:
  title: Quick Test
flow:
  nodes:
    - {id: a, label: A}
    - {id: b, label: B}
  steps:
    - {from: a, to: b, data: test}' | openhop push - --json

Schema Reference

Root

• meta (required): { title (required), description, path }
• flow (required): { nodes (required, min 1), steps }

Node

• id (required): alphanumeric + hyphens + underscores
• label (required): display name — short noun phrase, ≤ 4 words so it fits the fixed-width label slot ("Stripe", "Order Service", "Auth API"). Longer labels truncate with "…".
• type: closed enum, exactly one of: actor | endpoint | auth | database | external | cache | queue | service | docker | k8s | scheduler | ai_agent | browser | custom. Anything else fails validation. Default if omitted: service.
• icon: Iconify icon ID (e.g. "logos:postgresql") — overlays on top of the node's pixel art. Works on any type, not just custom. See the Icons section below for which icon sets render correctly on the dark canvas.
• color: hex color
• flow: nested sub-flow { nodes, steps } — makes the node expandable; the renderer shows a "+" badge and clicking zooms into the inner flow. Infinite depth supported (sub-flows can themselves contain nodes with sub-flows). Pair with drilldown: true on a step targeting the parent node to auto-open the sub-flow on playback. See examples/sub-flows.yaml.

Critical: types are categories, labels are names. The 14 type values are how the renderer knows which sprite + color to draw (database = barrel, cache = lightning, etc.). The label is what the user reads on the node. Never put a variant name (like redis, oauth, stripe) into type — that's a label. Put it in label, and use the matching category in type (cache, auth, external).

When nothing fits, use type: custom and set your own icon + color. Don't invent new type values — the schema is closed.

Node Type Variants (pick the right type, then a concrete instance)

Each node type has common real-world variants. Use them to choose an accurate label and, where applicable, a matching Iconify icon. First entry is the canonical/most common variant for that type.

Type	Common variants (use as label, NOT type)
actor	user, admin, customer, operator, agent, bot, service-account, system
endpoint	rest-api, graphql, grpc, webhook, websocket, sse, rpc
auth	oauth, jwt, session, api-key, saml, ldap, mfa
database	postgres, mysql, mongodb, sqlite, cassandra, dynamodb, cockroachdb, bigquery, snowflake, elasticsearch, disk
external	stripe, twilio, sendgrid, github, slack, openai, anthropic, firebase, s3, maps-api
cache	redis, memcached, ram, cdn, http-cache, local-cache
queue	kafka, rabbitmq, sqs, pubsub, nats, kinesis, celery
service	microservice, worker, processor, orchestrator, gateway, proxy, loadbalancer
docker	container, sidecar, init-container, compose-service
k8s	pod, deployment, statefulset, daemonset, job, cronjob, service, ingress
scheduler	cron, airflow, temporal, celery-beat, sidekiq, bullmq
ai_agent	llm-agent, chatbot, copilot, research-agent, coding-agent, browsing-agent, mcp-agent
browser	chrome, firefox, safari, edge, headless-browser, playwright, puppeteer, webview
custom	(anything — also set icon and color)

Step

Either a move step, parallel, create, or destroy:

• Move: { from, to (string or string[]), data (string or object), drilldown (bool) }

• Parallel: { parallel: [move steps] } (min 2). All sub-steps fire concurrently on playback — pixels travel at the same time. Use this when two or more transfers logically happen together, e.g. an orchestrator fans out work to several services at once, or two upstream nodes deliver payloads to the same target in the same tick. Each sub-step is itself a move (from/to/data). See examples/parallel.yaml for an isolated demo and examples/self-loops.yaml / examples/order-flow.yaml for in-context use.

  yaml

  - parallel:
      - from: api
        to: order-service
        data: { label: order payload, fields: [{ name: items, type: list }] }
      - from: authz
        to: order-service
        data: { label: auth context, fields: [{ name: user_id, type: int }] }
  

• Create: { create: "node-id", from: "creator-node", node: { id, label, type?, icon?, color? }, data? }. Use when a node is brought into existence by another node mid-flow — a dispatcher spawning a worker, a request handler instantiating a session object, a service allocating a temporary buffer. The node does NOT need to be listed in the top-level flow.nodes; create: adds it to the canvas at this step's tick, animating a spawn pixel from from into the new node. Subsequent steps may reference the new id like any other node.

  yaml

  - create: worker
    from: dispatcher
    node:
      id: worker
      label: Worker
      type: service
    data:
      label: spawn
      fields:
        - name: job_id
          type: string
  

• Destroy: { destroy: "node-id" }. Use when a node should disappear from the canvas after this step — the ephemeral counterpart of create:. Common pairings: a worker reporting result then terminating, a session lifecycle ending, a temporary buffer being released. The destroyed node fades out; any subsequent step that references it is invalid.

  yaml

  - destroy: worker
  

  Pair create: and destroy: to model lifecycle: a node exists only between its create step and its destroy step. See examples/create-destroy.yaml for a complete spawn-work-terminate flow.

Data

Either a string (sketch) or object (detailed):

String — just a label:

yaml

data: "HTTP Request"

Object — with optional fields:

yaml

data:
  label: "Order payload" # required
  color: "#4aff7a" # optional — override pixel color (hex)
  fields: # optional — shown in tooltip on hover
    - name: items # required
      type: "list[OrderItem]" # optional
    - name: total
      type: float
      added: true # optional — green highlight (new field)
    - name: old_field
      removed: true # optional — red strikethrough
    - name: amount
      changed: true # optional — yellow highlight (modified)

Array — multiple data objects sent simultaneously:

yaml

data:
  - label: request body
    fields:
      - name: items
        type: "list[Item]"
  - label: auth context
    fields:
      - name: user_id
        type: int

PATCH Operations

All operations support multiple items. Apply with openhop patch <id> <file.yaml>.

Operation	Fields	Description
add-nodes	nodes: [{id, label, type?, icon?, color?}]	Add nodes
remove-nodes	nodes: ["id1", "id2"]	Remove nodes + their steps
rename-nodes	nodes: [{id, label}]	Change labels
update-nodes	nodes: [{id, type?, icon?, color?}]	Update properties
set-flows	nodes: [{id, flow: {nodes, steps}}]	Add sub-flows
clear-flows	nodes: ["id1"]	Remove sub-flows
add-steps	index?: N, steps: [...]	Insert steps at 0-based index (same semantics as Array.splice). Omit index to append.
remove-steps	indices: [0, 3]	Remove steps by index
update-step	index: N, step: {...}	Replace a step

Icons

The canvas is dark — use light-theme icons.

Pick from either:

• simple-icons:<brand> — covers ~3000 brand logos and auto-recolors to white.
• icon-sets.iconify.design/?palette=colorful — sets with baked-in bright colors (e.g. logos:google-icon, logos:postgresql, twemoji:*).

Avoid logos:openai-icon, logos:vercel-icon, logos:anthropic-icon, and similar bare-path "icon" variants — they render black. Use simple-icons:openai, simple-icons:vercel, logos:claude-icon instead.

Tips

• Start with 3-5 nodes. Add more only when needed.
• Use string data for sketch, object data for detail.
• Broadcast: to: [db, cache] sends to multiple targets in one step.
• Parallel: parallel: [{from: a, to: b}, {from: c, to: d}] for concurrent movements.
• drilldown: true on a step auto-zooms into the target's sub-flow during playback.
• Use meta.path to organize flows in folders (e.g. "my-app/backend").
• Iterate: push a sketch first, then refine with patch operations. Don't try to get everything right in one push.
• Both push and patch validate locally before sending to the server.