hoolulu/deep-research: a /research skill that turns one command into a citable report
Professional deep research report generation Skill — one command, ten minutes, broker-grade deep research / 深度调研报告生成 Skill — 一条命令，十分钟出券商级深度调研报告
At a glance
- What is it?
- hoolulu/deep-research is a Python-based Skill that runs a four-stage research pipeline inside any AI coding tool, producing a sourced report in about ten minutes. Here is how it installs, how the search layers work, and where it stops being the right tool.
- Who is it for?
- Adopt hoolulu/deep-research if you already work inside an AI coding tool and need a structured, source-linked report rather than a chat answer, and if you accept that the pipeline depends on your tool's built-in search plus Scrapling fetching. Skip it if you need a hosted service with a support contract, or if your topic requires paywalled databases the free fallback layer cannot reach.
- 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?
- Yes. The repository last received commits 19 days ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 17, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The gap hoolulu/deep-research is aimed at
Ask a chat model to research a market and you get a handful of bullet points with no provenance. Buy an industry report and you pay $50 to $500 or more for one document. The README frames the project as the middle path: a Skill that produces what it calls institutional-grade research for indie developers, independent researchers and small teams, without a paid database subscription.
The design target is explicit. The README says reports are benchmarked against institutional research structure: conclusions-first, traceable sources, counter-arguments, scenario forecasting. It also claims an advantage for Chinese-language work, since the project says overseas tools cannot search sources like Baidu Baike, Zhihu, 199IT and iResearch. That is a positioning claim, not a measured result, and the README offers no comparison run against those tools.
The intended audience is narrow enough to be useful. If you are writing an investment memo, a competitive scan or a policy brief and you already live in a coding tool, this is built for that workflow. If you want a hosted product with an SLA, it is not.
The four-stage pipeline and its four-layer search
The README documents a pipeline of four automated stages. Stage one analyzes the topic and generates a research framework plus a search plan. Stage two collects data, either online or offline. Stage three writes all chapters in parallel, and the README notes it falls back to sequential writing when the host tool has no multi-agent support, with facts embedded directly in the prompts rather than fetched through tool calls. Stage four validates in batch, then runs assemble-report, convert-citations, escape-currency and qa-report.
Search is the part worth reading twice. It uses a four-layer priority strategy, all issued in parallel. Layer 0 is the tool's built-in engine, auto-detected at runtime, with websearch or web_search named as examples. Layer 1 is outline-suggested sources, topic-targeted recommendations such as arctic-council.org. The README is truncated before the remaining layers, but the repository carries a sources.json at the top level, which the README names as a layer, plus a free fallback layer.
Fetching is handled by Scrapling, which the README says runs locally at zero cost. Offline mode bypasses search entirely: PDF, DOCX, TXT and MD files are read directly into the data pool. That offline path is the most defensible part of the design, because it removes the network as a failure point.
Installing it and running a first report
The repository is a Skill, not a pip package. Its top level holds SKILL.md, RULES.md, TYPES.md, VERSION, profiles.json, sources.json, a command/ directory, prompts/, tools/, reports-browser/ and scrapling-mcp-server.py. The README's install story is that the Skill works with any AI coding tool, listing Claude Code, Codex CLI, Cursor, DSH, Windsurf and Cline. The README does not give a step-by-step install command, so the practical route is to clone the repository into the location your tool reads Skills from.
git clone https://github.com/hoolulu/deep-research.gitOnce the Skill is available to the tool, research is a single command with the topic as its argument. The README gives these examples, and the report language follows the language of the topic rather than a separate setting.
/research 中国新能源汽车产业发展现状
/research Competitive landscape of AI cloud computing
/research Анализ рынка нефти и газа в РоссииThe last example should produce a Russian report. The README states the tool interacts with you entirely in the language you set and searches for materials in that target language, and that it is not a translation pipeline. After a run, the README says a local browser page is refreshed automatically at reports-browser/index.html, where you can search, filter, sort and preview, and export to PDF or DOCX from the preview modal. The README describes that export as fully client-side with no server required.
What a standard run is supposed to produce
The README publishes ranges for standard mode rather than a single figure: 500 to 700 lines, roughly 12,000 to 20,000 characters, 15 to 25 data tables, and 80 to 120 analysis paragraphs, each described as carrying conclusion plus data plus causation plus judgment. It also claims 15 to 25 unique sources and 3 to 8 opposing viewpoints, with at least one controversy per chapter.
Those numbers come from the project's own documentation, not from an independent run, and the README hedges them: actual times vary by topic complexity and data availability. Treat the structure as the real promise. A report that must carry a counter-argument in every chapter is a different artifact from a chat summary, and that constraint is what the writing prompts are built around.
Cost is documented per tier. The README estimates a DeepSeek v4 Flash baseline at roughly 100 to 150k tokens for quick, 150 to 300k for standard and 300 to 500k for deep, with dollar figures under $0.03, $0.06 and $0.10. It cites the DeepSeek pricing page as the basis and notes actual cost varies with cache hit rate.
Where the pipeline breaks down
The dependency on Layer 0 is the sharpest limitation. If your AI tool has no built-in search engine, or exposes one under a name the runtime does not detect, the top layer is empty and the pipeline falls through to suggested sources, sources.json and the free fallback. The README does not document what happens when all four layers return nothing for a topic, and it does not describe a rollback path for a run that produces an unusable report.
Quality tracks source availability. A niche B2B topic with little public material will not yield 15 to 25 unique sources no matter how the prompts are written, and the README's own caveat about data availability is doing a lot of work there. Paywalled research sits outside the free fallback layer by definition.
The language claim also deserves scrutiny. Searching in the target language is harder than generating in it, and the README asserts the behavior without publishing a per-language quality breakdown across the 19 languages it claims. If your report must be in, say, Turkish, you are trusting an unverified claim.
Finally, the time budget. Quick mode is listed at 8 to 12 minutes and standard at 10 to 15, with total time up to about 20 minutes. That is a real cost when you are iterating on a topic and want to try five framings.
How it differs from a hosted deep research mode
The obvious alternative is the deep research mode built into a hosted assistant, which the search data shows people asking about by name. The architectural difference is where the work runs. A hosted mode is a closed pipeline: you supply the topic, the vendor supplies the search index, the retrieval and the synthesis, and you cannot inspect or replace a stage.
hoolulu/deep-research inverts that. The stages are files in the repository. SKILL.md defines the Skill, prompts/ holds the writing instructions, sources.json holds a source layer you can edit, and tools/ plus scrapling-mcp-server.py handle fetching. You can point Layer 1 at your own preferred domains, or run entirely offline against local PDFs and DOCX files, which a hosted mode will not do.
That flexibility costs you the vendor's search infrastructure. A hosted mode typically has a proprietary index behind it; this project borrows whatever engine your coding tool already has and adds Scrapling on top. The trade is control and local file access against retrieval depth you did not have to build.
Licence, maintenance and upgrade cost
The project is MIT licensed, and the repository carries a LICENSE file at the top level. MIT permits commercial use and modification provided the copyright notice and permission notice are retained; that is a summary of the licence text, not legal advice, and you should read the LICENSE file yourself before shipping anything derived from it.
The last push to the repository was on 2026-08-30, and the project is not archived. The release history shows v6.0.0 on 2026-08-27, described as platform-agnostic with one skill for every AI tool, following v5.1.3 and v5.1.2 the same day. Rapid minor releases on a single day suggest active iteration rather than a frozen artifact, but the README does not document a migration path between major versions, so a v5 to v6 upgrade may require re-reading SKILL.md and RULES.md rather than following a changelog.
Upgrade cost is mostly in the prompts. If you have customized prompts/ or sources.json for your domain, a new release can overwrite those files. The README does not describe a merge strategy, so version-pinning your fork is the safer pattern.
Editorial conclusion
Adopt hoolulu/deep-research if you already work inside an AI coding tool and need a structured, source-linked report rather than a chat answer, and if you accept that the pipeline depends on your tool's built-in search plus Scrapling fetching. Skip it if you need a hosted service with a support contract, or if your topic requires paywalled databases the free fallback layer cannot reach. Before relying on it, verify the license file against the repository LICENSE entry, confirm your AI tool exposes a websearch or web_search capability, and run one quick-tier topic end to end so you can inspect the citation list it produces.
Frequently asked questions
What is hoolulu/deep-research?
It is an MIT-licensed Skill that generates deep research reports inside an AI coding tool. The README describes a four-stage pipeline that analyzes a topic, collects data, writes chapters in parallel and then validates and assembles the report.
Is hoolulu/deep-research free to use?
The Skill itself is MIT licensed and the README lists Scrapling fetching, domestic sources and AI tool runtime as zero cost. Your LLM usage is not free: the README estimates a DeepSeek v4 Flash baseline of under $0.03 for quick mode and under $0.10 for deep mode.
How do I use deep research in Claude?
With this project, you make the Skill available to your tool and then run /research followed by a topic, for example /research Competitive landscape of AI cloud computing. The README lists Claude Code among the supported tools and says the report is generated in the language of the topic.
Community notes