Deep research agent, shallow codebase

What it does

deep-research takes a topic, plus breadth and depth parameters, and recursively searches the web via Firecrawl. After each round of scraping, an LLM extracts learnings and decides which new questions deserve a deeper dive. The loop continues until the depth counter hits zero, at which point it compiles a markdown report with sources. The entire agent is intentionally kept under 500 lines of TypeScript so you can trace the logic without drowning in abstractions.

The interesting bit

Most agent frameworks arrive with orchestrators, memory layers, and plugin architectures; this project throws all of that away and simply loops: search, read, reflect, recurse. The depth and breadth parameters turn an open-ended LLM wander into a bounded tree search, which is exactly the kind of boring constraint that keeps costs and hallucinations from spiraling.

Key highlights

• Recursive research loop: generates queries, processes results, and spawns follow-up directions until depth reaches zero.
• Configurable breadth and depth parameters to control how wide the initial search spreads and how many recursive layers it drills.
• Swappable LLM backends: defaults to OpenAI o3-mini, but auto-switches to DeepSeek R1 via Fireworks or accepts any OpenAI-compatible local endpoint.
• Concurrent search and processing via Firecrawl, with an adjustable CONCURRENCY_LIMIT.
• Outputs a compiled markdown report (report.md or answer.md) citing sources.

Caveats

• Free Firecrawl tiers hit rate limits quickly; the README warns you’ll need to drop the CONCURRENCY_LIMIT to a single thread, which slows the loop considerably.
• Local LLM support is mentioned but underspecified: the README only says to point an OPENAI_ENDPOINT at a local server without detailing model size or context-window requirements.

Verdict

Grab this if you want to understand how recursive research agents work under the hood without parsing a framework’s plugin registry. Skip it if you need production-grade error handling, authentication, or a no-code interface; this is a teaching skeleton, not a shipped product.