hyperresearch: biến Claude Code và Codex thành trợ lý nghiên cứu sâu — hướng dẫn cài đặt và dùng
Bài này là một góc nhìn khác về jordan-gibbs/hyperresearch — repo từng đổi tên nên mình viết lại với cách tiếp cận khác. Bài hướng dẫn chính: hyperresearch: biến Claude Code và Codex thành agent nghiên cứu sâu — hướng dẫn cài đặt và dùng →

Tóm tắt nhanh
hyperresearch là một skill kèm gói Python cho Claude Code và OpenAI Codex. Nó biến một câu hỏi thành báo cáo nghiên cứu có kiểm chứng trích dẫn, và lưu mọi nguồn đã đọc vào một kho (vault) tìm kiếm được. Cài bằng pip và một lệnh install, khá đơn giản nếu bạn đã có sẵn Claude Code hoặc Codex.
hyperresearch là một skill (kèm gói Python) giúp Claude Code, và cả OpenAI Codex, làm nghiên cứu sâu: bạn đưa một câu hỏi, nó đi tìm nguồn trên web, đọc, đối chiếu rồi viết thành báo cáo có trích dẫn. Mọi nguồn nó đã đọc được lưu vào một "kho" (vault) gồm file markdown và SQLite, nên lần nghiên cứu sau không phải bắt đầu từ số không.
Bạn nên xem repo này nếu hay phải làm việc kiểu "so sánh ba đối thủ", "đánh giá một thương vụ", "tổng hợp tài liệu về một chủ đề". Chủ shop, nhân viên phân tích, người làm nghiên cứu thị trường hay lập trình viên mới đều dùng được, miễn là bạn đã dùng Claude Code hoặc Codex.
Điểm đáng giá nhất là khâu kiểm tra. Báo cáo không chỉ được viết ra: có bốn "nhà phê bình" chạy song song để bắt lỗi, và một bước kiểm tra xem mỗi nguồn được trích có thật sự ủng hộ câu văn đi kèm hay không. Tác giả cho biết bản trả phí chạy trên máy chủ của họ đứng đầu bảng DRACO (một bộ đánh giá nghiên cứu sâu) với 77.7 điểm trên 10 tác vụ. Bài này nói về bản mã nguồn mở, bạn tự cài và tự chạy. Repo hiện có khoảng 4712 sao và 490 fork, dùng giấy phép MIT.
jordan-gibbs/hyperresearch
Skill và gói Python biến Claude Code hoặc Codex thành trợ lý nghiên cứu sâu: đọc hàng trăm nguồn, kiểm tra trích dẫn, lưu vào kho tri thức dùng lại được.
I.hyperresearch làm được gì
Dưới đây là những tính năng đáng quan tâm nhất với người dùng thật, chọn từ README:
- Quy trình 16 bước, tự chọn mức công sức. Câu hỏi đơn giản đi đường ngắn khoảng 30–40 phút. Câu hỏi cần phân tích sâu chạy đủ các bước, khoảng 1,5–2,5 giờ theo README. Bạn không phải tự chia việc.
- Đọc nhiều nguồn. Một lượt chạy có thể thu thập hơn 250 nguồn ở cấu hình cao nhất (profile
premier). Nhiều nguồn hơn thường nghĩa là ít bỏ sót góc nhìn hơn. - Kiểm tra trích dẫn trước khi giao báo cáo. Một bước "cite-check" xét từng nguồn có thật sự nói điều báo cáo gán cho nó không. Trích dẫn bịa hoặc nguồn đã bị rút lại bị chặn ở cổng cuối.
- Không tính bản sao thành đồng thuận. Nếu năm trang chỉ đăng lại cùng một thông cáo báo chí, hệ thống coi đó là một nguồn, không phải năm.
- Chỉ sửa nhỏ, không viết lại. Sau khi có bản nháp, chỉ có các chỉnh sửa từng đoạn nhỏ. Cách này tránh tình trạng "sửa mãi thành bản khác".
- Tìm tài liệu học thuật. Lệnh
hpr scholar searchtìm qua tám nguồn học thuật (README liệt kê OpenAlex, Crossref, CORE, DOAB, ClinicalTrials.gov, SEC EDGAR, FRED...) và gộp kết quả, loại trùng theo DOI và tiêu đề. - Đọc bản toàn văn hợp pháp khi có thể. Với bài báo trả phí, thay vì chỉ lưu phần tóm tắt, nó hỏi Unpaywall, Europe PMC và CORE để tìm bản mở hợp pháp. Mọi lần thay thế đều được ghi rõ.
- Chạy hỏng thì chạy tiếp. Mỗi lượt chạy có một bản ghi tiến độ, lệnh
run resumetiếp tục từ đúng bước bị dừng. - Chọn giọng văn báo cáo. Bạn có thể để hệ thống tự đoán, hoặc nói thẳng trong câu hỏi: "dạy mình về X" (giải thích), "bức tranh toàn cảnh" (khảo sát), phân tích (mặc định) hay bảo vệ một luận điểm.
II.Cần chuẩn bị gì
Theo tư liệu, bạn cần:
- Python 3.11 đến 3.14. File
pyproject.tomlghi>=3.11,<3.15. - Claude Code hoặc OpenAI Codex CLI đã cài sẵn. hyperresearch là phần bổ sung cho hai công cụ này, không chạy một mình.
- Một thư mục dự án để cài vào. README hướng dẫn cài theo từng dự án.
- Với Codex: phiên làm việc phải được cho phép ghi file và truy cập mạng (xem phần cài đặt).
README phần được cung cấp không nói gì về hệ điều hành cụ thể, phần cứng hay GPU, và không yêu cầu thêm API key riêng cho hyperresearch. Bạn vẫn cần tài khoản hoặc quyền dùng Claude Code hay Codex của chính mình. Muốn chắc về chi tiết khác, hãy xem README và thư mục docs/ trong repo.
Một lượt nghiên cứu sâu chạy nhiều subagent song song và đọc hàng chục đến hàng trăm nguồn, nên có thể dùng khá nhiều lượt sử dụng của tài khoản Claude Code hoặc Codex. Hãy thử với câu hỏi nhỏ trước, và kiểm tra gói cước của bạn.
III.Cài đặt từng bước
- Mở terminal trong dự ánVào đúng thư mục bạn muốn nghiên cứu
- Cài gói Pythonpip install hyperresearch
- Cài skill vào dự ánhyperresearch install (Claude Code) hoặc thêm --target codex
- Mở lại Claude Code hoặc CodexĐể nó nhận skill mới
- Gọi skill/hyperresearch rồi gõ câu hỏi của bạn
A.Mở terminal trong thư mục dự án
Cách cài chính của README là cài theo từng dự án. Bạn hãy mở terminal (PowerShell, Terminal...) rồi đi vào thư mục làm việc của mình:
cd your-projectThay your-project bằng tên thư mục thật của bạn. Chỗ người mới hay vấp: cài sai thư mục thì skill sẽ nằm ở dự án khác, mở Claude Code ở chỗ này sẽ không thấy.
B.Cài gói Python
pip install hyperresearchLệnh này tải gói hyperresearch và tạo lệnh hyperresearch trong terminal. Nếu máy báo không có pip, bạn cần cài Python 3.11 trở lên trước.
Lưu ý: README cho biết hỗ trợ Codex nằm trong bản PyPI kế tiếp. Nếu bạn muốn dùng Codex mà bản trên PyPI chưa có, cài thẳng từ GitHub:
pip install git+https://github.com/jordan-gibbs/hyperresearchC.Cài vào Claude Code hoặc Codex
Với Claude Code:
hyperresearch install # Claude Code, then: /hyperresearchVới OpenAI Codex:
hyperresearch install . --target codex # OpenAI Codex, then: $hyperresearchREADME cho biết --target all cài cả hai phiên bản song song. Với Codex, lệnh này đặt skill vào .agents/skills/hyperresearch/, các subagent vào .codex/agents/, thêm một Stop hook trong .codex/hooks.json và một đoạn ngắn vào AGENTS.md.
Nếu bạn thích dạng plugin, README có sẵn các lệnh sau. Cách này cài một skill khởi động tên deep-research, và vẫn cần pip install hyperresearch ở trên.
Claude Code:
/plugin marketplace add jordan-gibbs/hyperresearch
/plugin install hyperresearch@hyperresearchCodex:
codex plugin marketplace add jordan-gibbs/hyperresearch
codex plugin add hyperresearch@hyperresearchHoặc cài như một skill đơn lẻ qua skills.sh:
npx skills add jordan-gibbs/hyperresearch -a claude-code
npx skills add jordan-gibbs/hyperresearch -a codexD.Khởi động Codex đúng cách
Nghiên cứu cần ghi file và vào mạng, mà Codex mặc định không cho cả hai. Vì vậy hãy mở Codex bằng lệnh sau, rồi gọi skill:
codex --sandbox workspace-write -c sandbox_workspace_write.network_access=true
# then, in the session:
$hyperresearchCác cờ này do bạn truyền vào, hyperresearch không tự sửa cấu hình Codex của bạn. Nếu chạy Codex không tương tác (codex exec), nó không thể hỏi bạn có tin các hook của dự án không, nên Stop hook sẽ không chạy trừ khi thêm cờ --dangerously-bypass-hook-trust. README dặn chỉ dùng cờ này cho các hook bạn đã đọc (file .codex/hooks.json).
E.Mở lại công cụ
Nếu Claude Code chưa nhận skill và subagent mới cài, hãy khởi động lại nó ngay trong cùng thư mục, rồi gõ /hyperresearch <câu hỏi>. Codex chỉ tìm skill khi bắt đầu phiên, nên lần đầu skill khởi động sẽ đọc thẳng skill vừa cài; các phiên sau gõ được $hyperresearch <câu hỏi>.
IV.Kiểm tra đã chạy được chưa
README không đưa ra một lệnh "kiểm tra cài đặt" riêng. Dưới đây là cách kiểm tra hợp lý dựa trên những gì có trong tư liệu:
- Trong terminal, chạy lệnh sau để xem các cấu hình (gear) hiện có. Nếu in ra danh sách, lệnh
hyperresearchđã chạy được:
hyperresearch profile list- Mở Claude Code trong thư mục dự án và gõ
/hyperresearchkèm một câu hỏi nhỏ, hoặc$hyperresearchtrong Codex. Nếu pipeline chạy, nó sẽ bắt đầu với bước phân rã câu hỏi. - Trong lúc chạy, xem tiến độ:
hyperresearch run status -jLệnh này cho bạn thấy bước 1 đã chọn những "cần gạt" nào (giọng văn, độ sâu...).
Theo README, câu hỏi gốc của bạn được lưu nguyên văn ở research/runs/<vault_tag>/query.md, và báo cáo cuối cùng là final_report.md. Thấy các file này xuất hiện là dấu hiệu tốt.
V.Dùng vào việc thật
Những tình huống dưới đây đều bám đúng khả năng README mô tả. Câu lệnh mẫu là ví dụ do mình soạn, bạn đổi nội dung theo việc của bạn.
A.Chủ quán so sánh phần mềm bán hàng
Bạn là chủ một chuỗi quán ăn và đang cân nhắc ba phần mềm POS. Thay vì đọc từng trang giá và đánh giá, bạn mở Claude Code trong thư mục "nghien-cuu-pos" và gõ:
/hyperresearch So sánh Toast, Square và Clover cho một chuỗi 5 nhà hàng: chi phí, tính năng, rủi ro khi chuyển đổi.README có một báo cáo mẫu cùng chủ đề (phân tích đối thủ POS, dựng chủ yếu từ hồ sơ SEC, 241 nguồn). Với câu hỏi dạng so sánh, hệ thống thường chọn đường nhẹ hơn. Bạn nhận một báo cáo có nguồn dẫn, và các nguồn đã đọc nằm sẵn trong kho để dùng lại cho câu hỏi sau.
B.Người mua doanh nghiệp nhỏ làm thẩm định
Bạn đang xem xét mua một doanh nghiệp dịch vụ và muốn hiểu về mức định giá, vay vốn, những điều cần thẩm định. Bạn ra lệnh rõ giọng văn để báo cáo không bị "phán" quá sớm:
/hyperresearch Mình muốn hiểu bức tranh tổng thể khi mua một doanh nghiệp dịch vụ cỡ nhỏ: các mức định giá thường gặp, cách vay vốn, những điểm cần thẩm định. Hãy khảo sát, chưa cần kết luận.Theo README, câu kiểu "bức tranh toàn cảnh" dẫn tới giọng survey: bản đồ của lĩnh vực mà không đưa ra phán quyết. README có một báo cáo mẫu tương tự về mua một doanh nghiệp HVAC (213 nguồn).
Báo cáo nghiên cứu chỉ đáng tin khi bạn kiểm tra được từng câu trích dẫn có thật sự đứng được hay không.
Ông T
C.Lập trình viên mới so sánh hai công nghệ
Bạn vừa vào một công ty cần chọn giữa hai nền tảng dữ liệu. Bạn muốn một bản phân tích có dẫn chứng chứ không phải ý kiến cảm tính. Bạn gõ câu hỏi, đặt thêm mức độ sâu cao hơn:
hyperresearch levers set <tag> inference_depth=deep --rerender # go deeper mid-runLệnh này (có trong README) cho phép đi sâu hơn ngay giữa lúc chạy. <tag> là mã của lượt chạy, bạn xem ở kết quả của hyperresearch run status -j. README có mẫu so sánh Snowflake với Databricks cho một công ty 2.000 người, tính chi phí năm đầu từ hồ sơ công bố và bảng giá.
D.Sinh viên hoặc người nghiên cứu cần tài liệu học thuật
Bạn đang viết một bài tổng quan và cần tìm sách, thử nghiệm lâm sàng và bài báo cùng lúc. Lệnh hpr scholar search tìm đồng thời trên nhiều nguồn học thuật và trả về một danh sách đã loại trùng. Kho còn cho phép lọc theo DOI, tạp chí, số lượt trích dẫn, tình trạng bị rút bài hay phiên bản bản thảo đã lấy về. Bạn xem thêm cách dùng chi tiết lệnh này trong docs/ của repo, vì phần README được cung cấp không nêu hết các tham số.
VI.Lỗi hay gặp và cách xử lý
A.Gõ /hyperresearch mà Claude Code không nhận
Thường do skill mới cài mà phiên đang mở chưa tải lại. Cách xử lý theo README: tắt Claude Code, mở lại trong cùng thư mục đã cài, rồi chạy /hyperresearch <câu hỏi>. Cũng kiểm tra bạn đã chạy hyperresearch install đúng thư mục dự án chưa.
B.pip báo sai phiên bản Python
Gói yêu cầu Python từ 3.11 đến dưới 3.15. Nếu máy bạn dùng Python cũ hơn hoặc quá mới, pip sẽ từ chối hoặc báo lỗi. Cài một phiên bản Python nằm trong khoảng đó rồi chạy lại.
C.Codex không tìm hoặc không ghi được file, không vào được mạng
Codex mặc định không cho ghi file và truy cập mạng. Hãy mở Codex bằng đúng lệnh ở phần cài đặt, với --sandbox workspace-write và network_access=true. Nếu không, pipeline không thể lưu nguồn hay tải trang.
D.Gọi skill trong Codex lần đầu không thấy
Codex chỉ phát hiện skill khi bắt đầu phiên. Lần đầu, skill khởi động sẽ đọc trực tiếp skill vừa cài. Từ các phiên sau, bạn có thể bắt đầu thẳng với $hyperresearch <câu hỏi>.
E.Chạy lâu hoặc bị ngắt giữa chừng
Chế độ đầy đủ mất khoảng 1,5–2,5 giờ, chế độ premier khoảng 3–5 giờ theo README, nên chuyện bị ngắt là dễ xảy ra. Hãy dùng lệnh run resume để tiếp tục từ đúng bước bị dừng thay vì chạy lại từ đầu. Xem tiến độ bằng hyperresearch run status -j.
F.Có trang web bị chặn, không tải được
Trên Claude Code, hệ thống có thể dùng một đường trình duyệt cho trang yêu cầu đăng nhập. Trên Codex thì không có đường này: các trang bị chặn nằm trong hàng đợi và thông điệp cuối sẽ liệt kê cho bạn. Bạn tự mở những trang đó nếu thật sự cần.
VII.Có nên dùng không
Điểm mạnh. Quy trình nghiêm ngặt về nguồn: kiểm tra trích dẫn, loại bản sao, kiểm tra độc lập. Kho tri thức giúp nghiên cứu lần sau nhanh hơn. Dùng giấy phép MIT, có thể chạy lại sau khi hỏng, có cả hướng dẫn cho Claude Code và Codex. Repo còn được cập nhật trong vài tháng gần đây.
Giới hạn. Đây không phải công cụ "gõ một lệnh ra kết quả trong vài giây": chạy đầy đủ mất cả giờ và dùng nhiều lượt sử dụng. Bạn cần sẵn Claude Code hoặc Codex. Trên Codex, các khóa "chỉ được sửa nhỏ" chỉ là chỉ dẫn, không bị ép buộc, và không có đường trình duyệt. Chế độ dissertation (viết rất dài) còn đang thử nghiệm, README thừa nhận một số mục tiêu về độ dài và số nguồn chưa được nối vào đầy đủ.
Khi nên chọn cách khác. Nếu bạn chỉ cần câu trả lời nhanh cho một câu hỏi nhỏ, tìm kiếm bình thường trong chính Claude hay Codex là đủ. Nếu không muốn cài gì, README nói có bản chạy trên máy chủ của tác giả, kèm API và MCP server từ vài chỗ khác; chi phí và điều khoản bản đó bạn cần tự xem trên trang của dự án.
Tóm lại, nếu công việc của bạn cần báo cáo có nguồn đáng tin và bạn sẵn sàng chờ, hyperresearch rất đáng thử.
Câu hỏi thường gặp
hyperresearch có miễn phí không?
Repo dùng giấy phép MIT nên bạn dùng mã nguồn mở miễn phí. Tuy nhiên bạn vẫn cần Claude Code hoặc Codex, và các công cụ này có chi phí riêng. Tác giả cũng có bản chạy trên máy chủ riêng của họ, README được cung cấp không nêu giá của bản đó.
Có cần GPU hay máy mạnh không?
Phần README được cung cấp không nhắc đến yêu cầu GPU hay phần cứng. Phần nặng được thực hiện bởi Claude Code hoặc Codex, bạn chủ yếu cần Python 3.11 đến 3.14 và kết nối mạng.
Chạy được trên Windows không?
Phần README được cung cấp chưa nói rõ về hệ điều hành. Các lệnh cài đặt là pip và lệnh hyperresearch, nên về nguyên tắc chạy ở nơi nào cài được Python và Claude Code hoặc Codex. Nếu gặp vấn đề, bạn nên xem mục Issues hoặc thư mục docs của repo.
Dùng được với Codex của OpenAI không?
Có. Dùng hyperresearch install . --target codex rồi mở Codex với quyền ghi file và truy cập mạng. README lưu ý hỗ trợ Codex nằm trong bản PyPI kế tiếp, nếu chưa có thì cài từ GitHub bằng pip install git+https://github.com/jordan-gibbs/hyperresearch.
Một lượt nghiên cứu mất bao lâu?
Theo README, câu hỏi đơn giản (tier light) mất khoảng 30–40 phút. Chế độ mặc định (full) khoảng 1,5–2,5 giờ. Profile premier khoảng 3–5 giờ, còn chế độ dissertation thử nghiệm khoảng 4–8 giờ.
Khác gì hỏi thẳng Claude hoặc ChatGPT?
hyperresearch chạy cả quy trình nhiều bước: tìm nhiều nguồn, đối chiếu mâu thuẫn, để bốn nhà phê bình bắt lỗi và kiểm tra từng trích dẫn. Nó cũng lưu nguồn vào kho để dùng lại. Đổi lại, nó chậm hơn và tốn nhiều lượt sử dụng hơn một câu hỏi thông thường.
Dữ liệu của tôi có an toàn không?
Phần README được cung cấp không có mục riêng về quyền riêng tư. Có thể nói rằng bản mã nguồn mở lưu kho nguồn ngay trong dự án của bạn. Câu hỏi và nội dung vẫn đi qua Claude Code hoặc Codex mà bạn dùng, nên hãy tránh đưa thông tin nhạy cảm nếu chưa đọc điều khoản của các dịch vụ đó.


