OpenContextually

Your agent can write the code. The harder problem is making sure it reads the right code first.

Quickstart · Discord · Discussions · ContextBench · Ecosystem · Contributing · Community

OpenContextually turns a task into a small, ranked, explainable context package from your repository. It is not another coding agent — it is the open context layer before the agent.

Agent failed because it read the wrong context? Bring us the case.

Quickstart

pip install opencontextually

gctx "fix the authentication bug"

No model. No API key. No network. No database. No setup. One dependency. The same repository and task produce byte-identical output every time.

"fix the authentication bug"
            │
            ▼
  SELECT → FOLLOW → BOUND → CHECK → EXPLAIN
            │
            ▼
      task-ready context
      every file with a reason

What it looks like

gctx "dependency override not applied in nested routers"

Run from a clone of fastapi/fastapi at 49033471 — this is the real, unedited output:

dependency override not applied in nested routers
18 relevant · 3121 excluded

  fastapi/routing.py                             defines _frontend_dependency_endpoint
  fastapi/applications.py                        references applied
  tests/test_frontend.py                         defines record_dependency
  tests/test_dependency_overrides.py             filename matches 'dependency'
  tests/test_dependency_wrapped.py               filename matches 'dependency'
  docs/hi/docs/advanced/testing-dependencies.md  defines dependency requirements
  docs/en/docs/advanced/testing-dependencies.md  defines dependency requirements
  docs/tr/docs/advanced/testing-dependencies.md  defines dependency requirements

  +10 more  ·  --all to list  ·  -v for code excerpts

Excluded: 3121 files
  ⚠ 205 relevant files dropped -- the result list was already full
  2715 files scanned, not relevant enough
  201 files not scanned (187 binary, 7 exact duplicate of another file, 7 too large to scan)

Checks run: configuration_discrepancy, test_reference_gap

Two files were reached through imports, not text — --all marks fastapi/openapi/utils.py and fastapi/exceptions.py ← via routing.py, the file that actually implements dependency overrides. One doc page shows up three times, correctly: testing-dependencies.md is genuinely translated under docs/en, docs/hi, and docs/tr. Every file carries a reason, and everything excluded is accounted for — including the 205 that scored relevant but missed the result budget.

Try it yourself

git clone https://github.com/fastapi/fastapi.git && cd fastapi
python -m venv .venv && source .venv/bin/activate   # fish: activate.fish
pip install opencontextually

gctx "dependency override not applied in nested routers"   # ~2s

Flask clones the same way — gctx "session cookie is not set on redirect" — in about 0.2s. No model, no API key, no network call; your code never leaves your machine. Add -v to see the excerpt behind each match.

Already have a project open? Skip the clone:

gctx "where does authentication actually happen?"
gctx "what will break if I change the User model?"

Give it something you're actually working on — you'll know in seconds whether it's right, because it's your code.

Bad result? Bring us the context failure — that's useful too.

Search finds matches. Context needs relationships.

Search answers "where do these words occur?". That is a different question from "what should be read for this task?".

grep / ripgrep

  task ──────────────────►  keyword matches


OpenContextually

  task ──►  direct matches
                 │
                 ├──►  imported dependencies
                 ├──►  tests that exercise them
                 ├──►  relevant configuration
                 └──►  governing documentation
                              │
                              ▼
                     bounded context package

A task like fix the authentication bug can need a file that never contains the words authentication or bug. OpenContextually starts from direct matches, follows Python's own import graph, applies repository boundaries, runs two deterministic checks, and explains every inclusion.

Most of the value, though, is ranking and compression of files search could already find: a grep for sqlfluff's "indentation rule fires on a templated line" matches 415 files; OpenContextually returns 12, each with a reason — reproducible from the corpus below.

Install

pip install opencontextually

Python 3.10+, one runtime dependency. To work on OpenContextually itself:

git clone https://github.com/gammalex-ai/opencontextually
cd opencontextually
pip install -e ".[dev]"

Using it

CLI

gctx is short for GammaLex Context. The same command is also installed as octx (the original name, kept working) and opencontextually. Flags compose (-v --all); --json is unaffected by either and is always full fidelity.

Write tasks the way you'd describe the bug. Naming a specific behavior or symbol beats a directory-shaped noun.

Python

from opencontextually import get_context

package = get_context("fix the authentication bug")

print(package.render())     # the text above
package.to_dict()           # the same content as JSON

MCP

