npm package · v0.1.0 · Claude Code skill
askyoda
The whole AskYoda ladder in one function call — or one skill your Claude Code agent reaches for on its own: run a goal on TinyFish, verify the answer, diagnose and patch failures, and escalate to a human when no retry can help, inside a hard credit budget.
npm i askyoda/plugin install askyoda --marketplace 1sakshm/askyoda-plugin- Zero dependencies
- TypeScript
- Bring your own TinyFish key
- MIT
01
In Claude Code
> /plugin install askyoda --marketplace 1sakshm/askyoda-plugin # then just ask, e.g. > Get me the title and price of the first 5 books on https://books.toscrape.com
The skill teaches Claude when to reach for AskYoda and how to use it well: write a check that matches what you actually asked for, run npx askyoda inside a credit budget, and report honestly — verified answers with their cost, partial answers as partial, and login walls or CAPTCHAs as “needs human escalation”. Set TINYFISH_API_KEY first; runs bill to your own account.
02
Quickstart
import { AskYoda } from "askyoda";
const yoda = new AskYoda({
tinyfishKey: process.env.TINYFISH_API_KEY!,
llm: { provider: "gemini", apiKey: process.env.GEMINI_API_KEY! }, // optional
});
const run = await yoda.run({
url: "https://example.com/careers",
goal: "List the open positions with their title and team.",
expect: { minItems: { path: "positions", min: 20 } },
maxCredits: 25,
});
run.status; // "verified" | "needs_human" | "budget_exhausted" | "error" | "cancelled"
run.result; // the verified answer
run.creditsUsed; // estimated TinyFish credits (1 per agent step)
run.diagnoses; // what failed, where, with quoted evidence, and the patch appliedRuns bill to your own TinyFish account. The LLM is optional: without one, AskYoda skips the free Fetch extraction and diagnoses with its built-in rules.
03
From the terminal
export TINYFISH_API_KEY=... npx askyoda run https://example.com/careers \ "List the open positions with their title and team." \ --min-items positions:20 --max-credits 25
| --min-items path:N · --contains TEXT · --regex P · --fields a,b | the check the answer must pass |
| --schema file.json | TinyFish output schema |
| --start fetch|agent|agent_stealth | starting rung (default fetch) |
| --max-credits N · --max-attempts N | hard budget (defaults 40 / 4) |
| --proxy CC | proxy country for the stealth rung |
| --llm gemini|anthropic|none | optional LLM (default: whichever key is set) |
| --json · --quiet | machine-readable output · verdict only |
Exit codes: 0 verified · 2 needs human escalation · 3 budget spent · 1 error.
04
Live events
await yoda.run({
url, goal, expect,
onEvent: (e) => {
if (e.type === "live_view") console.log("watch:", e.streaming_url);
if (e.type === "diagnosis") console.log(e.diagnosis.failure_class);
},
});
for await (const e of yoda.stream({ url, goal, expect })) console.log(e.type);05
What it fixes
| needs_interaction | Escalate from Fetch, or tell the agent to click, search, “Load more” or “Next”. |
| popup_overlay | Prefix the goal with “close cookie and consent dialogs first”. |
| misread_page | Free re-extraction from the cached page, or a tighter schema plus “return at least N items”. |
| bot_block | Jump to the stealth browser behind a proxy. |
| auth_wall | Stop — needs human escalation, with 0 wasted credits. |
| captcha | Stop — needs human escalation. |