repo-context

Read-only repository context explorer for coding agents.

The canonical architecture is a local CLI-first exploration core that talks to an OpenAI-compatible FastContext-style model endpoint. MCP is an adapter around the same core, not the primary abstraction.

Current Status

This repository has the initial Python 3.13+ implementation for spec 001: CLI, shared exploration core, read-only repository tools, OpenAI-compatible chat-completions client, optional trajectory logging, and a thin MCP adapter. It also includes spec 002 hardening for deterministic controller-owned finalization and citation-mode rendering, plus spec 003 latency controls for bounded endpoint prompt growth, and spec 004 same-turn parallel local tool execution. Spec 005 adds a deterministic exact path/symbol fast path for trivial evidence lookups. Spec 006 fixes configuration ownership to project-root config.yaml plus .env/environment overrides. Spec 007 adds raw source snippets for validated, merged citation ranges.

Primary planning artifacts:

• Spec Kit feature spec

• Implementation plan

• Task breakdown

• Deterministic explorer harness

• Latency-bounded explorer harness

• FastContext-compatible parallel tool executor

• Exact path/symbol fast path

• Project-root YAML and env configuration

• Raw location evidence with merged ranges

• Implementation order

FastContext Alignment

This project intentionally follows Microsoft FastContext's explorer shape:

• Delegated repository exploration: CLI/MCP call a focused explorer core that returns evidence for a downstream coding agent.

• Read-only tools: the only model-callable repository tools are read_file, repo_glob, and repo_grep, corresponding to FastContext's Read, Glob, and Grep.

• Same-turn parallel tool calling: independent local tool calls from one model message execute concurrently, while model endpoint requests remain serial.

• Compact evidence: citation mode renders controller-validated path:start-end lines, with the model prompted toward a <final_answer> block.

Primary references: Microsoft FastContext README, FastContext model card, and FastContext paper.

Usage

Use the CLI first for local debugging, scripts, CI checks, and one-off questions. It has the smallest moving parts and exposes the exact core result.

Use MCP when an MCP-capable editor or agent should call repository exploration as a tool during its workflow. MCP delegates to the same core as the CLI.

Configure

The default config lives in the repo-context project root:

cp config.yaml.example config.yaml

The inspected repository's config files are not loaded implicitly. This keeps the explorer's operator config independent of whatever target folder is being read.

Relative paths in config.yaml, including explorer.traj_dir, resolve from the repo-context project root. Environment path overrides are used as provided.

Use project-root .env or process environment variables for local overrides, CI, or secrets:

cp .env.example .env

Configure at least:

FASTCONTEXT_BASE_URL=http://localhost:8000/v1
FASTCONTEXT_MODEL=your-model-name

Endpoint requests use a 120 second default timeout. The harness also caps model-observation payloads, model-requested read spans, completion tokens, and temperature to reduce latency variance. Independent same-turn local tool calls execute concurrently with a default worker cap of 4; model endpoint requests remain serial.

Exact path or uniquely defined symbol queries can complete locally without an endpoint when the controller can validate the citation deterministically.

Configuration precedence:

defaults < project-root config.yaml < project-root .env < process environment < CLI overrides

CLI

Text output:

uv run repo-context explore \
  --query "Find the request validation logic" \
  --repo . \
  --max-turns 6 \
  --citation

In citation mode, repo-context validates and normalizes citations in the controller. Text output is only repository-relative path:start-end labels, or NO_CITATIONS_FOUND; model prose is not emitted. The model is prompted to use a FastContext-style <final_answer> block, but the public text output is rendered from controller-validated citations.

JSON output:

uv run repo-context explore \
  --query "Find the request validation logic" \
  --repo . \
  --format json

MCP

Install optional MCP dependencies:

uv sync --extra mcp

Development server command:

uv run repo-context mcp \
  --transport stdio

Tool: explore_repository(query, repo_root?, max_turns?, citation?)

Generic MCP client config shape:

{
  "mcpServers": {
    "repo-context": {
      "command": "uv",
      "args": [
        "run",
        "--project",
        "/path/to/repo-context",
        "--extra",
        "mcp",
        "repo-context",
        "mcp",
        "--transport",
        "stdio"
      ],
      "env": {
        "FASTCONTEXT_BASE_URL": "http://localhost:8000/v1",
        "FASTCONTEXT_MODEL": "your-model-name"
      }
    }
  }
}

Validate

uv run pytest
uv run ruff check .
uv run mypy

Endpoint-backed e2e tests are opt-in and use this repository as the target repo:

REPO_CONTEXT_RUN_E2E=1 \
FASTCONTEXT_BASE_URL=http://localhost:8000/v1 \
FASTCONTEXT_MODEL=your-model-name \
uv run pytest tests/e2e

To print per-prompt timing for the current-repo multi-prompt e2e:

REPO_CONTEXT_RUN_E2E=1 \
FASTCONTEXT_BASE_URL=http://localhost:8000/v1 \
FASTCONTEXT_MODEL=your-model-name \
uv run pytest tests/e2e/test_current_repo_multi_prompt_timing.py -s

Scope

In scope:

• Local, read-only repository exploration.

• Root-scoped read_file, repo_glob, and repo_grep tools.

• OpenAI-compatible chat completion loop with bounded tool observations.

• Same-turn concurrent execution for independent local tool calls.

• CLI output with file paths and line-range citations.

• MCP adapter that delegates to the CLI/core implementation.

Out of scope for the MVP:

• Repository mutation.

• Vector database ownership or embedding/model serving.

• MCP-first context_search, context_pack, and context_get tools.

• OKF bundle output.