Hyperresearch: cómo hacer que Claude Code verifique citas y mantenga un archivo de investigación

Hyperresearch es un paquete de Python de código abierto que intenta resolver esto. Hace que Claude Code se comporte como un agente de investigación profunda: un pipeline de 16 pasos, un archivo permanente con todo lo que lee y una batería de comprobaciones que impiden publicar un informe cuando sus citas se desmoronan. El repositorio está en https://github.com/jordan-gibbs/hyperresearch y el paquete se puede instalar desde PyPI. A continuación verás cómo usarlo, con las dos decisiones de configuración que hacen que una primera ejecución resulte útil o decepcionante.

Tres malos hábitos que evita

Tres decisiones de diseño hacen casi todo el trabajo, y cada una responde a un fallo que reconocerás de otros agentes de investigación. También explican qué te da a cambio el tiempo de espera.

Reparar en vez de regenerar. Una vez redactado el informe, los agentes que lo tocan quedan limitados a permisos de lectura y edición en la allowlist de Claude Code. El patcher y el auditor de pulido no pueden escribir físicamente un borrador nuevo. Si le pides a un modelo normal que regenere un documento de 20.000 palabras tras una crítica, le das miles de oportunidades de cambiar o eliminar un hecho ya establecido sin que nadie lo note. Aquí, el hallazgo de un crítico o cabe en una edición pequeña y quirúrgica, o se escala como fallo estructural. El documento no puede reescribirse a sí mismo en silencio.

Repetir no es corroborar. Si cincuenta medios reproducen el mismo comunicado de prensa, un agente sin calibrar ve un consenso abrumador. Para contrarrestarlo, una auditoría de independencia agrupa las copias casi idénticas según lo parecido de su contenido y reparte el peso entre el grupo. Cinco reproducciones de un mismo comunicado acaban pesando como una sola fuente.

La pregunta original queda fijada. Tu prompt exacto se escribe una vez en un archivo query.md, y cada paso posterior y cada subagente que se lanza vuelve a leerlo. Los pipelines multiagente se desvían, y para el paso 9 el tema puede haberse convertido en un primo más sencillo de lo que preguntaste. Fijar el texto y releerlo es una solución tonta que funciona.

A largo plazo, quizá lo que más compense sea el archivo. Cada página, PDF y nota de trabajo va a un almacén consultable de archivos markdown más SQLite dentro de la carpeta del proyecto. Una ejecución posterior en la misma carpeta revisa lo que ya hay antes de descargar nada, así que la investigación se acumula en lugar de esfumarse.

Instalarlo sin llevarse un chasco

La instalación son dos comandos, ejecutados dentro del directorio del proyecto donde debe vivir el archivo:

cd your-project
pip install hyperresearch && hyperresearch install

Después, escribe /hyperresearch <your question> (tu pregunta) en Claude Code. Se admite Python de 3.11 a 3.13. Si usas 3.14, que todavía no está soportado, crea primero un entorno 3.13 con pyenv install 3.13 o uv venv -p 3.13.

La documentación menciona el siguiente punto una sola vez y casi todo el mundo lo pasa por alto. El proveedor web por defecto es builtin, una petición HTTP simple sin ninguna búsqueda. No tiene dependencias extra y no es para lo que se ajustó el pipeline. Si tras una ejecución por defecto el corpus de fuentes se queda escaso, esa es la razón.

La solución es el extra crawl4ai:

pip install "hyperresearch[crawl4ai]"

Luego selecciónalo en .hyperresearch/config.toml:

[web]
provider = "crawl4ai"

Así la descarga pasa a un navegador headless con manejo sigiloso, y además se incorporan la extracción de texto de PDF y el carril de escalado al navegador. Exa y Tavily están soportados si tienes claves. Parallel no requiere cuenta, pero solo busca, y las descargas masivas vuelven a una URL cada vez, así que funciona mejor como complemento.

Otra decisión al instalar. Una instalación por proyecto mantiene limpias las sesiones de Claude Code que no tienen nada que ver. Una global (hyperresearch install --global) deja el comando disponible en todas partes a cambio de unas quince líneas en el recordatorio del sistema de cada sesión. Empieza por proyecto.

Elige un nivel antes de quemar tres horas

Cada ejecución cae en uno de tres niveles, elegido por el paso 1, que clasifica la consulta sin preguntarte.

• light ejecuta cinco de los dieciséis pasos en unos 30 a 40 minutos y sirve para preguntas factuales acotadas, panoramas y comparaciones.
• full es el predeterminado y lo ejecuta todo: críticos adversariales, verificación de citas, el lote completo. Cuenta con unas 1,5 a 2,5 horas.
• dissertation solo se activa cuando el prompt lo pide. Organiza el trabajo en 4 a 10 capítulos, se apoya en 300 a 450 fuentes y produce entre 25.000 y 80.000 palabras, con una duración aproximada de 4 a 8 horas.

