Gus

• Report a bad result: tell us what you asked, what Gus returned, and what you expected. These reports drive ranking work.
• Add a language: add its tree-sitter grammar package, map the file extensions in gus/chunker.py, and add a small test.
• Try an embedding model: register it in ONNX_MODELS in gus/embed.py and report dev and test eval numbers plus indexing speed.
• Verify an agent integration: Cursor's config follows its documented format but hasn't been checked with the real agent yet.

git clone https://github.com/SUD747/gus && cd gus
uv venv && uv pip install -e '.[onnx]'

Use .[gpu] instead if you have an NVIDIA GPU, or plain . if you only need the fast model.

Everything routes through one function: get_context() in gus/core.py, which runs hybrid semantic and keyword retrieval and ranks the results. The MCP server and the CLI are thin wrappers around it.

• gus/index.py: walks files, updates the index incrementally, stores it in SQLite
• gus/chunker.py: splits code into functions and classes with tree-sitter, Markdown by heading, PDFs by page
• gus/embed.py: embedding backends
• gus/agents.py: what gus init writes for each agent

• Quality comes before token savings. A change that returns less context but lowers hit@k or MRR is a regression. Report both numbers side by side.
• Keep the wrappers thin. Behaviour belongs in core.get_context; the CLI and server only translate input and output.
• Never write to stdout from library code. Under gus serve it's the MCP channel. Log with index.log(), which goes to stderr.
• Bump FORMAT_VERSION when chunking or the storage schema changes, so existing indexes rebuild cleanly.
• Keep dependencies small. No torch, and nothing that downloads at runtime apart from the embedding model.

If you touch chunking, embedding, indexing or ranking, run the eval. It scores hand-checked questions about two real repos at pinned commits.

Tune only on the dev split. Run the test split once, for your final configuration: choosing between ideas by looking at test results ruins it as a held-out measure.

python eval/run.py --split dev -v   # lists every case not ranked first
python eval/run.py                   # full run before you open the PR

uvx ruff check .
python tests/test_gus.py

CI runs both on Python 3.10 and 3.13. Security issues go through SECURITY.md in the repo, not the public issue tracker.