HCC Docs

Local development

hcc dev (the @hcc/cli package) connects the test environment to your machine, like stripe listen --forward-to. Test flow events reach localhost, with no public URL, no ngrok and no endpoint to change. With an hcc.config.ts, every save deploys what changed to test.

pnpm dlx @hcc/cli dev --forward-to http://localhost:8790/hcc -- wrangler dev --port 8790
✓ Dev session ds_8f2… attached (test environment, workspace Acme)
  Flow events → http://localhost:8790/hcc · Webhooks → not forwarded

12:04:31  call_9x… ringing   +14155550100 → +12025550107
12:04:31  → call.answered            200    38 ms   say "Thanks for calling.", gather 1 digit
12:04:35  ← caller: Pressed 1
12:04:35  → call.gather              200    21 ms   connect assistant
12:04:52  ✓ call_9x… completed 21 s
12:04:52  ← call.completed           delivered 200 12 ms
  • Your code runs unchanged: events carry the same envelope and Hcc-Signature (the test endpoint's secret) and the same budget, so your server verifies them as usual. Timeouts and errors take the same fallbacks.
  • It uses a test key only: --api-key, else HCC_TEST_API_KEY / HCC_API_KEY from the environment, .dev.vars or .env. A live key is refused; the key is never printed.
  • --forward-to and --webhooks-to must be localhost, 127.0.0.1 or [::1].
  • On save it scans in a fresh process, keeps hcc.gen.ts current, and deploys only what changed, to test only. A file that fails to load is printed, and the last good version stays. --no-sync keeps the generated file current and deploys nothing.
  • Agent tools. A save syncs tools only to test branches, because the tools on a shared agent's main are the ones live calls use. --sync-tools syncs to every agent. It tells you when tools changed and weren't synced.
  • -- <command> runs your server too: its output prefixed app │, started once hcc.gen.ts exists, stopped when hcc dev stops. Separate terminals work as well.
  • Webhooks. Pass --webhooks-to to get a copy of every test Event, signed with a secret printed at startup: set it as HCC_WEBHOOK_SECRET for hcc.webhooks.verify. Without it, copies aren't forwarded and each type prints once. Registered webhook endpoints still get their deliveries.
  • Without an hcc.config.ts, the flows that run are the ones deployed to test (a test key, or alsoTest: true). Place calls from the dashboard's Simulator or with hcc.simulator; their timeline prints in the terminal.
  • One dev session per workspace: a second hcc dev takes over the first. The dashboard's Flows and Simulator pages show who is attached; owners and admins can detach it. Ctrl+C detaches.