Deep Research Harness
Justaboringname/deep-research-harness
Pesquisa paralela multi-agente com verificação adversarial e relatórios citados
Ver no GitHubPipeline multi-agente de pesquisa profunda que executa como workflow dinâmico no Claude Code. Decompõe um tópico em sub-tópicos investigados em paralelo por subagentes independentes, aplica verificação adversarial estilo GAN para validar claims, e gera relatório HTML auto-contido e totalmente citado.
Instalação
npx convez-ai Justaboringname/deep-research-harness1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Pesquisa aprofundada de tópicos complexos com múltiplas perspectivas
- Fact-checking e verificação de claims com painel de agentes críticos
- Geração de relatórios técnicos ou jornalísticos auto-contidos e citados
Veredito

Solução robusta e honesta para pesquisa profunda, explicitamente otimizada para qualidade e paralelização em vez de custo de tokens. Arquitetura bem pensada que escapa dos limites clássicos (contexto, degradação, latência), mas demanda alto consumo de API — ideal para pesquisas críticas onde precisão supera custo.
README
A tradução para o português deste README ainda está na fila.
deep-research-harness
A multi-agent deep-research pipeline that runs as a single Claude Code dynamic workflow. You give it a topic; it fans out a tree of subagents to research it, adversarially fact-checks the load-bearing claims, and renders a self-contained, fully-cited HTML report — fire-and-forget.
It is built around two ideas:
- Fan-out like an NFA. A leader decomposes the topic into sub-topics, and each sub-topic is investigated by its own subagent in parallel — a tree of independent search paths rather than one long serial chain.
- Adversarial verification, GAN-style. Before a claim makes it into the report, a panel of skeptic agents tries to refute it from several angles. Claims that survive are kept; claims that can only be defended by reaching for new, stronger evidence are corrected; the rest are killed and logged in a transparent ledger.
Honest naming. It's GAN-shaped, not a real GAN — there is no gradient or training. The "generator" objective is inverted: instead of rewording a claim until the critic stops complaining (which optimizes for slippery, unfalsifiable claims), the generator must correct the claim toward the evidence or concede. See Adversarial verification below.
Why a workflow of subagents instead of one big prompt?
A single agent doing deep research hits three walls. This architecture is designed around all three:
- Context window. The volume of fetched source text in a real research task overflows even a 1M-token context. Here, each search subagent writes its full brief to disk (
raw/Sx.json) and returns only a few bytes of control-flow metadata to the orchestrator. The leader's context never holds all the source material at once. - Long-context degradation & hallucination. Model quality degrades and hallucination rises as a context fills up. Short-lived, single-purpose subagents each work in a small, clean context.
- Wall-clock. The sub-topics are researched in parallel. What would be a many-hour serial crawl finishes in the time of the slowest single branch.
The trade-off is honest and deliberate: this is expensive. It is optimized for quality and wall-clock, not for token cost. A broad topic with adversarial verification on can make 100+ agent calls and burn several hundred thousand tokens in one run.
Architecture
┌─────────────────────────────────────────────────────────────┐
│ orchestrator (you / the main agent) │
│ pre-captures what a sandboxed script can't: slug, temp dir, │
│ cost baseline, run-start ms — then fires the workflow │
└───────────────────────────────┬─────────────────────────────┘
│ Workflow({ name:'deep-research-harness', args })
▼
┌────────┐ ┌───────────────────┐ ┌────────┐ ┌──────────┐ ┌───────────┐ ┌──────────────────────┐ ┌────────┐
│ 1 Plan │──▶│ N Search │──▶│ Critic │──▶│ Gap-fill │──▶│ Synthesis │──▶│ Adversarial Verify │──▶│ Render │
│ leader │ │ parallel, │ │ gap │ │ 0–3 │ │ 1 agent, │ │ + Reconcile │ │ HTML │
│ N ≥ 8 │ │ 1 subagent/topic, │ │ finder │ │ targeted │ │ marks │ │ (GAN-shaped, ON by │ │ + cite │
│ │ │ writes brief→disk │ │ │ │ refills │ │ claims │ │ default) │ │ pool │
└────────┘ └───────────────────┘ └────────┘ └──────────┘ └───────────┘ └──────────────────────┘ └────────┘
│ │ │
raw/plan.json raw/Sx.json ✕N raw/verify.json
The stages
| Stage | Agents | What it does |
|---|---|---|
| Plan | 1 | Decomposes the topic into N ≥ 8 narrow, non-overlapping, web-searchable sub-topics. Captures the cost baseline. Scans raw/ to resume a prior run. |
| Search | N (parallel) | One rigorous fact-aggregation subagent per sub-topic. Runs WebSearch/WebFetch, extracts evidence quotes, cross-checks confidence, and writes a structured brief to raw/Sx.json — returning only metadata. |
| Critic | 1 | Fresh-context gap analyst. Reads every brief and finds coverage gaps, weak (single-source) evidence, contradictions, staleness, and failed sub-topics. Not a score — a hunt for holes. |
| Gap-fill | 0–3+ | Conditionally re-runs the search agent against the most severe gaps: all fatal gaps, plus the most severe major gaps up to 3 total (so an all-fatal run can exceed 3 — fatal is meant to be rare). |
| Synthesis | 1 | Merges all briefs into a markdown report, resolves contradictions by source quality, and marks the load-bearing claims the conclusions actually hang on. |
| Adversarial Verify + Reconcile | many | The GAN-shaped stage (below). On by default. Patches the synthesis and writes a verify.json ledger. |
| Render | 1 | Builds a global citation pool (dedup + global numbering), renders the report into the chosen HTML template, and fills the cost/wall-clock panel. One self-contained HTML file out. |
Adversarial verification (the GAN-shaped stage)
Only load-bearing claims that are weak-evidence or below high confidence are attacked (single-source / community-only / inferential, or merely medium/low); strong, high-confidence claims are skipped. Capped at adversarialMaxClaims (default 8).
Synthesis marks load-bearing claims
│ select (load-bearing × weak-evidence), cap N
▼
R1 refute-panel per claim, 3 independent lenses:
│ ① attribution — does the cited source actually contain this?
│ ② counter — is there a standing counter-example / better reading?
│ ③ overclaim — is it stronger than the evidence, or narrowed to a truism?
│ majority refute ⇒ claim is "attacked"
▼ attacked
Generator correct WITH new/stronger evidence, OR concede.
│ (rewording or same/weaker evidence ⇒ forced concede)
▼ corrected
R2 refute-panel re-run the SAME panel on the revised claim.
│ no 2nd correction allowed — it stands or it dies.
▼
Ledger: ✅ confirmed ✏️ corrected (+new evidence) ❌ refuted (+reason)
│
▼
Reconcile agent patches synthesis.md and writes verify.json
The five teeth that keep this from degenerating into "argue until the critic gives up":
- A correction must ship a new/stronger evidence quote, or it's forced to concede.
- One correction per claim, max. A corrected claim that's still refuted dies — no narrowing-to-a-truism ratchet.
- The adversarial pass can confirm, downgrade, or kill — never upgrade confidence past source quality. (The refuters are imperfect LLMs; surviving ≠ true. It's a culler, not a confidence pump.)
- Only load-bearing × weak-evidence claims are spent on panels.
- Fail-closed: a claim is only "confirmed" with a quorum of real verdicts that are majority-confirm. If a lens agent errors or returns nothing, the claim is routed to correct-or-concede, never silently passed.
Requirements
- Claude Code with the Workflow (dynamic workflow) tool available. The harness is a JS workflow script executed by Claude Code's workflow runtime — not by Node directly. (
nodeis only useful for--checksyntax validation; see below.) - Subagents need the
WebSearchandWebFetchtools. python3(for a reliable epoch-ms; macOSdate +%s%3Nis broken).- (optional, for the cost panel only)
jqplus aclaude usage --jsonthat emits the ccusage JSON schema (.daily[].totalCost). On the author's machineclaude usageis a shell wrapper around ccusage; the cost query is hard-coded to that shape. Without ccusage (or a wrapper that produces it) the cost panel just shows "no cost data" — nothing else depends on it.
⚠️ This repo's main file is named
deep-research-harnesson purpose — do not register a workflow nameddeep-research, which would collide with Claude Code's own built-indeep-researchharness.
Install
git clone https://github.com/Justaboringname/deep-research-harness
cd deep-research-harness
# 1. put the workflow where Claude Code scans for them
cp deep-research-harness.js ~/.claude/workflows/
# 2. point the script at the templates dir — EITHER edit the constant:
# DEFAULT_TEMPLATES_DIR = '/abs/path/to/deep-research-harness/templates'
# OR pass args.templatesDir at call time (see Usage).
# 3. (optional) install the skill so the orchestrator steps are documented in-tool
cp -r skill ~/.claude/skills/deep-research-harness
The named-workflow registry is scanned once at session start, so a freshly-copied file isn't callable by name until the next session. In the same session, call it by scriptPath instead (see Usage).
Usage
A sandboxed workflow script can't run shell, so the orchestrator (you, or your SKILL.md) pre-captures a few values first:
TOPIC="<your research question>"
TODAY=$(date +%F)
SLUG="<ascii-safe-slug>" # e.g. "http2-vs-http3"
WORK="/tmp/deep-research/$TODAY-$SLUG"; mkdir -p "$WORK/raw"
HTML_OUT="$HOME/Downloads/$TODAY-$SLUG.html"
RUN_START_MS=$(python3 -c "import time;print(int(time.time()*1000))")
Then fire the workflow (fire-and-forget — you get a completion notification):
Workflow({ name: 'deep-research-harness', args: {
topic: TOPIC,
outDir: WORK,
htmlOut: HTML_OUT,
templatesDir: '/abs/path/to/deep-research-harness/templates', // if you didn't edit the constant
runStartMs: RUN_START_MS,
topicLanguage: 'zh', // language of the report prose; JSON keys stay English. use 'en' for English.
style: 'claude', // claude | minimal | academic | magazine
adversarial: true // GAN-shaped verify — on by default; pass false to skip
}})
// first-session fallback (registry not yet scanned):
// Workflow({ scriptPath: '/abs/path/to/deep-research-harness/deep-research-harness.js', args: { …same… } })
On the completion notification: ls "$HTML_OUT" to confirm, open it, then rm -rf "$WORK" — the HTML is self-contained (it embeds the full dataset in a <script type="application/json"> block, so it can be re-rendered later without the temp files).
Key args
| arg | required | default | meaning |
|---|---|---|---|
topic | ✅ | — | the research question |
outDir | ✅ | — | abs path of a temp work dir (raw/ lives inside; deletable after) |
htmlOut | outDir/index.html | abs path of the final single HTML | |
templatesDir | DEFAULT_TEMPLATES_DIR const | abs path of this repo's templates/ | |
runStartMs | plan agent captures it | epoch-ms at run start, for the wall-clock panel | |
topicLanguage | zh | language of human-readable text | |
style | claude | template: claude / minimal / academic / magazine | |
nMin | 8 | sub-topic floor | |
nMax | none | sub-topic ceiling (omit for topic-driven, no cap) | |
adversarial | true | run the GAN-shaped verify stage | |
adversarialMaxClaims | 8 | cap on claims sent to refute-panels |
Design principles
- Zero-baseline. Every run is standalone. Subagents are told not to anchor on prior reports or "known conclusions" — the defense against confirmation bias compounding across runs (a hallucinated source in run A becoming "verified fact" in run C). Feed objective inputs (dates, known facts) freely; just don't anchor on prior conclusions.
- Subagent-writes-raw. Bodies go to disk; only control-flow metadata crosses agent boundaries (via JSON-Schema-validated returns). This is what keeps the orchestrator's context small.
- Source-quality heuristics. A 5-tier ladder (primary academic → official/first-party → established secondary → community → SEO content farm).
highconfidence requires ≥2 independent sources, ≥1 primary/official, and a real fetched evidence quote. SEO farms are barred from being primary support; citation frequency ≠ accuracy. - No silent caps. Sub-topic count is topic-driven with no upper limit. The Claude Code workflow runtime — not this script — bounds how many subagents run concurrently and runs the rest in waves, so adding sub-topics past that bound buys coverage, not speed (see Concurrency & cost reality). The pipeline aborts (keeping partial
raw/) if ≥ceil(N/2)sub-topics come back empty/failed. - Resume-aware. The plan agent scans
raw/for completed briefs and skips them; combined with the runtime's nativeresumeFromRunId, an interrupted run can continue.
Concurrency & cost reality
The Claude Code workflow runtime — not this script — bounds how many subagents run concurrently. At the time of writing that bound is min(16, cores−2) (e.g. ~8 on a 10-core machine), but it's a property of the runtime and may change across versions. All N sub-topics are spawned at once; the extras queue and run as slots free. So:
- "No sub-topic cap" is true, but finer slicing only speeds things up within that concurrency bound — beyond it you're buying coverage, and wall-clock can grow.
- Expect ~100k–400k+ tokens and dozens to 100+ agent calls per run on a broad topic with adversarial on. This is the cost of the quality; it is not optimized away.
Templates
Four self-contained HTML templates in templates/ ({{PLACEHOLDER}}-based, no build step):
claude— hand-drawn, warm "Claude" aesthetic (the default).minimal— clean and plain.academic— paper-like.magazine— editorial layout.
The report is data-self-contained — it embeds the full dataset in a <script type="application/json"> block, so it re-renders without the temp files. (Note: the claude and magazine templates pull web fonts from Google Fonts at view time and fall back to system fonts offline; academic and minimal use no font CDN.)
See examples/sample-report.html for a rendered sample (from the synthetic dataset in adapters/example-harness-output.json).
Optional: rendering Claude's built-in harness
Claude Code ships its own built-in deep-research workflow. If you'd rather use that as the research engine but still want this repo's nicely-rendered HTML report, adapters/built-in-harness-render.js is a standalone render-only adapter that eats the built-in harness's output JSON. It is not needed by the main deep-research-harness.js (which renders itself in its Render stage). See adapters/README.md.
Hacking on it
The script uses top-level await and return, so a bare node --check mis-reports errors. Validate syntax by wrapping it in an async function first:
{ echo 'async function __wf(){'; sed 's/^export //' deep-research-harness.js; echo '}'; } > /tmp/chk.mjs
node --check /tmp/chk.mjs
License
MIT © 2026 Yihan Zhu
Built with Claude Code.