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.

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
• 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

Prefer .repo-context.toml for stable project-local settings:

cp .repo-context.toml.example .repo-context.toml

Use environment variables for temporary overrides, CI, or secrets:

cp .env.example .env

repo-context reads real environment variables from the process environment; it does not load .env by itself. 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 < .repo-context.toml < environment variables < 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.