OpenWeb
Agent-native way to access any website. Bridging agent CLI and web GUI through API.
Load Discipline
- Do not read every file in this folder.
- Start with SKILL.md. Follow one route at a time.
Use Existing Site
1. Find the site
openweb sites # list all available sites
If the site has no package, do NOT say "unsupported." Route to add-site/guide.md.
2. Check readiness
openweb <site> # transport, auth, operations list
Requires browser: yes — browser auto-starts when needed; no manual setup requiredRequires login: yes — user must be logged in via their browser session
3. Read site notes
Prefer site docs when they exist in your workspace:
- Source repo: read
src/sites/<site>/SKILL.md for workflows and intent mapping, then src/sites/<site>/DOC.md for internals.
- Shipped/runtime package: only
DOC.md, specs, manifest, examples, and adapters are guaranteed. Per-site SKILL.md and PROGRESS.md are source-tree docs and are not shipped into $OPENWEB_HOME/sites/<site>/.
If only the shipped package is available, rely on openweb <site>, openweb <site> <op>, examples, and DOC.md.
4. Inspect the operation
openweb <site> <op> # params, response shape, permission tier
openweb <site> <op> --example # real example params from fixtures
Check the operation's permission tier before executing:
| Tier |
Default |
Behavior |
read |
allow |
GET-like operations — execute freely |
write |
prompt |
Creates/updates — ask user before executing |
delete |
prompt |
Destructive — ask user before executing |
transact |
deny |
Financial/irreversible — always skip |
5. Execute
openweb <site> <op> '{"key":"value"}' # stdout=JSON, stderr=JSON error
Auto-spill: responses over 4096 bytes write to a temp file.
openweb <site> exec <op> '{...}' is equivalent — exec can be omitted when the third arg is JSON.
6. On failure
Errors on stderr include failureClass:
| failureClass |
Action |
needs_browser |
Browser auto-starts; if it fails, check Chrome installation. Fallback: openweb browser start |
needs_login |
openweb login <site> then openweb browser restart |
needs_page |
Open a tab to the site URL |
bot_blocked |
openweb browser restart --no-headless, user solves CAPTCHA in visible browser, then retry. For persistent sites, set "browser": {"headless": false} in config |
permission_denied |
Update permissions in $OPENWEB_HOME/config.json |
permission_required |
Ask user for confirmation, then retry |
retriable |
Wait a few seconds, retry (max 2) |
fatal |
Don't retry — fix params or check site name |
If the table above doesn't resolve it, read references/troubleshooting.md.
7. Missing site or coverage
Site doesn't exist or lacks needed operations? Read add-site/guide.md.
Add / Expand / Upgrade Site
Read add-site/guide.md
Fix a Problem
Read references/troubleshooting.md
File Map
All paths relative to skills/openweb/.
add-site/ (workflow — load in sequence)
| File |
Load when |
add-site/guide.md |
Entry point for add/expand workflow |
add-site/probe.md |
Probe step: CDP browser-side discovery |
add-site/capture.md |
Capture step: recording browser traffic |
add-site/review.md |
Review step: reading analysis-summary.json |
add-site/curate-operations.md |
Curate: naming, noise, params, permissions |
add-site/curate-runtime.md |
Curate: auth, transport, extraction |
add-site/curate-schemas.md |
Curate: response schemas, examples, PII |
add-site/verify.md |
Verify: runtime + spec + doc loop |
add-site/document.md |
Document: per-site SKILL.md + DOC.md + PROGRESS.md, knowledge updates |
references/ (lookup — load independently)
| File |
Load when |
references/cli.md |
CLI command syntax, flags, stdout/stderr |
references/x-openweb.md |
Full x-openweb field schema |
references/troubleshooting.md |
Something broke — classify, diagnose, fix |
knowledge/ (patterns — load at decision points)
| File |
Load when |
knowledge/archetypes.md |
Expected operations by site category |
knowledge/auth-routing.md |
Auth type unknown — signal-to-family lookup |
knowledge/auth-primitives.md |
Configuring auth — config and gotchas |
knowledge/bot-detection.md |
Transport/capture decisions |
knowledge/extraction.md |
Extraction signals — SSR/DOM patterns |
knowledge/graphql.md |
GraphQL — persisted queries, batching |
knowledge/ws.md |
WebSocket — message/connection patterns |
knowledge/adapter-recipes.md |
Adapter patterns, code templates, pitfalls |
knowledge/transport-upgrade.md |
Transport tier decisions, node feasibility, API discovery |
1---2name: openweb3description: Typed JSON access to 90+ real websites — Google, Amazon, Reddit, YouTube, GitHub, Instagram, Bloomberg, Zillow, and more — across search, shopping, travel, finance, social, news, and dev tools. Use to read, search, post, comment, message, or otherwise interact with these sites (prices, products, articles, stock quotes, flights, posts, comments, DMs, etc.). Run `openweb sites` for the full list.4license: MIT5---67# OpenWeb89Agent-native way to access any website. Bridging agent CLI and web GUI through API.1011## Load Discipline1213- Do not read every file in this folder.14- Start with SKILL.md. Follow one route at a time.1516## Use Existing Site1718### 1. Find the site1920```bash21openweb sites # list all available sites22```2324If the site has no package, do NOT say "unsupported." Route to add-site/guide.md.2526### 2. Check readiness2728```bash29openweb <site> # transport, auth, operations list30```3132- `Requires browser: yes` — browser auto-starts when needed; no manual setup required33- `Requires login: yes` — user must be logged in via their browser session3435### 3. Read site notes3637Prefer site docs when they exist in your workspace:3839- **Source repo:** read `src/sites/<site>/SKILL.md` for workflows and intent mapping, then `src/sites/<site>/DOC.md` for internals.40- **Shipped/runtime package:** only `DOC.md`, specs, manifest, examples, and adapters are guaranteed. Per-site `SKILL.md` and `PROGRESS.md` are source-tree docs and are not shipped into `$OPENWEB_HOME/sites/<site>/`.4142If only the shipped package is available, rely on `openweb <site>`, `openweb <site> <op>`, examples, and `DOC.md`.4344### 4. Inspect the operation4546```bash47openweb <site> <op> # params, response shape, permission tier48openweb <site> <op> --example # real example params from fixtures49```5051Check the operation's permission tier before executing:5253| Tier | Default | Behavior |54|---|---|---|55| `read` | allow | GET-like operations — execute freely |56| `write` | prompt | Creates/updates — ask user before executing |57| `delete` | prompt | Destructive — ask user before executing |58| `transact` | deny | Financial/irreversible — always skip |5960### 5. Execute6162```bash63openweb <site> <op> '{"key":"value"}' # stdout=JSON, stderr=JSON error64```6566Auto-spill: responses over 4096 bytes write to a temp file.6768`openweb <site> exec <op> '{...}'` is equivalent — `exec` can be omitted when the third arg is JSON.6970### 6. On failure7172Errors on stderr include `failureClass`:7374| failureClass | Action |75|---|---|76| `needs_browser` | Browser auto-starts; if it fails, check Chrome installation. Fallback: `openweb browser start` |77| `needs_login` | `openweb login <site>` then `openweb browser restart` |78| `needs_page` | Open a tab to the site URL |79| `bot_blocked` | `openweb browser restart --no-headless`, user solves CAPTCHA in visible browser, then retry. For persistent sites, set `"browser": {"headless": false}` in config |80| `permission_denied` | Update `permissions` in `$OPENWEB_HOME/config.json` |81| `permission_required` | Ask user for confirmation, then retry |82| `retriable` | Wait a few seconds, retry (max 2) |83| `fatal` | Don't retry — fix params or check site name |8485If the table above doesn't resolve it, read references/troubleshooting.md.8687### 7. Missing site or coverage8889Site doesn't exist or lacks needed operations? Read add-site/guide.md.9091## Add / Expand / Upgrade Site9293Read add-site/guide.md9495## Fix a Problem9697Read references/troubleshooting.md9899## File Map100101All paths relative to `skills/openweb/`.102103### add-site/ (workflow — load in sequence)104105| File | Load when |106|---|---|107| `add-site/guide.md` | Entry point for add/expand workflow |108| `add-site/probe.md` | Probe step: CDP browser-side discovery |109| `add-site/capture.md` | Capture step: recording browser traffic |110| `add-site/review.md` | Review step: reading analysis-summary.json |111| `add-site/curate-operations.md` | Curate: naming, noise, params, permissions |112| `add-site/curate-runtime.md` | Curate: auth, transport, extraction |113| `add-site/curate-schemas.md` | Curate: response schemas, examples, PII |114| `add-site/verify.md` | Verify: runtime + spec + doc loop |115| `add-site/document.md` | Document: per-site SKILL.md + DOC.md + PROGRESS.md, knowledge updates |116117### references/ (lookup — load independently)118119| File | Load when |120|---|---|121| `references/cli.md` | CLI command syntax, flags, stdout/stderr |122| `references/x-openweb.md` | Full x-openweb field schema |123| `references/troubleshooting.md` | Something broke — classify, diagnose, fix |124125### knowledge/ (patterns — load at decision points)126127| File | Load when |128|---|---|129| `knowledge/archetypes.md` | Expected operations by site category |130| `knowledge/auth-routing.md` | Auth type unknown — signal-to-family lookup |131| `knowledge/auth-primitives.md` | Configuring auth — config and gotchas |132| `knowledge/bot-detection.md` | Transport/capture decisions |133| `knowledge/extraction.md` | Extraction signals — SSR/DOM patterns |134| `knowledge/graphql.md` | GraphQL — persisted queries, batching |135| `knowledge/ws.md` | WebSocket — message/connection patterns |136| `knowledge/adapter-recipes.md` | Adapter patterns, code templates, pitfalls |137| `knowledge/transport-upgrade.md` | Transport tier decisions, node feasibility, API discovery |
spike-faye-lei