{"id":51079059,"url":"https://github.com/maxgfr/ultrasearch","last_synced_at":"2026-06-27T22:00:58.957Z","repository":{"id":364534434,"uuid":"1268284799","full_name":"maxgfr/ultrasearch","owner":"maxgfr","description":"Recap everything the web says about a topic — keyless multi-backend web search into a citation-checked, tiered Markdown + HTML report, in five modes (topic/bug/research/learn/startup), plus an agentic deep-research tier (decompose, merge, adversarially verify). The web-facing sibling of ultradoc. A skills.sh agent skill.","archived":false,"fork":false,"pushed_at":"2026-06-20T09:53:03.000Z","size":671,"stargazers_count":0,"open_issues_count":6,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-23T16:40:31.959Z","etag":null,"topics":["agent-skill","ai-agent","citations","claude","deep-research","literature-review","rag","research","skills","skills-sh","typescript","web-search"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/maxgfr.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-13T10:56:20.000Z","updated_at":"2026-06-16T06:36:48.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/maxgfr/ultrasearch","commit_stats":null,"previous_names":["maxgfr/ultrasearch"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/maxgfr/ultrasearch","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maxgfr%2Fultrasearch","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maxgfr%2Fultrasearch/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maxgfr%2Fultrasearch/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maxgfr%2Fultrasearch/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/maxgfr","download_url":"https://codeload.github.com/maxgfr/ultrasearch/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maxgfr%2Fultrasearch/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34869004,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-27T02:00:06.362Z","response_time":126,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-skill","ai-agent","citations","claude","deep-research","literature-review","rag","research","skills","skills-sh","typescript","web-search"],"created_at":"2026-06-23T16:33:07.833Z","updated_at":"2026-06-27T22:00:58.928Z","avatar_url":"https://github.com/maxgfr.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ultrasearch\n\n**Recap everything the web says about a topic — grounded, not guessed.**\n\n`ultrasearch` is a [skills.sh](https://skills.sh) agent skill. Give it a\ntopic or question and it fans out **keyless web search across many backends**,\nfetches and de-duplicates the pages into an **evidence dossier**, then has the\nagent write a **citation-checked research report** in three sizes (TL;DR /\nstandard / exhaustive) plus a **self-contained HTML** you can open and read.\n\nIt's the web-facing sibling of [`ultradoc`](https://github.com/maxgfr/ultradoc):\nsame machine (one committed, zero-dependency Node bundle; deterministic\nretrieval; a `check` command that fails on ungrounded claims), pointed at the\nopen web instead of a git repo.\n\n```bash\nnpx skills add maxgfr/ultrasearch\n```\n\n## Why\n\nAsk a model about a topic and it answers from stale training memory. ultrasearch\n**retrieves first**: it searches, fetches real pages, and writes each source's\ncleaned text to disk. The agent then writes an answer where **every factual\nclaim cites a fetched source** (`[S3]`), and `ultrasearch check` fails the report\nif any citation is dangling or any claim is unsourced. The model may still add\nits own background knowledge — but only as a **clearly flagged \"model hint\"**\n(`\u003e [model-hint] …`), never disguised as a source.\n\n## What you get\n\nA run writes an output folder:\n\n```\n\u003cout\u003e/\n  manifest.json   run metadata (question, mode, depth, backends, source count)\n  sources.json    the dossier: S1…Sn with url, title, backend, trust, extract path\n  sources/S#.md   cleaned, readable text of each fetched source\n  DOSSIER.md      model-facing digest + the template + citation rules\n  SUMMARY.md      TL;DR tier            ┐\n  REPORT.md       standard tier         ├ written by the agent, cited [S#]\n  FULL.md         exhaustive tier       ┘\n  glossary.md     (learn mode)   refs.bib (research mode)\n  index.html      self-contained HTML report (embedded CSS + TOC), easy to read\n```\n\n## Five modes\n\nEach mode is a **report template** + a **backend-priority profile**:\n\n| Mode | For | Favors |\n|------|-----|--------|\n| `topic` *(default)* | a general briefing on any subject | Wikipedia + general web |\n| `bug` | debugging an error / symptom | Stack Overflow, GitHub issues, Hacker News, changelogs |\n| `research` | a scholarly literature review | arXiv, Crossref, OpenAlex, Semantic Scholar, Europe PMC, PubMed (+ `refs.bib`) |\n| `learn` | learning a topic from scratch | general web + docs → glossary, lesson, exercises, rich HTML |\n| `startup` | market research for a product/idea | general web → competitors, market sizing, pricing, GTM |\n\n## How it's used (the agent's loop)\n\n```bash\n# 1. Retrieve — fan out keyless backends, write the dossier\nnode scripts/ultrasearch.mjs gather --q \"how does HTTP rate limiting work\" \\\n  --mode topic --depth standard --out /tmp/rl\n\n# 2. The agent reads DOSSIER.md, enriches thin areas with its own WebSearch:\nnode scripts/ultrasearch.mjs fetch --url \"https://…\" --out /tmp/rl    # → prints new S#\n\n# 3. The agent writes SUMMARY.md / REPORT.md / FULL.md, citing every claim [S#]\n\n# 4. Render + verify grounding\nnode scripts/ultrasearch.mjs render --run /tmp/rl     # → index.html\nnode scripts/ultrasearch.mjs check  --run /tmp/rl     # exit≠0 if ungrounded\n```\n\n## Deep research tier (opt-in)\n\nFor an exhaustive, *verified* deep-dive, ultrasearch runs an agentic loop instead\nof a single pass — **decompose → fan out → merge → adversarially verify →\nloop-until-dry** — grafted onto the same keyless engine. Every step is a plain\nCLI call, so it works on any harness; parallel subagents are an *optimization*,\nnever a requirement (full playbook + the copy-pasteable subagent contract:\n[`references/deep-research-playbook.md`](references/deep-research-playbook.md)).\n\n```bash\n# decompose into sub-questions, each with a deterministic out dir to gather into\nnode scripts/ultrasearch.mjs plan   --q \"\u003cquestion\u003e\" --run-root /tmp/deep\n# fan out one `gather --depth deep` per sub-question (parallel subagents or a loop), then:\nnode scripts/ultrasearch.mjs merge  --runs \"/tmp/deep/q1,/tmp/deep/q2\" --master /tmp/deep/master\n# write the tiers against the master, then verify every claim against its source:\nnode scripts/ultrasearch.mjs verify --run /tmp/deep/master [--shards N --shard I]  # one skeptic per shard\nnode scripts/ultrasearch.mjs verify --apply \u003cverdicts|dir\u003e --run /tmp/deep/master\nnode scripts/ultrasearch.mjs check  --semantic --run /tmp/deep/master   # fails on refuted/unsupported claims\n```\n\n`check --semantic` also surfaces **contradictions** — claims whose cited sources\ndisagree. Retrieval flags two more quality signals to act on: a **thin dossier**\n(too few on-topic sources — `check --min-sources N` enforces a floor) and\n**snippet-only** sources (the page fetch failed, so only the search snippet is on\nfile, marked `⚠ snippet only`).\n\n## Keyless, no API keys\n\nDiscovery is a layered, free fallback cascade, mirroring ultradoc:\n**SearXNG** (local, optional) → **DuckDuckGo** → **DuckDuckGo Lite** → **Mojeek**\n→ **Marginalia** — it stops at the first engine that returns enough, so recall\nsurvives one engine blocking — then the agent's own **WebSearch** (URLs fed back\nvia `fetch --url`). Mode-specific backends add\nWikipedia, the keyless StackExchange (multi-site) / Hacker News / GitHub APIs,\nand the scholarly APIs (arXiv / Crossref / OpenAlex / Semantic Scholar /\nEurope PMC / PubMed) — all keyless.\n\nEach run plans **query variants** and fans backends out across them, re-ranks\nsources by how well their fetched text covers the question, dedupes the same\nwork across scholarly backends by DOI/arXiv id, and retries once on throttling\n— so you get broad, relevant, de-duplicated coverage.\n\n## Commands\n\n- `gather` — the main entrypoint: search → fetch → dedupe → write dossier.\n- `search --backend \u003ckind\u003e` — drill one backend (debugging retrieval).\n- `fetch` / `add-source` — ingest a URL into a dossier (the WebSearch bridge).\n- `render --run \u003cdir\u003e` — render the report tiers to a self-contained `index.html`.\n- `check --run \u003cdir\u003e` — validate citation grounding (`--semantic` folds in the\n  verify verdicts + contradictions; `--min-sources N` fails a too-thin dossier).\n- `modes` — list modes and their backend profiles.\n- `plan` / `merge` / `verify` — the deep-research tier (decompose → merge →\n  adversarially verify; `verify --shards` for parallel skeptics).\n\nRun `node scripts/ultrasearch.mjs --help` for the full surface, and see\n[`DOCUMENTATION.md`](DOCUMENTATION.md) for the architecture.\n\n## License\n\nMIT © maxgfr\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaxgfr%2Fultrasearch","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmaxgfr%2Fultrasearch","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaxgfr%2Fultrasearch/lists"}