Workflow CLI Debugger

A fast, local-first observability companion for building and testing Clay Workflows from the CLI. It connects aggregate health, exact run traces, terminal findings, resolved step data, and copyable repair commands without replacing Clay Workflows or Sculptor.

Security model

The deployed Vercel project is a static start/help page. Connected debugging runs from the launcher on localhost, so it has no Clay credentials, API routes, database, analytics, or workflow payloads.

The launcher starts an ephemeral HTTP bridge bound only to 127.0.0.1 on an automatically selected free port. It checks clay whoami first and opens clay login when authentication is required. The bridge keeps the active run window in process memory, redacts likely secret fields, and stops on Ctrl-C. The browser authenticates with a random per-process bearer token placed in the URL fragment, which is never sent to Vercel. Responses use Cache-Control: no-store.

Workflow data travels:

Clay CLI → localhost bridge → browser memory

It never travels through Vercel or GitHub and is never written to disk by this app.

Start here

Share the public npm command as the canonical entry point. The Vercel page is an optional explainer and is not required to run the debugger.

npx --yes workflow-cli-debugger

Prerequisites: Node 20+, an active sign-in at app.clay.com, and the official Clay plugin installed in Claude Code, Codex, or Cursor. The plugin provides the clay CLI. Confirm it with clay whoami. If clay is not yet on PATH, the debugger automatically searches the installed plugin caches for the bundled launcher. It then guides users through Clay login and workspace selection when needed, starts the secure local UI and bridge on an automatically selected loopback port, and opens the connected browser tab. Keep the terminal open while debugging. The picker automatically pages through every workflow available to the active Clay session and searches by workflow name or ID.

Share with teammates

Anyone can launch from any directory without repository access, a global install, or sudo:

npx --yes workflow-cli-debugger

npx keeps the downloaded launcher in the user's npm cache, avoiding protected system directories such as /usr/local/lib/node_modules. The command works from Terminal, Claude Code, or any shell. It serves the bundled UI locally without introducing an account system or sending workflow data to a hosted backend. The source repository remains private; public package users receive only the files listed in the npm package manifest.

When developing from a clone, launch directly into a workflow:

npm run observe -- wf_abc123

The bundled local UI is the default, so there is no separate web server to run. For UI development with hot reload, use the local Vite shell instead:

npm run observe:local -- wf_abc123

Use --no-open when working over SSH or when you only want the connected URL printed.

The normal 20/50/100-run windows are optimized for iteration. Choose All only for a deliberate historical analysis; the bridge caps a single session at 5,000 runs.

Debug loop

• Health overview: node reach, reliability, recurring failures, runtime, credits, quality checks, and version-linked evidence.
• Flow: one top-to-bottom execution map showing branch volume, continuation rate, eventual outcome mix, exact failure points, and successful endpoints.
• Deep node inspection: lazy, redacted configuration schemas with nested Clay input/output field cards and searchable step records for account agents, Claygents, code, conditionals, tools, and map/reduce nodes.
• Results table: scan what each run found, search outcomes, flag review cues, export the visible run window, and click any row to open its exact trace.
• Run debugger: move through exact traces, inspect every reached step, and load resolved inputs/outputs only when selected.
• CLI handoff: copy inspect, replay, retest, and snapshot commands at the point of failure.

Keyboard shortcuts in the run debugger:

• J / K — next or previous run
• [ / ] — previous or next step
• F — failed runs only
• / — focus search
• C — copy the exact Clay CLI command for the selected step

Access and workspaces

The debugger never grants or elevates Clay access. It inherits the active user's workspace and permissions from clay login. The connected user and workspace are shown in the interface. Workflow listing, graph reads, run reads, and node configuration reads may each be restricted by Clay; unavailable details are shown as permission states instead of being proxied through another account.

To use another workspace, change the active Clay CLI session and relaunch the debugger. No Clay credential or workspace data is stored by this project.

clay login

Choose the other workspace during Clay login, stop the current debugger with Ctrl-C, and run the launch command again. Clay admins can inspect another workspace only when that login/session is granted access to it; the debugger does not add cross-workspace privileges.

Development

npm install
npm run observe:local
npm test
npm run build
npm run build:launcher

npm run observe:local starts the local bridge and the Vite hot-reload interface. The in-app Settings tab repeats the editing, session, workspace-switching, and inspection commands while the debugger is running.

See DESIGN-KIT.md for the visualization language and DIAGNOSABILITY-NOTES.md for customer and competitive context.