Sáltate full cuando con una buena búsqueda y veinte minutos de lectura bastaría. El clasificador es razonable, pero la redacción de tu prompt lo empuja, y pedir un «comprehensive analysis» («análisis exhaustivo») puede costarte dos horas que no necesitabas gastar.

El registro es la segunda palanca, y se deduce del verbo de tu prompt. «Teach me X» («enséñame X») da una explicación didáctica. «What does the field around X look like» («cómo es el campo en torno a X») da un mapa sin veredicto. El predeterminado, analyze, construye un argumento evaluativo, y advocate defiende una única tesis que tú nombras. Indica el registro de forma explícita y tu instrucción se impone a la suposición.

Lo que hace que esto funcione es que los críticos siguen el registro en lugar de ir en su contra. Con survey, el crítico dialéctico objeta un trato injusto a las posturas en competencia y no presiona para emitir un veredicto, y el auditor de pulido respeta tus matices. Con advocate, las comprobaciones se vuelven más estrictas. El verificador de citas y la puerta de publicación nunca ceden, y es lo correcto: la verificación no debería relajarse porque quisieras un tono más suave.

La extensión se controla aparte de la voz, mediante perfiles que fijan objetivos de fuentes y presupuestos de profundidad:

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

Pon también un tope al gasto antes de una ejecución larga:

hyperresearch run init --budget 50

Superar el tope bloquea la ejecución en lugar de dejar que se dispare. Limita el gasto estimado equivalente en API y no es una factura literal, así que úsalo en las primeras ejecuciones mientras aprendes cuánto cuesta una ejecución premier.

El ajuste que cambia la calidad de las fuentes

Si un tema tiene literatura de investigación de verdad, consulta las bases académicas antes que la web abierta. Una búsqueda web devuelve gente hablando del trabajo, mientras que una búsqueda académica devuelve el trabajo.

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

Ahora mismo, una sola consulta llega a siete fuentes. La cobertura bibliográfica y de acceso abierto viene de Crossref, OpenAlex, CORE y DOAB. Además de artículos, busca estudios registrados en ClinicalTrials.gov, informes corporativos en SEC EDGAR y series económicas de FRED. Los resultados se fusionan por DOI y, si no hay, por títulos normalizados. El README cuenta ocho porque también aparece RePEc, aunque su API no permite buscar. La lista fusionada etiqueta cada resultado por tipo, de modo que los ensayos que nunca llegaron a artículo, los informes de la SEC y los datos de la Fed no se confunden con artículos de revista.

Ahora, el ajuste en sí: un email de contacto real:

export HYPERRESEARCH_CONTACT_EMAIL="you@example.com"

Este único valor tiene dos efectos. Te pasa a los «polite pools» de OpenAlex y Crossref, donde los límites de peticiones son mucho más holgados que para usuarios anónimos. Y además lo exigen las condiciones de Unpaywall, el primer servicio al que recurre el pipeline cuando busca copias en acceso abierto.

Con el email vacío solo se usa Europe PMC, que cubre biomedicina y nada fuera de su subconjunto de acceso abierto. Con el email configurado, un muro de pago envía primero al agente a Unpaywall, con Europe PMC y CORE en cola detrás, en busca de una copia gratuita legal cuyo texto completo sustituya al resumen en la nota. De eso depende que tu archivo acabe lleno de esbozos de 1.500 caracteres o de artículos de verdad.

Pon el mismo valor bajo [scholar] en la configuración:

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

Fíjate en oa_prefer_published, que aquí hace un trabajo silencioso. Cuando no hay ninguna copia publicada en abierto, Unpaywall puede devolver un manuscrito aceptado o un preprint enviado, y ninguno equivale a la versión de registro.

Leer el resultado como alguien que responde de él

Cuando entra en juego la recuperación en acceso abierto, el campo source: de una nota sigue mostrando la URL que pediste, aunque el texto puede venir de otro sitio. La herramienta lo señala en cuatro lugares: un banner al principio de la nota, los campos de frontmatter oa_url, oa_source, oa_version y oa_license, un bloque JSON oa de hpr note show <id> --json que incluye body_is_not_from_source: true, y una mención en la propia salida de la descarga.

Revisa oa_version antes de citar nada. Si pone acceptedVersion o submittedVersion, contrasta la cita con el artículo publicado.

Hay un caso más difícil. Una fuente que no se puede leer en absoluto, por ejemplo por un 403 o un muro de inicio de sesión, pasa por la misma búsqueda, y toda la nota se construye a partir de la copia en acceso abierto. Esas notas llevan oa_recovery_kind: rescued y nothing_from_source: true, y un banner admite que la URL original nunca llegó a abrirse. Créetelo: título, autores y texto salen todos del sustituto. Si prefieres no tener nota antes que una montada a partir de un sustituto, configura oa_rescue_blocked = false.

