Hyperresearch: як змусити Claude Code перевіряти цитати й вести дослідницький архів

Hyperresearch — відкритий Python-пакет, який намагається це виправити. Він змушує Claude Code працювати як агент глибокого дослідження: конвеєр із 16 кроків, постійний архів з усім прочитаним і набір перевірок, які не дають звіту вийти, якщо його цитати розсипаються. Репозиторій лежить за адресою https://github.com/jordan-gibbs/hyperresearch, а сам пакет можна встановити з PyPI. Нижче — як його запускати і які два налаштування вирішують, чи буде перший прогін корисним, чи розчарує.

Три звички, яких він уникає

Основну роботу роблять три архітектурні рішення, і кожне відповідає на збій, знайомий вам з інших дослідницьких агентів. Вони ж пояснюють, за що ви платите часом очікування.

Лагодження краще за перегенерацію. Коли чернетку звіту готово, агентам, що з нею працюють, на рівні allowlist у Claude Code залишено лише права на читання й редагування. Патчер і фінальний аудитор фізично не можуть написати нову чернетку. Попросіть звичайну модель перегенерувати документ на 20 000 слів після критики, і ви дасте їй тисячі шансів непомітно змінити чи викинути встановлений факт. Тут зауваження критика або вкладається в маленьку точкову правку, або піднімається як структурний збій. Документ не може тихо перекроїти сам себе.

Повтор — не підтвердження. Якщо один пресреліз передрукували пʼятдесят видань, некалібрований агент бачить переважний консенсус. Щоб із цим боротися, аудит незалежності групує майже однакові копії за схожістю змісту, а потім ділить вагу на всю групу. Пʼять передруків одного релізу зрештою важать як одне джерело.

Початкове питання завжди на виду. Ваш точний промпт один раз записується у файл query.md, і кожен наступний крок і кожен породжений субагент перечитує його. Багатоагентні конвеєри дрейфують, і до девʼятого кроку тема може перетворитися на простішу родичку того, про що ви питали. Закріпити текст і перечитувати його — примітивне рішення, яке працює.

У довгостроковій перспективі найбільше, можливо, окупиться архів. Кожна сторінка, PDF і робоча нотатка потрапляють у пошукове сховище з markdown-файлів і SQLite всередині теки проєкту. Наступний запуск у тій самій теці спершу переглядає те, що вже є, і лише потім щось завантажує, тож дослідження накопичується, а не зникає.

Встановлення без розчарування

Встановлення — це дві команди, запущені в каталозі проєкту, де має жити архів:

cd your-project
pip install hyperresearch && hyperresearch install

Після цього наберіть /hyperresearch <your question> (ваше питання) у Claude Code. Підтримується Python від 3.11 до 3.13. Якщо у вас 3.14, яка поки не підтримується, спершу створіть середовище на 3.13 через pyenv install 3.13 або uv venv -p 3.13.

Наступний момент документація згадує один раз, і більшість його пропускає. Вебпровайдер за замовчуванням — builtin, простий HTTP-запит узагалі без пошуку. У нього немає зайвих залежностей, але конвеєр налаштовували не під нього. Якщо після запуску за замовчуванням корпус джерел здається бідним, причина саме в цьому.

Рішення — доповнення crawl4ai:

pip install "hyperresearch[crawl4ai]"

Потім оберіть його в .hyperresearch/config.toml:

[web]
provider = "crawl4ai"

Так завантаження переходить на headless-браузер з обходом захисту від ботів, а заодно зʼявляються видобування тексту з PDF і браузерна смуга ескалації. Якщо є ключі, підтримуються Exa і Tavily. Parallel не потребує акаунта, але вміє лише шукати, а масові завантаження відкочуються до одного URL за раз, тож він найкраще працює як доповнення.

Ще один вибір під час встановлення. Встановлення на проєкт не засмічує сторонні сесії Claude Code. Глобальне (hyperresearch install --global) робить команду доступною всюди ціною приблизно пʼятнадцяти рядків у системному нагадуванні кожної сесії. Почніть зі встановлення на проєкт.

Оберіть рівень, перш ніж спалити три години

Кожен запуск потрапляє на один із трьох рівнів. Його обирає крок 1, що класифікує запит, не питаючи вас.

• light виконує пʼять кроків із шістнадцяти приблизно за 30–40 хвилин і підходить для обмежених фактичних питань, оглядів і порівнянь.
• full використовується за замовчуванням і запускає все: змагальних критиків, перевірку цитат і решту. Розраховуйте приблизно на 1,5–2,5 години.
• dissertation вмикається, лише якщо про це прямо просить промпт. Робота ділиться на 4–10 розділів, спирається на 300–450 джерел і дає від 25 000 до 80 000 слів, а триває приблизно 4–8 годин.

Пропускайте full, коли вистачило б доброго пошуку й двадцяти хвилин читання. Класифікатор розумний, але формулювання промпту його підштовхує, і прохання про «comprehensive analysis» («всебічний аналіз») може коштувати двох годин, які витрачати було ні до чого.

