Quickstart

Record a task on a public site, build a spider from it, check the spider offline, then run it for real.

View as MarkdownAsk Claude about this page

Before you begin

  • Node.js 24 or later
  • Google Chrome
  • A clone of the Graphdom repository

Graphdom has no runtime dependencies and no build step. Run it from the clone:

cd graphdom
alias graphdom="node $PWD/src/cli.ts"
graphdom --version

1. Record a session

graphdom record https://quotes.toscrape.com --task "search quotes"

Chrome opens on the site. Do the task as you normally would, then close the browser or press Ctrl-C. Graphdom prints the session directory:

archive/sessions/2026-11-06T09-12-44-101Z-3f9a1c

Record the same task two or three more times with different inputs. More sessions give the spider more evidence to generalise from.

You can start from Studio instead: graphdom studio on an empty workspace walks you through adding the site, making a project and naming the task, then opens the task’s page at Record a session, where Record opens the same Chrome window.

2. Review it in Studio

graphdom studio --root archive

Studio opens in a Chrome app window on 127.0.0.1:7357. Each session shows its actions, the requests they caused and the pages they led to. Once a recording is finished, its actions are grouped as the spider will perform them, so they are the same steps the task’s Flow lines up across sessions. Anything the spider will not do, like a click that led nowhere, is tagged not a spider step.

3. Build the spider

graphdom build archive --task "search quotes"

The build derives a spider from the sessions and runs it against each one in its sandbox. It ships only when every session passes. The spider lands in spiders/<task>/v1/, and each later build in the next version beside it:

File Contents
spider.json The spider in its intermediate form (IR)
spider.ts, prelude.ts The same spider compiled to Playwright
tests.json Each session’s inputs and expected outcome
report.json, evidence.json The test results the release is based on

When GOOGLE_CLOUD_PROJECT is set, Gemini on your Vertex AI project (gemini-3.5-flash) repairs candidates that fail; otherwise a Claude model does, when ANTHROPIC_API_KEY is set. Pass --model none to derive only.

In Studio, the task’s page lists its versions, newest first: whether each passes, when it was built, and where it came from. A version built from the recordings says so. A repair names the version it repaired and counts what it changed, and that count opens the spider compared with that version, step by step.

4. Run it

Check the spider offline on Graphdom’s runtime first:

graphdom runtime test spiders/<task>/v1/spider.json \
  --session archive/sessions/<id>

Then run it on the real site:

graphdom runtime run spiders/<task>/v1/spider.json --input query=love

The runtime asks on the terminal before every submit step. Pass --yes to skip the prompt. Outputs are printed as JSON on stdout.

Next steps