| name | price-scan |
| description | Scan a shortlist of products for current price, stock, shipping and landed cost across the user's configured marketplaces, from the user's own machine with the VPN exit set to the country each shop requires. Use when comparing live prices across shops, re-checking whether a shortlisted item has moved, working out what something will actually cost delivered to a specific address, or checking which delivery options make a deadline. Works inside any purchase-research repo. |
| allowed-tools | Bash(python3 *), Bash(./scripts/*), Bash(ls *), Bash(cat *), Bash(mkdir *), Read, Write, Edit, Glob, Grep |
Price Scan — Live Prices and Delivery Options for a Shortlist
Turns a shortlist of candidate products into a table of current prices, shipping
options and landed costs, delivered to a named address profile. Designed to run
inside a purchase-research repo, writing results into that repo so scans
accumulate next to the research they inform.
The plugin is public; the config it reads is not. Marketplaces, VPN setup and
delivery addresses live in the plugin data directory outside any repo — see
/procurement-tools:shop-setup.
The one rule
Never source a price from a cloud fetch. WebSearch, WebFetch, Tavily and
gateway-side fetchers egress from somewhere that is not the user's machine, so
they return whatever country that host resolves to — a plausible number for the
wrong market, with nothing on the page to signal it. Prices, stock and shipping
quotes come from this machine, through the user's own VPN exit, or they are
marked unavailable. Cloud tools are fine for finding candidate products and
reading reviews; they are not fine for pricing them.
Prerequisites
Config at <plugin-data-dir>/marketplaces.yaml and addresses.yaml, where
<plugin-data-dir> resolves as $CLAUDE_USER_DATA/procurement-tools/ →
$XDG_DATA_HOME/claude-plugins/procurement-tools/ →
~/.local/share/claude-plugins/procurement-tools/ (the convention the plugin's other
commands use). If it's missing, run /procurement-tools:shop-setup first rather than
guessing values.
Flow
1. Preflight the exit
python3 "${CLAUDE_PLUGIN_ROOT}/scripts/price_scan.py" --check-egress
Reports the observed exit country, whether the VPN client is on PATH, and which
exits the in-scope shops need. This sends one request to a public IP-geolocation
endpoint — that endpoint sees the machine's exit IP and nothing else.
Do this before pricing anything. The failure mode it prevents is silent: a scan
run from the wrong exit returns real-looking numbers in the wrong currency for
the wrong market, and nothing downstream flags it.
2. Make sure there's a watchlist
The scanner reads price-watchlist.yaml from the repo root. If there isn't one,
create it from ${CLAUDE_PLUGIN_ROOT}/examples/price-watchlist.example.yaml and
populate it from whatever the repo already knows — a shortlist in research/,
candidates in spec.md, a comparison table in docs/. Confirm the list with
the user before scanning; a watchlist assembled from stale research wastes the
run.
Use direct product URLs. Search-result pages are the most heavily
bot-protected part of these sites, and a search URL doesn't pin one product
between runs, which makes the price history meaningless.
3. Scan
python3 "${CLAUDE_PLUGIN_ROOT}/scripts/price_scan.py" --address <profile-id>
Useful flags: --marketplace <id> to restrict to one shop, --no-vpn to leave
the connection alone entirely, --dry-run to see what it would do to the VPN
without doing it, --watchlist / --out-dir for non-default paths.
The scanner groups candidates by the exit country their shop requires and flips
the VPN once per country. With a kill-switch enabled each flip briefly drops
connectivity, so never work around this by scanning candidates one at a time
with separate invocations.
Tell the user when the VPN moved and where to. It is their network connection;
a scan that silently leaves them on a different continent is not acceptable even
when auto_switch permits the move.
4. Finish the blocked rows in a browser
Amazon and Newegg both sit behind bot protection. blocked rows are an expected
outcome of scripted fetching, not a defect to debug — the scan report lists them
under "Needs a browser".
For those, use claude-in-chrome: a real session, already logged in, already on
the same VPN exit. Read the price, shipping options and delivery estimate off
the page and write them into the scan's markdown report. Mark by-hand rows as
such so a later reader can tell which numbers a script parsed and which a human
read.
Do not click through to checkout, place orders, or trigger confirmation dialogs.
This skill prices things; buying them is the user's action.
5. Report
Summarise in the reply: cheapest landed, whether anything is out of stock, which
rows are unresolved, and any delivery option that misses the address profile's
deadline. Point at the generated files rather than pasting them wholesale.
Output
Written to data/price-scans/ in the current repo, created if absent:
| File | Contents |
|---|
<stamp>-scan.md | Comparison table, unresolved rows, landed-cost workings, run log |
<stamp>-scan.json | Same data structured, for later diffing |
price-history.csv | Appended every run — this is what makes "has it dropped since last week?" answerable |
Honesty constraints
These matter more than completeness of the table:
- A missing price stays missing. The scanner emits
null with a status
(blocked, no_price, not_found, error, skipped_wrong_geo). Never fill
a gap with a remembered, estimated, or search-result price.
- Landed cost states its assumptions. Unknown shipping is counted as zero
and said to be; an unconfirmed tax rate is labelled unconfirmed. Don't
present a total whose caveats you've dropped.
- Shipping cost off a product page is indicative. Real cost usually appears
at cart. Newegg in particular quotes at cart, not on the page.
- A price is tied to an exit country and a moment. Carry both into any claim
built on it.
Relationship to the rest of the plugin
/procurement-tools:research and /procurement-tools:compare decide what to buy; this skill
establishes what it costs to get it here, now. /procurement-tools:market-check does
the strategic version of the same question — local market versus international
RRP with import realism — and reads the same config. Run this when the shortlist
is settled and the question has become procurement rather than selection.