Другий важіль — регістр, і він виводиться з дієслова в промпті. «Teach me X» («навчи мене X») дає навчальне пояснення. «What does the field around X look like» («як виглядає галузь навколо X») дає карту без вердикту. Варіант за замовчуванням, analyze, будує оцінну аргументацію, а advocate захищає одну названу вами тезу. Назвіть регістр прямо, і ваша інструкція переможе здогадку.

Працює це тому, що критики йдуть за регістром, а не воюють із ним. У режимі survey діалектичний критик заперечує проти несправедливої подачі конкурентних поглядів і не тисне в бік вердикту, а фінальний аудитор не чіпає ваших застережень. У режимі advocate перевірки стають суворішими. Перевірка цитат і фінальний шлюз не прогинаються ніколи, і це правильно: верифікація не повинна слабшати через те, що вам хотілося мʼякшого тону.

Обсяг налаштовується окремо від тону, через профілі, що задають цільову кількість джерел і бюджет глибини:

hyperresearch profile list           # what's available, what's active
hyperresearch profile use premier    # 100-130 sources, doubled depth budget
hyperresearch profile use full       # back to the 55-80 baseline

Перед довгим запуском обмежте й витрати:

hyperresearch run init --budget 50

У разі перевищення ліміту запуск блокується, а не роздувається. Ліміт обмежує оціночні витрати в перерахунку на API, а не буквальний рахунок, тож використовуйте його в перші прогони, доки не зрозумієте, скільки коштує запуск premier.

Налаштування, яке змінює якість джерел

Якщо з теми є справжня наукова література, запитуйте наукові бази раніше за відкритий веб. Вебпошук повертає людей, які обговорюють роботу, а науковий пошук повертає саму роботу.

hpr scholar search "GLP-1 cardiovascular outcomes" -j
hpr scholar sources    # what's wired up, what each one covers

Зараз один запит охоплює сім джерел. Бібліографію й відкритий доступ дають Crossref, OpenAlex, CORE і DOAB. Окрім статей, пошук іде зареєстрованими дослідженнями в ClinicalTrials.gov, корпоративною звітністю в SEC EDGAR та економічними рядами з FRED. Результати обʼєднуються за DOI, а якщо його немає — за нормалізованими назвами. У README їх вісім, бо там указано й RePEc, хоча його API шукати не вміє. Обʼєднаний список позначає кожне влучання за типом, тож випробування, які так і не стали статтями, звітність SEC і дані ФРС не плутаються з журнальними статтями.

Тепер саме налаштування — справжній контактний email:

export HYPERRESEARCH_CONTACT_EMAIL="you@example.com"

Це одне значення має два ефекти. Воно переводить вас у «ввічливі» пули OpenAlex і Crossref, де ліміти запитів набагато мʼякші, ніж для анонімних клієнтів. І його вимагають умови Unpaywall — першого сервісу, до якого звертається конвеєр у пошуках копій у відкритому доступі.

Якщо email порожній, використовується лише Europe PMC, а він покриває біомедицину й нічого поза своєю відкритою підмножиною. Якщо email задано, у разі пейволу агент спершу йде в Unpaywall, а за ним у черзі стоять Europe PMC і CORE: шукається легальна безплатна копія, чий повний текст замінює в нотатці анотацію. Від цього залежить, чи буде ваш архів набитий заглушками на 1 500 символів, чи справжніми статтями.

Вкажіть те саме значення в розділі [scholar] конфігу:

[scholar]
oa_recovery = true
contact_email = "you@example.com"
oa_min_full_text_chars = 6000
oa_prefer_published = true

Зверніть увагу на oa_prefer_published, що тихо робить тут важливу роботу. Коли опублікованої відкритої копії немає, Unpaywall може повернути прийнятий рукопис або надісланий препринт, і ні те, ні інше не дорівнює версії запису.

Читайте результат так, ніби відповідаєте за нього

Коли спрацьовує відновлення з відкритого доступу, поле source: нотатки й далі показує запитаний вами URL, хоча текст міг прийти з іншого місця. Інструмент позначає це в чотирьох місцях: банер на початку нотатки, поля frontmatter oa_url, oa_source, oa_version і oa_license, JSON-блок oa з hpr note show <id> --json, де є body_is_not_from_source: true, і згадка в самому виводі завантаження.

Перш ніж щось цитувати, перевірте oa_version. Якщо там acceptedVersion або submittedVersion, звірте цитату з опублікованою статтею.

Є випадок складніший. Джерело, яке взагалі не вдається прочитати, наприклад через 403 або стіну логіну, проходить через той самий пошук, і вся нотатка будується за копією з відкритого доступу. Такі нотатки позначаються oa_recovery_kind: rescued і nothing_from_source: true, а банер визнає, що початковий URL так і не відкрився. Вірте йому: назва, автори й текст — усе взято із заміни. Якщо вам краще не мати нотатки взагалі, ніж отримати зібрану за підміною, задайте oa_rescue_blocked = false.

