Model or dataset
dzhng/deep-research avatar
dzhng/deep-research

dzhng/deep-research: A Recursive Research Agent Aiming for Under 500 Lines

An AI-powered research assistant that performs iterative, deep research on any topic by combining search engines, web scraping, and large language models. The goal of this repo is to provide the simplest implementation of a deep research agent - e.g. an agent that can refine its research direction overtime and deep dive into a topic.

19,906 stars2,009 forksTypeScriptMIT

At a glance

What is it?
A TypeScript deep research agent that loops search queries, scrapes pages, and asks a model to extract learnings and new directions. The README states the goal is the simplest implementation of this pattern, and the design choices follow from that constraint.
Who is it for?
Adopt dzhng/deep-research if you want a readable reference for the recursive search loop and you already hold Firecrawl and OpenAI keys, or if you plan to point it at a local OpenAI-compatible endpoint. Do not adopt it if you need a hosted service, a stable CLI contract, or a system that runs without a scraping vendor.
Can I use it commercially?
Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Activity is slowing. The repository last received commits 7 months ago.
What is it written in?
Mainly TypeScript, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • dzhng/deep-research19,906 ★ · +246
Star history
Repository2026-09-122026-11-15
dzhng/deep-research19.7k19.9k

246 Stars in the last 64 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

The gap this fills: a research loop you can read in one sitting

Search APIs return links. A model summarizing those links returns a single pass. Neither refines its own question. dzhng/deep-research targets the loop between those two: generate queries, scrape results, ask a model what was learned and what to ask next, then repeat. The README frames the audience directly by stating the goal is to keep the repository under 500 lines of code so it is easy to understand and build on top of. That is the design brief. The intended user is an engineer who wants to see the whole agent, modify the prompts, and swap providers without reading a framework. If you want a product, this is the wrong shape. If you want a working skeleton of iterative research, the size constraint is the feature.

The recursion: SERP queries, learnings, directions, depth counter

The flowchart in the README shows the data flow plainly. A user query plus a breadth parameter and a depth parameter enter the Deep Research step. That step produces SERP queries, which are executed and then processed. Processing yields two separate outputs: learnings and directions. A decision node checks whether depth is greater than zero. If yes, the next direction is assembled from prior goals, new questions and accumulated learnings, and that bundle is fed back into Deep Research as new context. If no, the loop exits and the system emits a markdown report. Two details matter here. First, learnings and directions are distinct artifacts, so the model is asked both to compress what it read and to propose where to look next. Second, breadth and depth are separate knobs: breadth controls how many queries go out per round, depth controls how many rounds happen. The README recommends breadth 3 to 10 with a default of 4, and depth 1 to 5 with a default of 2. Those defaults are modest, which suggests the author expects cost and latency to bite before quality does.

Setup: two keys, a .env.local file, and the Fireworks switch

The README gives a Node.js path and a Docker path. For Node: clone the repository, run npm install, then create a .env.local file containing FIRECRAWL_KEY and OPENAI_KEY. Firecrawl handles both search and content extraction, so there is no separate search provider to configure. For a self-hosted Firecrawl instance, the README shows an optional FIRECRAWL_BASE_URL pointing at http://localhost:3002. To run against a local model instead of OpenAI, you comment out OPENAI_KEY and uncomment OPENAI_ENDPOINT (for example http://localhost:1234/v1) and OPENAI_MODEL. Two further optional variables exist for OpenAI-compatible providers: OPENAI_ENDPOINT and CUSTOM_MODEL. There is also a provider switch that is easy to miss: setting FIREWORKS_KEY makes the system automatically use DeepSeek R1 instead of o3-mini. The Docker route renames .env.example to .env.local, builds with docker build -f Dockerfile, starts with docker compose up -d, and runs the agent inside the container with docker exec -it deep-research npm run docker. The interactive run itself is npm start, which prompts for the query, breadth, depth, and follow-up questions, and writes report.md or answer.md into the working directory depending on the mode selected.

Concurrency is the first thing that will break

The README is explicit that CONCURRENCY_LIMIT controls how many searches and result-processing jobs run at once, and that raising it is only sensible on a paid Firecrawl plan or a self-hosted instance. On the free tier it warns that rate limit errors appear, and the documented remedy is to drop the limit to 1, which the README itself describes as running a lot slower. This is the honest failure mode of the project. The agent's value comes from fanning out across many queries per round, so the moment the scraping vendor throttles you, the recursion either stalls or degrades into serial requests. There is no built-in retry policy described, no backoff configuration, and no partial-result handling mentioned. A second constraint follows from the architecture: every round passes prior goals, new questions and learnings back into the model as context, so token usage grows with depth even when breadth stays fixed. The README gives no cost estimate and no token accounting, so the only way to know what a depth-5 run costs is to run it.

