get_codebase_contextLABSCO SUMMARY
The repository is read in Gemini's context, and your client only sees the answer.
That is the whole trade: a large codebase costs Gemini tokens on your own key instead of filling the context window your agent is working in. It also means the quality of the digest is Gemini's call rather than your agent's.
What it is
A server that points Gemini Flash at a local repository and hands back a digest instead of raw files. The client sees a single tool; behind it, Gemini lists the repository structure, reads the files it decides it needs and greps the code, then returns only what bears on the question asked. Files you reference in a query are named to Gemini rather than pasted in, so their contents are pulled only if they matter.
What you get
- One tool the client calls with a question, answered from the repository you launched the server against
- Structure listing, file reading and grep performed on Gemini's side, so the client's context receives the digest and not the files
- Referenced files passed as leads, read only when the query needs them
- A configurable ceiling on how much context an analysis may build, and a report of the tokens each one consumed
- A standalone SSE server several clients can share, or stdio when you would rather the client start and stop it
- CORS limited to loopback origins unless you name the origins yourself
Requirements
A Google Gemini API key, since every question is answered by Gemini on your account. Python with the project's dependencies, the tree command available on the machine, and the repository path given to the server when it starts. Token counts are estimated with a gated Hugging Face tokenizer; without access to it the server keeps running on a heuristic estimator and switches over on its own once you have access.
Setup effort
Build from source — git clone https://github.com/ReyNeill/Kontxt.git
USE CASES
01
Getting oriented in an unfamiliar codebase
Ask what the project is or how a subsystem works and get a digest assembled from the files that actually matter, not a directory listing.
02
Answering a question that spans many files
Gemini greps and reads across the repository, so a question like how the authentication flow works comes back as one answer instead of a chain of file reads.
03
Tracing files you already suspect
Reference specific files in the question and they are passed to Gemini as leads, read only if the query needs them.
1 tool
Listed in project docs. Your client may show a different list.
BEFORE YOU INSTALL
What to know first
Tools you get
1 tool named in the project's documentation. list_repository_structure, read_files and grep_codebase are used internally by Gemini and cannot be called. The token budget can be set to 500k, 800k (default) or 1M.
Requires
- Python
- The tree command on your system (macOS: brew install tree; Debian/Ubuntu: sudo apt install tree; Windows needs a port or WSL)
- A Google Gemini API key — GEMINI_API_KEY in .env, the client configuration's env, or --gemini-api-key
INSTALLATION
Connect your client
You clone this one yourself.
Server setup
TERMINAL
git clone https://github.com/ReyNeill/Kontxt.git
cd Kontxt
python -m venv venv
source venv/bin/activate
pip install -r requirements.txtCopy .env.example to .env and set GEMINI_API_KEY to your Google Gemini API key
MCP Clients
Cursor — SSE
Start the server from the Kontxt folder (venv active) and leave it running — it serves http://127.0.0.1:8080/sse:
CURSOR — SSE · TERMINAL
python kontxt_server.py --repo-path <YOUR_REPO_PATH>Then add this to ~/.cursor/mcp.json and refresh the server in Cursor Settings:
CURSOR — SSE · JSON
{
"mcpServers": {
"kontxt-server": {
"serverType": "sse",
"url": "http://localhost:8080/sse"
}
}
}<YOUR_REPO_PATH> is the absolute path of the repository to analyse (run pwd inside it).
Cursor — stdio
CURSOR — STDIO · JSON
{
"mcpServers": {
"kontxt-server": {
"serverType": "stdio",
"command": "python",
"args": [
"<YOUR_PATH_TO_KONTXT_SERVER>",
"--repo-path",
"<YOUR_PATH_TO_CODEBASE>",
"--transport",
"stdio"
],
"env": {
"GEMINI_API_KEY": "<YOUR_GEMINI_API_KEY>"
}
}
}
}Cursor starts the server itself in this mode. <YOUR_PATH_TO_KONTXT_SERVER> is that file in your Kontxt clone, and <YOUR_PATH_TO_CODEBASE> is the repository to analyse, and <YOUR_GEMINI_API_KEY> is your Gemini API key. python must be the venv's interpreter (Kontxt/venv/bin/python) or have the requirements installed.