Перед випуском запускається батарея перевірок. Процитований фрагмент має дослівно траплятися в якійсь нотатці архіву, тож вигадана цитата — жорстка зупинка. Відкликане джерело, процитоване без згадки про відкликання, — теж жорстка помилка, причому перевірка відкликань переперевіряє кожен процитований DOI саме в момент випуску, а не в тому стані, у якому він був під час першого завантаження. Цифри без підтвердження позначаються.

hyperresearch run verify <tag> -j   # headings, length, citation density, cite-check resolution
hyperresearch run status -j         # step status, spend, escalation queue depth
hyperresearch run resume -j         # crashed runs pick up at the exact step

Остання команда рятує життя: якщо запуск упав на кроці 12, він продовжиться з кроку 12.

Робота з архівом згодом

Звіт — це результат, а архів — це актив.

hyperresearch search "ion-trap gate fidelity" -j
hyperresearch search "quantum" --include-body -j
hyperresearch graph hubs -j          # most-connected notes
hyperresearch sources independence -j # syndication clusters
hyperresearch lint -j                # broken links, missing tags

Джерело істини — markdown, а SQLite слугує лише кешем, який можна перебудувати. Якщо базу втрачено, hyperresearch sync відновить індекс із файлів на диску. Тримайте теку в git і відкривайте в будь-якому редакторі. Ваше дослідження лишається читабельним і без інструмента, і ця переносність важить більше за будь-яку окрему функцію.

Працює він і поза Claude Code. hyperresearch serve --open запускає локальний вебінтерфейс на порту 8080, а після pip install hyperresearch[mcp] команда hyperresearch mcp надає тринадцять інструментів через stdio, тож Cursor або Claude Desktop можуть звертатися до того самого архіву.

Обмеження й одна заява, до якої варто ставитися обережно

Заблоковані завантаження стають у чергу ескалації, а не губляться мовчки. Один раз запустіть hyperresearch setup і увійдіть на свої сайти. Якщо встановлено розширення Claude-in-Chrome, агент-завантажувач розбирає цю чергу через ваш справжній Chrome з виконаними входами й проходить пейволи, за які ви заплатили. CAPTCHA, 2FA і логіни ніколи не обробляються автоматично: ви отримуєте їх усі разом в одному повідомленні.

Лінт-шлюз ловить структурні збої: відсутні каркаси, розірвані ланцюжки походження й нерозібрані критичні зауваження. Фактичної точності він гарантувати не може, і README прямо про це каже. Вибір джерел лишається за агентом, а отже, спрямовувати його й далі вам.

Далі — заява про лідерборд. У репозиторії сказано, що інструмент посідає перше місце в категорії RACE на DeepResearch-Bench, проте підпис під графіком чесний: це прогноз за стратифікованим пілотом, виміряний власними силами, який чекає незалежної перевірки. Публікувати таке розумно, а повторювати як встановлений факт — ні. Справжній суддя — ваші власні запуски.

Зважте й на швидкість змін. Перший реліз на PyPI датовано квітнем 2026 року, а в середині вересня 2026-го після сімнадцяти релізів вийшла 0.11.1. Софт версії нижче 1.0, що змінюється так швидко, на момент читання вже зрушить, тож звіряйте будь-який згаданий тут прапорець із README. Ліцензія — MIT.

Перший запуск, який можна справді оцінити

Не тестуйте його на незнайомій темі: ви не помітите помилок. Оберіть те, що знаєте досить добре, щоб ловити хиби, — із солідною літературою внизу й купою переказаних коментарів згори. Таке поєднання викриває дві слабкості, яких з одного тексту звіту не видно:

/hyperresearch Survey the evidence on whether remote work changes
software team productivity. Separate individual output from team-level
coordination costs, and distinguish measured studies from company
self-reports. Survey the landscape; don't argue for a position.

Формулювання тут працює всерйоз. «Survey» («огляд») обирає регістр, тож результат описує галузь, не виносячи вердикту. Два запитані розмежування на кроці 1 перетворюються на атомарні пункти чек-листа, і критик інструкцій потім звіряє з ними чернетку. Останнє речення перекриває здогадку про регістр, щоб вона не залежала від одного дієслова.

Для першої спроби використайте light і не оцінюйте прозу. Відкрийте пʼять нотаток в архіві й дайте відповідь на чотири питання:

1. Чи було отримано самі дослідження, чи лише статті, що їх описують?
2. У яких нотатках повний текст, а в яких лише анотація на 1 500 символів? Для всього відновленого погляньте на oa_version і nothing_from_source.
3. Візьміть три твердження зі звіту й переконайтеся, що процитована нотатка справді підтверджує кожне.
4. Виконайте hyperresearch sources independence -j. Чи згорнулися передруки в кластери, чи самотній пресреліз і далі рахується пʼять разів?

Якщо відповіді збігаються з тим, до чого ви дійшли б, зробивши роботу самі, довші запуски варті вашого вечора. Цей тест підходить для будь-якого дослідницького агента. Просто більшість із них не зберігає нотаток, за якими його можна провести.

Почніть із репозиторію: встановлення на проєкт, доповнення crawl4ai і ваш контактний email, а потім витратьте сорок хвилин на запуск light.