Convert Claude Code or Codex into the most intelligent Deep Research Agent. Collect, search, and synthesize web research into a persistent, searchable wiki that builds on itself. Hosted API + MCP: hyperresearch.ai
Contributing to hyperresearch
Thank you for your interest in contributing.
Development setup
git clone https://github.com/jordan-gibbs/hyperresearch.git
cd hyperresearch
python -m venv .venv
source .venv/bin/activate # or .venv\Scripts\activate on Windows
pip install -e ".[dev]"
Running tests
python -m pytest tests/ -v
All tests must pass before submitting a PR. The full suite takes a minute or two; run a single file while iterating.
Code style
This project uses ruff for linting:
ruff check src/ tests/
Configuration is in pyproject.toml. Line length is 100 characters.
Type checking
mypy src/hyperresearch/
Strict mode is enabled in pyproject.toml.
Submitting changes
- Fork the repository.
- Create a branch from
main. - Make your changes with tests.
- Run
ruff check src/ tests/andpython -m pytest tests/. - Open a pull request against
main.
Keep PRs focused on a single change. Include a clear description of what changed and why.
Reporting issues
Open an issue at github.com/jordan-gibbs/hyperresearch/issues. Include:
- What you expected to happen
- What actually happened
- Steps to reproduce
- hyperresearch version (
hyperresearch --version) - Python version and OS
Architecture overview
src/hyperresearch/core/-- vault management, sync engine, frontmatter parsing, SQLite schemasrc/hyperresearch/cli/-- typer CLI commands, output formattingsrc/hyperresearch/search/-- FTS5 search engine, filters, rankingsrc/hyperresearch/models/-- Pydantic models for notes, output envelopessrc/hyperresearch/graph/-- link parsing (shared patterns)src/hyperresearch/indexgen/-- auto-generated index page buildersrc/hyperresearch/web/-- pluggable web providers (fetch and search backends)src/hyperresearch/export/-- export formatterssrc/hyperresearch/mcp/-- MCP server exposing research-base tools to agentssrc/hyperresearch/skills/-- bundled research skills installed into the harnesssrc/hyperresearch/serve/-- lightweight web UI servertests/-- pytest test suite
The key design principle: markdown files are the source of truth, SQLite is a derived cache that can be rebuilt at any time with hyperresearch sync --force.