What it is not: no releases, no CLI contract, no library surface

The repository has no published releases and no homepage, and the README documents a single interactive entry point rather than a programmatic API. The README does not describe importing the agent as a module, exposing a function, or returning structured output to a caller. The interactive run's output is a markdown file on disk, although package.json also defines an `api` script that runs src/api.ts and lists express and cors as dependencies, so check that file before ruling out programmatic use. It is a poor fit for anyone who wants to pin a version: with no tags, you track the main branch. The licence is MIT, which is permissive and imposes no obligations beyond retaining the notice, but the README does not discuss the terms of the services it depends on. Firecrawl and OpenAI each carry their own terms and billing, and self-hosting Firecrawl moves that cost onto your own infrastructure. None of this is a defect in a reference implementation. It is a defect if you were hoping to drop it into production unchanged.

Where it sits next to a general-purpose agent framework

The obvious comparison is to a general agent framework such as LangChain or LangGraph, where you would assemble a research loop from a retriever, a tool-calling agent and a state graph. The difference is not capability but where the structure lives. In a framework, the loop is something you configure and the framework supplies the abstractions, tracing and integrations. In dzhng/deep-research, the loop is the codebase: the flowchart in the README is close to a description of the program, and the sub-500-line target means there is no abstraction layer between you and the prompts. That is a real advantage when the loop itself is what you are trying to understand or modify, and a real disadvantage when you need retries, observability or multi-tenant isolation, because you will write those yourself. The README also links a Python port, deep-research-python, for teams whose stack is not Node, which is worth noting since the two implementations are not described as sharing a test suite or a compatibility guarantee.

Editorial conclusion

Adopt dzhng/deep-research if you want a readable reference for the recursive search loop and you already hold Firecrawl and OpenAI keys, or if you plan to point it at a local OpenAI-compatible endpoint. Do not adopt it if you need a hosted service, a stable CLI contract, or a system that runs without a scraping vendor. Before you commit, verify the current Firecrawl rate limits against your plan, confirm which model the run will actually use after the FIREWORKS_KEY switch, and check whether the CONCURRENCY_LIMIT default survives your first run.

Frequently asked questions

What is deep research, in this repository?

It is an iterative loop. A user query plus a breadth and a depth parameter generate search queries through Firecrawl, results are processed into Learnings and new Directions, and while depth is above zero each Direction starts another round carrying prior goals and new questions. The run ends in a markdown report with sources.

Is deep research free?

The code is free to read, copy, and modify under the license the project states, but running it needs a Firecrawl key for web search and content extraction and an OpenAI key for the o3 mini model. On a free Firecrawl version you may hit rate limit errors, and the documented fix is to set the concurrency limit to 1, which runs a lot slower.

What does dzhng deep-research need to run?

A Node.js environment, an npm install, and a .env.local file holding FIRECRAWL_KEY and OPENAI_KEY. package.json declares engines node 22.x, and the run itself is started with npm start, after which you are prompted for a query, a breadth from 3 to 10 defaulting to 4, and a depth from 1 to 5 defaulting to 2.

Can deep-research use a local model instead of OpenAI?

Yes. The setup instructions say to comment out OPENAI_KEY and set OPENAI_ENDPOINT to the address of your local server, for example http://localhost:1234/v1, along with the model name variable. The setup text calls that variable OPENAI_MODEL while the .env.example file uses CUSTOM_MODEL.

How do I run DeepSeek R1 with deep-research?

Set FIREWORKS_KEY in the environment file. Fireworks is the main provider for the R1 model, and the system automatically switches over to R1 instead of o3-mini when the key is detected.

Where does the deep-research report end up?

It is saved in your working directory as report.md or answer.md, depending on which modes you selected. The README does not say which mode produces which filename, and a sample report.md is committed at the repository root, so a run started there overwrites it.

Official sources

  1. dzhng/deep-research on GitHub
  2. Issues
  3. License: MIT
  4. README
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/dzhng-deep-research.svg)](https://hysenlabs.com/projects/dzhng-deep-research)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/dzhng-deep-research.svg)](https://hysenlabs.com/projects/dzhng-deep-research)

Was this useful?