Live demo · real TinyFish runs · shared budget, one run at a time
AskYoda

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
View on npm ↗
/plugin install askyoda --marketplace 1sakshm/askyoda-plugin
The skill on GitHub ↗

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 applied

Runs 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,bthe check the answer must pass
--schema file.jsonTinyFish output schema
--start fetch|agent|agent_stealthstarting rung (default fetch)
--max-credits N · --max-attempts Nhard budget (defaults 40 / 4)
--proxy CCproxy country for the stealth rung
--llm gemini|anthropic|noneoptional LLM (default: whichever key is set)
--json · --quietmachine-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_interactionEscalate from Fetch, or tell the agent to click, search, “Load more” or “Next”.
popup_overlayPrefix the goal with “close cookie and consent dialogs first”.
misread_pageFree re-extraction from the cached page, or a tighter schema plus “return at least N items”.
bot_blockJump to the stealth browser behind a proxy.
auth_wallStop — needs human escalation, with 0 wasted credits.
captchaStop — needs human escalation.