Agents that speak MCP can call it directly. Requires the optional extra:

pip install "opencontextually[mcp]"

Point your MCP client at the opencontextually-mcp command:

{
  "mcpServers": {
    "opencontextually": {
      "command": "opencontextually-mcp"
    }
  }
}

It exposes exactly one tool — get_context(task, root=".") — returning the same shape as gctx --json.

Tested on real repositories

Scripted tests lock in fixes; they do not find them. Most real defects in this project were found by running it against unfamiliar repositories and reading the output, so a standing corpus is part of the project (benchmarks/, with a runner that also checks determinism and sweeps for leaked secrets).

What it selected, and what it missed

Fourteen repositories, each with a hand-checked answer key (benchmarks/answer-keys.json): the files that actually implement or test the behaviour the task names. Six were used while tuning ranking. Eight were held out — keys written and committed before the tool ran against them, nothing tuned afterward.

79% and 66% — the held-out figures — are the ones to argue with: they predict a repository this project has never seen, and the default view (compact output shows eight files) matters more than the total.

Across all fourteen: zero fixture, vendor, generated or CI files selected, and 0.05%–2.1% of repository bytes delivered.

What the held-out repos caught that tuning missed:

• A bundled previous major version. pydantic ships Pydantic 1 inside Pydantic 2 — six of eighteen slots went to pydantic/v1/*. Fixed.
• Repeated documents. rich's README translations, fastapi's docs/en/docs/hi/docs/tr — genuinely different pages sharing a filename. Not fixed — a dedup cap was tried and reverted.
• Vocabulary collisions. On django, rich ranks progress.py (ProgressColumn) first for a table-width task. Tracked as issue #3.

The corpus

A 10-repository, timed subset of the fourteen above, reproducible with benchmarks/dogfood.py:

All ten are MIT- or BSD-licensed, unaffiliated with this project, cloned --depth 1 on 2026-08-30 at the commits above. 18,693 files total, but only 16,331 are actually scanned — the rest excluded before reading, mostly gitignored build output. Zero secret-shaped strings reached any package; every run was byte-identical across repeats. Times are best-of-three on an M-series Mac, Python 3.13, warm cache — treat as orders of magnitude, not a benchmark.

Ecosystem & Community

Works with today

Verified by the test suite and by hand against a clean install — nothing here is aspirational.

Community integrations

Nothing here yet — an empty table beats a fictional one. --json and the MCP server are both stable, so anything below is buildable today:

• an editor/IDE extension, or a wrapper for an agent harness (Cursor, Continue, OpenCode, Aider, your own)
• a GitHub Action posting the context package onto an issue's PR
• language support beyond Python's import graph — see GOOD_FIRST_CONTEXT.md

Built something with gctx? Tell us and we may feature it here.

The question this project is trying to answer

What should an agent know before it acts — and how do we prove it got the right context?

Every claim above is checkable against committed answer keys in ContextBench. Found a wrong-files case, or want to argue with a number? COMMUNITY.md has every way in.

What it deliberately does not do

• Follow imports outside Python. Expansion uses the stdlib ast module; other languages get lexical matching only.
• Understand your code. Ranking is lexical scoring plus import expansion — weakest when a task's words are also the repo's naming convention, since filename matches then dominate.
• Find problems for you. Two narrow checks flag detectable conflicts — a config value contradicting docs, a symbol no test references — not arbitrary missing context. Quiet by default: zero findings across the six answer-key corpus tasks, one false positive (since fixed) across eleven real repos. A footer always names which checks ran.
• Guarantee secrets stay out of excerpts. Redaction masks secret-shaped keys and high-entropy strings, but it is best-effort pattern matching, not a secrets scanner. See SECURITY.md.

Scope, determinism, and safety

Discovery reads everything under --root minus what git already ignores — honoring nested .gitignore files, .git/info/exclude, and the global core.excludesFile, plus an optional .opencontextuallyignore. All resolved without shelling out to git, so it works in directories that aren't repositories at all.

Runs are deterministic: the same task and repository produce byte-identical output, which is asserted in the test suite and re-checked by the corpus runner. Nothing is written anywhere, and no network call is ever made.

Contributing

Bug reports, context failures, ContextBench cases, integrations, language support and documentation fixes are all welcome — CONTRIBUTING.md covers the workflow and the scope boundaries, GOOD_FIRST_CONTEXT.md lists concrete places to start, and COMMUNITY.md is where to find people.

License

MIT