Gus

Your agent doesn't need the whole file.

It needs the six lines that answer the question. Gus is a local context layer for AI coding agents: ask a question, get back only the functions, classes, doc sections and PDF passages that matter, with file paths and line ranges.

Install from PyPI View source

$ cat httpx/_client.py
# 13,702 tokens, 2,019 lines. What an agent reads without Gus.

$ gus search "where are cookies persisted between requests" --top-k 1
httpx/_client.py:318-323
    @property
    def cookies(self) -> Cookies:
        """
        Cookie values to include when sending requests.
        """
        return self._cookies

68%

less context per question

4 in 5

questions with the right code in the top 5

API keys or cloud services

Why Gus

Plugs into your agent

gus init wires it into Claude Code, Cursor, Codex CLI and Antigravity. Any MCP client works, and shell-only agents can call gus search.

Runs entirely on your machine

Indexing, embedding and search are all local. The only network access is downloading the embedding model once.

Never stale

Every query re-indexes changed files first, so the agent always sees its own edits.

Smarter than grep

It ranks whole functions by what they do, so plain-English questions work even when you don't know the names. Exact identifiers still match.

Code, docs and PDFs

Code is split into real functions and classes for nine languages, Markdown by heading and PDFs by page. Pages that are only images are flagged, so the agent knows to open them.

Fast or quality, your call

The default model indexes big repos in seconds on any CPU. The optional EmbeddingGemma model ranks the right code first 70% of the time.

Measured, not guessed

Gus is scored on 33 held-out, hand-checked questions about real open-source repos, phrased the way agents ask them. Tokens are real tiktoken counts, and when Gus misses, reading the file is still counted against it. In a Claude Code A/B run, it matched accuracy while cutting mean tokens by 24% and cost by 32%.

Charts: reading the file that holds the answer costs 6,472 tokens; Gus results cost 2,059 (68% less) and Gus outline mode 1,597 (75% less). The right code is ranked first 45% of the time with the fast model and 70% with the quality model.

Try Gus

Restart your agent and it has a new get_context tool. Requires Python 3.10 or newer; pipx install gus-mcp works too.

Install from PyPI Help build it

Gus is free and open source. If it saves you time, buy me a coffee.

uv tool install gus-mcp
cd your-project
gus init

Hit a bug?

Tell me what broke or what Gus is missing. No account needed — or open an issue on GitHub if you'd rather track it there.