microsoft/fastcontext

microsoft/fastcontext

Description: FastContext: Training Efficient Repository Explorer for Coding Agents

Language: Python

License: MIT

Stars: 0

Forks: 0

Open issues: 0

Created: 2026-06-02T05:01:11Z

Pushed: 2026-06-15T06:20:09Z

Default branch: main

Fork: no

Archived: no

README:

FastContext: Training Efficient Repository Explorer for Coding Agents

📰 News | 🔎 Overview | 📊 Results | ⚡ Quick Start | 🧪 Reproduction | 📚 Citation

FastContext is a lightweight repository-exploration subagent for coding agents. Instead of letting the main coding agent spend its own context window on broad file reads and code searches, the main agent delegates a natural-language context query to FastContext. FastContext explores the repository with read-only tools, issues independent tool calls in parallel, and returns compact file-line citations as focused evidence for the main agent.

News

• 🚀 2026-06-15: We released the arXiv paper [📄 arXiv] and the model weights [🤗 Model].

Overview

Modern coding agents often use the same model to explore a repository and solve the task. This makes exploration expensive: exploratory reads and searches consume tokens, stay in the solver's history, and can pollute later reasoning with irrelevant snippets.

FastContext separates repository exploration from solving:

• 🧭 Delegated exploration: the main agent asks FastContext for repository context before editing or answering.
• 🔒 Read-only tools: FastContext uses Read, Glob, and Grep; it does not modify files.
• ⚙️ Parallel tool calling: independent reads and searches can be issued in the same exploration turn.
• 📌 Compact evidence: the final response is a short `` block with file paths and line ranges.
• 🧠 Trainable explorers: the paper trains 4B-30B exploration models with SFT and task-grounded RL.

The intended contract is simple: FastContext finds the relevant code; the main coding agent uses that focused evidence to edit, test, or answer.

/path/to/repo/src/router.py:42-58
/path/to/repo/tests/test_router.py:101-119

Results

Across SWE-bench Multilingual, SWE-bench Pro, and SWE-QA, FastContext improves the score-token tradeoff of Mini-SWE-Agent style coding agents.

| Result | Finding | | --- | --- | | 📈 End-to-end success | Up to +5.5 score improvement with delegated repository exploration. | | 💸 Main-agent token use | Up to 60.3% fewer main-agent tokens. | | 🧠 Compact trained explorer | FC-4B-RL improves or ties FC-4B-SFT across all reported end-to-end settings. | | 🎯 Standalone exploration | Trained FastContext models recover patch-relevant files and symbols more accurately than non-FastContext small-model baselines. |

Token Efficiency

FastContext reduces the main agent's context burden by moving broad repository exploration outside the solver trajectory. The reduction is especially visible in file-reading and code-search tokens.

Installation

FastContext requires Python 3.12 or newer. The repository uses `uv` for package and environment management.

Install the CLI from the repository root:

uv tool install .

For development:

uv sync --all-groups

Build a local wheel:

uv build

The built wheel is written under dist/, for example:

dist/fastcontext-0.1.0-py3-none-any.whl

Model Configuration

FastContext expects an OpenAI-compatible chat completions endpoint. For direct CLI usage, configure:

export BASE_URL="https://your-endpoint.example/v1"
export MODEL="your-model-name"
export API_KEY="your-api-key"

Benchmark runners may also pass separate FastContext credentials through FASTCONTEXT_* variables in benchmark/evaluation/configs/example.env.

Quick Start

Run FastContext from the repository you want to explore:

fastcontext \
--query "Find the files that implement authentication and explain where to make a change" \
--max-turns 6 \
--traj .fastcontext/trajectory.jsonl

Return only the machine-readable citation block:

fastcontext \
--query "Locate the request validation logic" \
--citation

Useful CLI options:

| Option | Description | | --- | --- | | --query, -q | Natural-language exploration request. | | --traj, -t | JSONL trajectory output path. | | --max-turns | Maximum exploration turns before forcing a final answer. | | --verbose | Print intermediate messages and runtime information. | | --citation | Return only the `` block when present. |

Programmatic Use

import asyncio

from fastcontext.agent.agent_factory import make_fastcontext_agent

async def main() -> None:
agent = make_fastcontext_agent(
trajectory_file=".fastcontext/trajectory.jsonl",
work_dir="/path/to/repo",
)
answer = await agent.run(
prompt="Find where database migrations are defined",
max_turns=6,
citation=True,
)
print(answer)

asyncio.run(main())

Reproduction

This repository contains scripts for end-to-end Mini-SWE-Agent runs and standalone exploration evaluation. The exact paths, model names, and credentials should be adapted to your serving environment.

End-to-End SWE-Bench Runs

git submodule update --init --recursive
uv build
cp benchmark/evaluation/configs/example.env .env

Edit .env with the main-agent and FastContext endpoint credentials, then run:

uv run --group benchmark python benchmark/evaluation/bench_mini_swe_agent.py \
--bench swebench-multilingual \
--agent-config prompts/gpt-multi-fc.yaml \
--config .env \
--output preds.json \
--logs-dir logs \
--workers 1

For SWE-bench Pro, use the Pro prompt:

uv run --group benchmark python benchmark/evaluation/bench_mini_swe_agent.py \
--bench ScaleAI/SWE-bench_Pro \
--agent-config prompts/gpt-pro-fc.yaml \
--config .env \
--output preds-pro.json \
--logs-dir logs-pro

Standalone Exploration

The standalone runner evaluates FastContext as a repository explorer on SWE-bench-style subagent queries.

cd benchmark/swebench
cp run.sh.sample run.sh
# Edit run.sh with BASE_URL, MODEL, and API_KEY.

uv run --group benchmark python bench_fastcontext.py \
--bench swebench-multilingual \
--experiment fastcontext-eval \
--prediction-file predictions.jsonl \
--local-mount-dir /absolute/path/to/output \
--num-threads 1

After extracting the final FastContext responses...