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 bộ skill và gói Python (MIT) biến Claude Code hoặc OpenAI Codex thành agent nghiên cứu sâu. Bạn đưa một câu hỏi, nó tự tìm nguồn, đọc, phản biện và viết báo cáo có trích dẫn. Cài bằng pip và một lệnh install, cần Python 3.11 đến 3.14.
hyperresearch là một bộ skill kèm công cụ dòng lệnh Python, giúp Claude Code (và cả OpenAI Codex) làm nghiên cứu sâu thay bạn. Bạn đặt một câu hỏi, nó chạy quy trình nhiều bước: chia nhỏ câu hỏi, tìm và đọc hàng chục đến hàng trăm nguồn, viết nháp, cho nhiều "người phản biện" soi lỗi rồi mới ra báo cáo cuối.
Vấn đề nó giải quyết rất quen thuộc: hỏi AI một câu phức tạp thì được câu trả lời trôi chảy nhưng khó biết nguồn nào thật, trích dẫn nào bịa. hyperresearch buộc từng trích dẫn phải được kiểm tra xem nguồn có thật sự nói đúng câu đó không. Mọi nguồn nó đọc cũng được lưu vào một "kho" (vault) dạng markdown kèm SQLite, nên lần nghiên cứu sau không phải bắt đầu từ số không.
Repo hiện có khoảng 4712 sao và 490 fork, giấy phép MIT, vẫn được cập nhật trong 3 tháng gần đây. Bạn nên dùng nếu hay phải làm báo cáo so sánh đối thủ, khảo sát thị trường, tìm hiểu một lĩnh vực mới, hoặc tổng hợp tài liệu. Điểm đáng giá nhất là bước kiểm chứng trích dẫn và kho nguồn tích lũy qua nhiều lần chạy.
jordan-gibbs/hyperresearch
Skill cho Claude Code và OpenAI Codex: từ một câu hỏi, chạy quy trình 16 bước để ra báo cáo có trích dẫn đã kiểm chứng, nguồn lưu vào kho tra cứu.
I.hyperresearch làm được gì
Dưới đây là các tính năng chính, giải thích theo lợi ích thực tế.
- Quy trình 16 bước, tự chọn mức theo câu hỏi. Câu hỏi đơn giản đi đường nhanh khoảng 30–40 phút. Câu hỏi cần lập luận sâu chạy đủ các bước, khoảng 1,5–2,5 giờ. Bạn không phải tự dựng quy trình.
- Đọc nhiều nguồn trong một lần chạy. README nói một lần chạy có thể thu thập hơn 250 nguồn ở cấu hình mạnh nhất. Bạn có bức tranh rộng hơn nhiều so với vài đường link AI thường dẫn.
- Kiểm chứng từng trích dẫn trước khi giao báo cáo. Một bước "cite-check" xem nguồn có thật sự ủng hộ câu được trích không. Trích dẫn bịa hoặc nguồn đã bị rút lại sẽ bị chặn ở cổng cuối.
- Không coi bản sao chép là đồng thuận. Năm trang cùng đăng lại một thông cáo báo chí chỉ được tính như một nguồn. Nhờ vậy báo cáo ít bị "thổi phồng" bởi nội dung lặp.
- Phản biện và vá lỗi có kiểm soát. Bốn "critic" soi bản nháp song song. Người vá chỉ được sửa từng đoạn nhỏ, không được viết lại cả báo cáo. Nhờ đó bản đã kiểm tra không bị đổi nội dung bất ngờ.
- Tìm nguồn học thuật. Lệnh
hpr scholar searchtìm qua tám nguồn (OpenAlex, Crossref, CORE, DOAB, ClinicalTrials.gov, SEC EDGAR, FRED…) và gộp kết quả, bỏ trùng theo DOI và tiêu đề. Có cả sách, thử nghiệm lâm sàng và hồ sơ tài chính, không chỉ bài báo. - Cố đọc toàn văn bài báo bị khoá. Thay vì chỉ lưu phần tóm tắt ngắn, nó hỏi Unpaywall, Europe PMC và CORE xem có bản mở hợp pháp không. Mỗi lần thay thế đều được ghi rõ.
- Kho tri thức dùng lại được. Nguồn đã đọc nằm trong kho, phiên sau tra trước khi tải mới.
- Chạy hỏng thì chạy tiếp. Mỗi lần chạy có một bản ghi tiến trình, lệnh
run resumetiếp tục đúng bước bị dừng.
Tác giả cũng có bản hosted (hyperresearch.ai) với API, nhưng bài này chỉ hướng dẫn bản tự chạy trên máy bạn.
II.Cần chuẩn bị gì
Theo tư liệu, bạn cần:
- Python từ 3.11 đến 3.14 (theo
pyproject.tomlvà README). - Claude Code hoặc OpenAI Codex CLI (một trong hai, hoặc cả hai). hyperresearch chạy bên trong các công cụ này, nên bạn cần cài và đăng nhập sẵn.
- Một thư mục dự án để cài vào. Cách cài mặc định là theo từng dự án.
- Với Codex: phiên làm việc phải được mở với quyền ghi file và quyền truy cập mạng (xem phần cài đặt).
README không nêu yêu cầu về GPU, hệ điều hành cụ thể hay API key riêng cho hyperresearch. Chi phí cũng chưa được ghi: quy trình dùng nhiều agent con chạy song song, nên hãy theo dõi hạn mức của gói Claude hoặc Codex đang dùng.
Một lần chạy đầy đủ kéo dài hàng giờ và dùng nhiều agent con song song. README không ghi chi phí, nên lần đầu hãy thử với câu hỏi nhỏ và theo dõi mức tiêu thụ hạn mức của bạn.
III.Cài đặt từng bước
- Mở terminal trong thư mục dự áncd vào thư mục bạn muốn làm việc
- Cài gói Pythonpip install hyperresearch
- Cài skill vào dự ánhyperresearch install (Claude Code) hoặc thêm --target codex
- Mở Claude Code hoặc Codexchạy trong cùng thư mục, bật quyền nếu dùng Codex
- Gọi skill/hyperresearch <câu hỏi> hoặc $hyperresearch <câu hỏi>
A.Mở terminal đúng thư mục
Hyperresearch cài theo từng dự án, nên bạn phải đứng đúng thư mục muốn dùng. Mở terminal (PowerShell trên Windows, Terminal trên macOS/Linux) rồi chuyển vào thư mục đó. Ví dụ với thư mục tên your-project:
cd your-projectThay your-project bằng tên thư mục thật của bạn. Chỗ này người mới hay vấp: cài ở thư mục này mà mở Claude Code ở thư mục khác thì sẽ không thấy skill.
B.Cài gói Python
pip install hyperresearchLệnh này tải công cụ hyperresearch về máy. Nếu báo không tìm thấy pip hoặc Python quá cũ, xem phần lỗi thường gặp bên dưới.
C.Cài skill vào dự án
Chọn đúng lệnh theo công cụ bạn dùng:
hyperresearch install # Claude Code, then: /hyperresearch
hyperresearch install . --target codex # OpenAI Codex, then: $hyperresearchCòn nếu muốn cả hai chạy song song, README nói dùng --target all:
hyperresearch install . --target allVới Codex, lệnh install đặt skill vào .agents/skills/hyperresearch/, các bước quy trình vào .hyperresearch/codex/steps/, các agent con vào .codex/agents/, một Stop hook vào .codex/hooks.json và một đoạn ngắn vào AGENTS.md.
Ngoài ra README ghi một lựa chọn cho người dùng nâng cao: hyperresearch install --global giúp /hyperresearch dùng được ở mọi phiên Claude Code, nhưng đổi lại mỗi phiên sẽ thêm khoảng 15 dòng vào system reminder. Nếu không chắc, cứ cài theo từng dự án như trên.
D.Cách khác: cài qua plugin hoặc skill
README còn có hai đường khác, đều cài một skill khởi động tên deep-research rồi tự thiết lập quy trình lúc dùng lần đầu. Cả hai vẫn cần pip install hyperresearch.
Plugin trong Claude Code:
/plugin marketplace add jordan-gibbs/hyperresearch
/plugin install hyperresearch@hyperresearchPlugin trong Codex:
codex plugin marketplace add jordan-gibbs/hyperresearch
codex plugin add hyperresearch@hyperresearchHoặc cài skill đơn qua skills.sh:
npx skills add jordan-gibbs/hyperresearch -a claude-code
npx skills add jordan-gibbs/hyperresearch -a codexVới cách này, lệnh gọi sẽ là /hyperresearch:deep-research <câu hỏi> (plugin) hoặc /deep-research <câu hỏi> (skill) trên Claude Code. Trên Codex thì thay / bằng $.
E.Nếu dùng Codex: mở phiên với quyền ghi và mạng
Quá trình nghiên cứu cần ghi file và ra mạng, mà Codex mặc định không cho cả hai. Hãy mở Codex bằng lệnh sau:
codex --sandbox workspace-write -c sandbox_workspace_write.network_access=true
# then, in the session:
$hyperresearchREADME cũng ghi chú rằng bản hỗ trợ Codex sẽ có trong bản PyPI kế tiếp. Trước đó, bạn có thể cài thẳng từ GitHub:
pip install git+https://github.com/jordan-gibbs/hyperresearchHyperresearch không tự sửa cấu hình Codex của bạn. Các quyền này chỉ truyền qua cờ lệnh.
F.Gọi skill lần đầu
Trong Claude Code gõ /hyperresearch kèm câu hỏi. Trong Codex gõ $hyperresearch kèm câu hỏi. README nói bạn cũng có thể chỉ cần yêu cầu "nghiên cứu sâu" bằng lời thường, skill sẽ tự kích hoạt theo mô tả của nó.
Nếu Claude Code chưa nhận skill và agent mới cài, hãy khởi động lại nó ở cùng thư mục rồi chạy lại /hyperresearch <câu hỏi>.
IV.Kiểm tra đã chạy được chưa
Cách nhanh nhất là gọi một lệnh của chính công cụ để xem nó có phản hồi không:
hyperresearch profile listLệnh này liệt kê các "gear" (mức quy mô), kèm mô tả và gear hiện tại. Thấy danh sách là gói Python đã cài được.
Tiếp theo, kiểm tra phần skill:
- Trên Claude Code: gõ
/hyperresearchtrong phiên, nếu skill được nhận là cài xong. - Trên Codex: kiểm tra có thư mục
.agents/skills/hyperresearch/và file.codex/hooks.jsontrong dự án.
Khi đang chạy hoặc sau khi chạy, xem tiến trình và lựa chọn của bước 1 bằng:
hyperresearch run status -jBáo cáo cuối được ghi ở final_report.md theo mô tả trong README, còn câu hỏi gốc được lưu trong thư mục research/runs/ của dự án.
V.Dùng vào việc thật
A.Chủ quán so sánh phần mềm bán hàng
Bạn mở quán và đang phân vân giữa vài phần mềm quản lý bán hàng. Trong Claude Code, bạn gõ câu hỏi bằng lời thường, ví dụ:
/hyperresearch So sánh các hệ thống POS cho nhà hàng nhỏ: chi phí, tính năng, rủi ro hợp đồngĐây là câu mẫu do mình đặt, bạn tự thay bằng chủ đề của bạn. Vì là câu hỏi so sánh, bước 1 có thể xếp vào mức light và đi đường nhanh. Kết quả là một báo cáo có trích dẫn cho từng nhận định. README có đưa mẫu cùng kiểu (phân tích đối thủ POS cho nhà hàng) từ bản hosted để bạn xem trước chất lượng.
B.Nhân viên văn phòng tìm hiểu một lĩnh vực mới
Sếp giao bạn "tìm hiểu thị trường X" trong khi bạn chưa biết gì. Bạn có thể nói rõ kiểu báo cáo mình cần ngay trong câu hỏi, vì README nói bước 1 chọn "register" từ cách bạn đặt câu:
- "Dạy mình về X" ra bản giải thích kiểu giảng bài (
teach). - "Toàn cảnh lĩnh vực X" ra bản bản đồ lĩnh vực, không phán xét (
survey).
Nếu cần đi sâu hơn giữa chừng, README có lệnh đổi mức:
hyperresearch levers set <tag> inference_depth=deep --rerender # go deeper mid-runBạn nhận được một báo cáo đúng giọng bạn cần, thay vì tự đọc hàng chục tab.
Trích dẫn nào cũng phải qua một người hoài nghi trước khi báo cáo được giao.
Ông T
C.Dev hoặc nhà nghiên cứu cần tài liệu học thuật
Bạn cần tìm bài báo, thử nghiệm lâm sàng hoặc hồ sơ tài chính về một chủ đề. Lệnh tìm học thuật của repo gom tám nguồn vào một danh sách đã bỏ trùng:
hpr scholar searchREADME không ghi đầy đủ tham số của lệnh này trong đoạn mình có, nên hãy xem hướng dẫn trong repo (thư mục docs/) để biết cách truyền từ khoá. Khi chạy trong quy trình, các bài bị khoá sẽ được thay bằng bản mở hợp pháp nếu tìm thấy, và việc thay thế được ghi rõ trong ghi chú.
D.Người dùng Codex chạy tự động không cần ngồi canh
Bạn muốn chạy một lần không tương tác. README cho lệnh sau, nhưng lưu ý cờ --dangerously-bypass-hook-trust chỉ nên dùng khi bạn đã đọc .codex/hooks.json:
codex exec --sandbox workspace-write -c sandbox_workspace_write.network_access=true \
--dangerously-bypass-hook-trust "\$hyperresearch
"Nếu không có cờ đó, Stop hook (lớp chặn Codex bỏ bước) sẽ không chạy, vì codex exec không hỏi được bạn có tin tưởng hook hay không.
VI.Lỗi hay gặp và cách xử lý
A.Không tìm thấy lệnh hyperresearch hoặc pip báo lỗi
Thường do Python chưa cài hoặc sai phiên bản. Gói yêu cầu Python từ 3.11 đến 3.14. Kiểm tra phiên bản Python bằng python --version, cài lại nếu ngoài khoảng đó, rồi chạy lại pip install hyperresearch. Nếu vừa cài xong mà vẫn không gọi được lệnh, hãy đóng và mở lại terminal.
B.Claude Code không thấy skill vừa cài
README hướng dẫn khởi động lại Claude Code ở đúng thư mục đã cài rồi chạy /hyperresearch <câu hỏi>. Hãy chắc chắn bạn đang ở đúng dự án, vì cài mặc định là theo từng thư mục.
C.Codex không ghi được file hoặc không ra mạng
Codex mặc định không cho cả hai. Mở lại phiên bằng đúng hai cờ trong phần cài đặt (--sandbox workspace-write và network_access=true). Đừng bật thêm quyền nào khác mà bạn không hiểu.
D.Codex đi tắt, trả lời thẳng rồi dừng
Đây chính là việc Stop hook được thiết kế để chặn, nhưng Codex chỉ chạy hook của dự án sau khi bạn tin tưởng chúng. Trong phiên tương tác, hãy xác nhận tin tưởng hook sau khi đọc .codex/hooks.json. Với codex exec, hook không chạy nếu thiếu cờ bỏ qua bước tin tưởng.
E.Một số trang không tải được
Trang đòi đăng nhập hoặc chặn bot sẽ làm bước tải nguồn thất bại. Trên Codex không có "làn trình duyệt" như Claude-in-Chrome, nên các nguồn này nằm lại trong hàng đợi và tin nhắn cuối liệt kê chúng cho bạn. Bạn có thể tự mở và đọc thủ công những nguồn đó nếu chúng quan trọng.
VII.Có nên dùng không
Điểm mạnh. Quy trình có cấu trúc rõ, kiểm chứng trích dẫn, chống nguồn lặp, kho nguồn dùng lại được và chạy lại được khi bị dừng giữa chừng. Cài đặt khá đơn giản: một lệnh pip và một lệnh install. Giấy phép MIT, chạy ngay trong công cụ bạn đã dùng.
Giới hạn. Chạy lâu: đường nhanh cỡ 30–40 phút, đường đầy đủ 1,5–2,5 giờ, chế độ premier có thể 3–5 giờ. Chi phí hạn mức chưa được README nêu. Trên Codex, việc "khoá công cụ" chỉ là chỉ dẫn chứ không bị ép cứng, và không có làn trình duyệt. Chế độ dissertation (báo cáo rất dài) vẫn đang ở mức thử nghiệm, README tự ghi một số chỉ tiêu chưa được nối vào hệ thống.
Khi nên chọn cách khác. Nếu chỉ cần câu trả lời nhanh cho một câu hỏi đơn giản, cứ hỏi AI bình thường. Nếu không muốn cài gì, tác giả có bản hosted tại hyperresearch.ai (có API) nhưng đó là dịch vụ riêng, README chưa nói rõ về giá trong phần mình có. Và với bất kỳ báo cáo quan trọng nào, bạn vẫn nên tự mở vài nguồn trọng yếu ra kiểm tra lại.
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 cài và dùng gói tự chạy được mà không phải trả phí cho chính repo. Tuy nhiên nó chạy bên trong Claude Code hoặc Codex, nên vẫn tiêu hao hạn mức hoặc chi phí của các công cụ đó. README chưa ghi con số chi phí cụ thể.
Cần cài những gì trước khi dùng?
Bạn cần Python từ 3.11 đến 3.14 và một trong hai công cụ là Claude Code hoặc OpenAI Codex CLI. Sau đó cài gói bằng pip rồi chạy lệnh hyperresearch install trong thư mục dự án. README không nêu yêu cầu GPU.
Dùng được với Codex không, hay chỉ Claude Code?
Dùng được cả hai. Với Codex, cài bằng hyperresearch install . --target codex rồi mở phiên có quyền ghi file và truy cập mạng. Trên Codex không có làn trình duyệt và việc khoá công cụ chỉ là chỉ dẫn, không bị ép cứng.
Chạy một lần mất bao lâu?
Câu hỏi đơn giản đi đường nhanh, khoảng 30–40 phút. Câu hỏi cần phân tích sâu chạy đủ 16 bước, khoảng 1,5–2,5 giờ ở mức mặc định. Gear premier tốn khoảng 3–5 giờ.
Trích dẫn trong báo cáo có đáng tin không?
Quy trình có bước cite-check kiểm tra xem từng nguồn có thật sự ủng hộ câu được trích không, và trích dẫn bịa là lỗi chặn ở cổng cuối. Dù vậy README không cam kết tuyệt đối, nên với báo cáo quan trọng bạn vẫn nên tự kiểm tra các nguồn then chốt.
Dữ liệu và nguồn đã đọc được lưu ở đâu?
Nguồn được lưu trong một kho cục bộ gồm file markdown và SQLite trong dự án của bạn, và các lần chạy sau tái sử dụng kho này. Câu hỏi gốc cũng được lưu trong thư mục research/runs/. Quy trình vẫn gọi mô hình Claude hoặc Codex và tải nội dung từ web, README chưa có phần nào nói về quyền riêng tư vượt ngoài điều đó.
Khác gì bản hosted hyperresearch.ai?
Bản hosted dùng cùng quy trình nhưng không cần cài Claude Code hay Codex, và có thêm REST API, MCP server từ xa và API kiểm chứng trích dẫn. Bản trong repo này là bản tự chạy trên máy bạn. README chưa nêu giá của bản hosted.