Antes de publicar se ejecuta la batería de verificación. Un fragmento citado debe aparecer palabra por palabra en alguna nota del archivo, así que una cita inventada es una parada en seco. Una fuente retractada que se cita sin mencionar la retractación también es un error grave, y la revisión de retractaciones vuelve a comprobar cada DOI citado justo en el momento de publicar, no tal como estaba cuando se descargó la fuente. Las cifras sin evidencia detrás se marcan.

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

El último comando es un salvavidas: si una ejecución falla en el paso 12, retoma en el paso 12.

Trabajar después con el archivo

El informe es el resultado, y el archivo es el activo.

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

La fuente de verdad es el markdown, y SQLite solo sirve de caché que puedes reconstruir. Si se pierde la base de datos, hyperresearch sync regenera el índice a partir de los archivos en disco. Guarda la carpeta en git y ábrela en cualquier editor. Tu investigación sigue siendo legible sin la herramienta, y esa portabilidad vale más que cualquier funcionalidad concreta.

También funciona fuera de Claude Code. hyperresearch serve --open lanza una interfaz web local en el puerto 8080, y tras pip install hyperresearch[mcp], el comando hyperresearch mcp ofrece trece herramientas por stdio, lo que permite a Cursor o Claude Desktop consultar el mismo archivo.

Límites, y una afirmación que conviene tomar con cautela

Las descargas bloqueadas se ponen en una cola de escalado en lugar de perderse en silencio. Ejecuta hyperresearch setup una vez e inicia sesión en tus sitios. Si tienes instalada la extensión Claude-in-Chrome, un agente de descarga recorre esa cola usando tu Chrome real con las sesiones iniciadas y supera los muros de pago por los que has pagado. Los CAPTCHA, el 2FA y los inicios de sesión nunca se gestionan de forma automática, y te llegan todos juntos en un solo mensaje.

La puerta de lint detecta fallos estructurales como andamiajes que faltan, cadenas de procedencia rotas y hallazgos críticos sin resolver. La exactitud factual queda fuera de lo que puede prometer, un límite que el README reconoce abiertamente. La selección de fuentes sigue en manos del agente, así que dirigirlo sigue siendo cosa tuya.

Luego está lo del ranking. El repositorio dice que ocupa el primer puesto en la categoría RACE de DeepResearch-Bench, aunque el pie del gráfico es sincero al respecto: una proyección a futuro a partir de un piloto estratificado, medida internamente y pendiente de validación por terceros. Publicarlo es razonable, pero repetirlo como un hecho asentado no lo es. El juez de verdad son tus propias ejecuciones.

Ten en cuenta también lo rápido que cambia. La primera versión en PyPI es de abril de 2026, y a mediados de septiembre de 2026 salió la 0.11.1 tras diecisiete versiones. Un software por debajo de 1.0 que cambia a este ritmo se habrá movido cuando leas esto, así que compara cualquier flag mencionado aquí con el README. La licencia es MIT.

Una primera ejecución que de verdad puedas juzgar

No lo pruebes con un tema que te resulte nuevo, porque no notarás los errores. Elige algo que conozcas lo bastante bien como para pillar fallos, con literatura sólida debajo y un montón de comentarios refritos encima. Esa combinación deja al descubierto las dos debilidades que no se ven solo con el texto del informe:

/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.

La redacción hace un trabajo real. «Survey» («panorama») selecciona el registro, así que el resultado traza el mapa del campo sin emitir veredicto. Las dos distinciones pedidas se convierten en elementos atómicos de la checklist en el paso 1, y el crítico de instrucciones después exige que el borrador las cumpla. La última frase anula la suposición del registro para que no dependa solo del verbo.

Usa light en el primer intento y no juzgues la prosa. Abre cinco notas del archivo y responde a cuatro preguntas:

1. ¿Se recuperaron los estudios reales o solo artículos que los describen?
2. ¿Qué notas contienen el texto completo y cuáles solo un resumen de 1.500 caracteres? En todo lo rescatado, mira oa_version y nothing_from_source.
3. Toma tres afirmaciones del informe y confirma que la nota citada respalda de verdad cada una.
4. Ejecuta hyperresearch sources independence -j. ¿La cobertura sindicada se agrupó en clústeres, o un comunicado de prensa solitario sigue contando cinco veces?

Si esas respuestas coinciden con lo que habrías concluido haciendo el trabajo tú mismo, las ejecuciones más largas merecen tu tarde. La prueba sirve para cualquier agente de investigación. Lo que pasa es que la mayoría no guarda las notas que te permiten hacerla.

Empieza en el repositorio con una instalación por proyecto, el extra crawl4ai y tu email de contacto, y luego dedica cuarenta minutos a una ejecución light.