Overview

Agents perform better when they receive small, relevant, explainable task context instead of blindly consuming everything.

That’s why we built OpenContextually, an open-source context layer for coding agents. Give it a task, and it identifies, ranks, and explains the context that matters before the agent starts working.

Give it a task:

gctx "fix the authentication bug"

It scans your repository, follows the relationships a keyword search would miss — imports, calls, tests, configuration, documentation — and returns a small, ranked, explainable package of what to look at before acting. No model, no API key, no network call, no database; the same repository and task produce byte-identical output every time.

It is not another coding agent. It is the layer that helps the agent — or you — figure out what it should know before it starts working.

How it works

your task
   │
   ▼
SELECT → FOLLOW → BOUND → CHECK → EXPLAIN
   │
   ▼
small, ranked, explainable context

The selection itself is local and deterministic — no model decides what matters.

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.

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
17 relevant · 3122 excluded

  fastapi/routing.py             called by applications.py
  fastapi/applications.py        mentions applied
  fastapi/param_functions.py     called by oauth2.py
  fastapi/dependencies/utils.py  called by utils.py
  tests/test_frontend.py         defines record_dependency
  fastapi/security/oauth2.py     called by utils.py
  fastapi/openapi/utils.py       called by applications.py
  fastapi/exceptions.py          called by utils.py

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

Excluded: 3122 files
  ⚠ 48 relevant files dropped -- the result list was already full
  1 relevant file with nothing quotable to show
  1372 files scanned, not relevant enough
  1701 files not scanned (187 binary, 1507 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. (More on what to do with a bad result under Help us break it.)

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.

76% 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.

Dedicated integrations

OpenContextually already works with Claude Code, Cursor, Codex, MCP-compatible agents, and custom coding agents through the CLI and MCP.

Dedicated editor extensions, wrappers, and deeper integrations are still early. --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

Nothing here yet? Build one. 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.

Help us break it

OpenContextually is early. The most useful contribution right now isn't telling us it works — it's finding where it doesn't.

pip install opencontextually
gctx "the bug you're currently fighting"

Bad result? Bring us the context failure with the task, the files you expected, and the files it actually returned — that's exactly what shapes ContextBench and the next fixes.

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

pip install opencontextually
gctx "fix the bug"