Run an agent pack

The runner executes locally with Node 24 or later and calls models hosted on Cloudflare Workers AI. Your inputs and tool results are sent to the services you use.

Download the files

Save the runner.mjs download in a working folder. On any pack page, download the runnable JSON pack and its example input into the same folder. YAML remains available for reading and editing; the runner consumes JSON and needs no packages for standard execution.

Examples are illustrative inputs, not measured results. Replace them with your own brief, product facts, code or references before judging whether the method helps your work.

Connect Cloudflare

Use Cloudflare’s Workers AI API token template for your account. If creating a custom token, include Workers AI Read and Edit permissions. Save these variables in a private .env file, using your actual account ID and token. Keep that file out of version control and never paste credentials into a pack or its input.

CLOUDFLARE_ACCOUNT_ID=your_account_id
CLOUDFLARE_API_TOKEN=your_workers_ai_token

Model requests use your Cloudflare account and its normal usage billing. GitHub and Firecrawl tools use their respective services; Firecrawl requires FIRECRAWL_API_KEY. GitHub code search requires GITHUB_TOKEN; unauthenticated repository reads work within GitHub's lower rate limits. Tools only read sources.

Check and run

This example uses Copy Fit. For another pack, substitute its downloaded filenames. The first command validates the execution plan without network calls or credentials. The second runs it and writes a private result file containing the output, stage results and request usage.

node runner.mjs --pack copy-fit.json --check
node --env-file=.env runner.mjs --pack copy-fit.json --input copy-fit.input.json --out result.json

Input paths are relative to the input JSON file. Add text source files in files and PNG, JPEG or WebP paths or public HTTPS image URLs in images. Only image-capable stages receive images; later text stages use those stages' observations.

{
  "task": "Find the observable mechanism in this reference.",
  "files": ["reference.css"],
  "images": ["reference.png"]
}

How execution works

Chained steps receive the original input and completed earlier results. Parallel reviewers share the same earlier results and do not see their peers' findings; synthesis runs afterward. Routing runs the classifier and one selected handler. Low-confidence or unclassified requests return for clarification. Evaluator loops stop at their configured limit, with bounded scores and required fields validated in code. Scores are working rubrics, not calibrated probabilities.

Defaults allow 40 model calls, 40 tool calls, 8,192 output tokens per call, three concurrent calls and ten minutes per run. Use --help to see adjustable limits. Provider errors stop the run; invalid structured output gets one repair attempt. Nothing is deployed and no scheduled job is created automatically. To repeat Reference Forager, schedule the CLI externally and supply a current library snapshot each time.

Rendered checks for Copy Fit

Character counts are computed in code as Unicode code points. They are a writing constraint, not proof that text fits. To check fonts, wrapping and clipping on your actual page, install Playwright beside the runner and add a render target to your input.

pnpm add -D playwright
pnpm exec playwright install chromium

"render": {
  "url": "http://localhost:3000/your-page",
  "selectors": { "heading": "#hero-title", "body": "#hero-description" },
  "widths": [390, 1440]
}

Selector keys must match your input slot names. Select one visible leaf text element per slot so the check preserves surrounding icons and markup. The browser temporarily compares each original and replacement in the rendered page. A fit requires no added lines, increased height or detected clipping at every requested width. Without this check, suitable copy returns needs-review. Review meaning and the full composition yourself before publishing.

Read the result

completed: the workflow finished; its findings still need your review.
passed: an evaluator's rubric and implemented gates passed, not a certification of correctness.
needs-review: candidate copy is available but rendered fit has not been checked.
needs-input: evidence, measurements or classification confidence is insufficient.
needs-revision: the evaluator limit was reached without passing.