Compact Context

Give Codex five useful files before the model starts.

Website · Install · Benchmark · Row-level data · Roadmap

▶ Watch the 10-second project overview

Compact Context is a deterministic, local repository router for Codex. Before a qualifying coding turn, it ranks repository metadata and supplies up to five likely files. Codex then opens and edits the authoritative source normally.

It is a public beta, not a general claim that every coding session will cost less.

One turn, at a glance

"Fix the receipt marker race in turn_start.py"
                         │
                         ▼
        Git-bounded local metadata index
                         │
                         ▼
     BM25 + symbols + imports + related tests
                         │
                         ▼
       up to 5 terse candidate-file lines
                         │
                         ▼
         Codex reads authoritative source

No source bodies are placed in the automatic shortlist. Weak matches simply add nothing.

Measured result

On a frozen 68-task, 10-repository benchmark, using the same five-file limit and the o200k tokenizer:

Repository-map metric	Without Compact Context	With Compact Context
Mean input tokens per task	1,402.1	230.4
Right file in top five	48/68	50/68

That is an 83.6% smaller candidate-map payload with two additional top-five hits on this benchmark. The 95% paired-bootstrap interval for the retrieval change includes zero, so this is not evidence of a statistically established retrieval improvement. It is also not an 83.6% reduction in total prompt tokens, provider spend, latency, or completed-task cost.

The row-level results, task identifiers, file paths, hashes, and bootstrap intervals are in docs/benchmark-results.json. See docs/BENCHMARK.md for claim boundaries.

Install the beta

The current signed release and checksum are served from the project site:

curl -fsSL 'https://compact-context.met.chatgpt.site/install.sh?v=5' | bash

The installer is open source: scripts/install.sh is the public source served by that URL. It downloads the public release ZIP and verifies its published SHA-256 checksum before installing.

Already installed? Run the same command again. It leaves the current version untouched and reinstalls the cached plugin only when the packaged version changes. Previously shared installer links continue to work.

Review the downloaded code and hook permissions before approving them. Full setup and an inspect-before-install ZIP are at https://compact-context.met.chatgpt.site.

Prefer to inspect everything first?

Download the source ZIP and SHA-256 file from the website, inspect plugins/compact-codebase/, then run the installer only when you are comfortable approving the UserPromptSubmit and Stop hooks.

How it works

1. Uses Git to limit scanning to tracked and non-ignored untracked files.
2. Builds a local metadata index of paths, roles, symbols, imports, and signatures.
3. Scores task evidence with field-weighted BM25 and local dependency links.
4. Selects up to five complementary candidates within a bounded payload.
5. Abstains when the match is weak or the repository is small enough to inspect directly.

The automatic hint contains metadata, not source bodies. It does not make an extra model call, use embeddings, rewrite source files, or contact a Compact Context service.

Privacy and safety

• Processing and cache state stay on the local machine.
• The plugin itself performs no network requests.
• Credential-shaped files, binaries, symlinks, dependencies, build output, and oversized files are excluded.
• Repository content is treated as untrusted data, never as instructions.
• Codex still reads real source before making a change.

Read PRIVACY.md, SECURITY.md, and LIMITATIONS.md before production use.

Important

The measured 83.6% reduction is a repository-map payload result. It is not a claim about the full Codex prompt or bill. The broader 30% completed-workload cost gate remains unscored.

Repository layout

.agents/plugins/marketplace.json       local marketplace entry
plugins/compact-codebase/              installable Codex plugin
  .codex-plugin/plugin.json            plugin manifest
  hooks/                               automatic shortlist and receipt hooks
  skills/compact-codebase-context/     direct/fallback skill and engine
docs/                                  benchmark evidence and launch material
tests/                                 unit and end-to-end checks

Development

Requirements: Python 3.9 or newer and Git.

python3 -m unittest discover -s tests -v
python3 plugins/compact-codebase/skills/compact-codebase-context/scripts/repo_context.py doctor --root . --source-mode git

The code uses only the Python standard library.

Contributing

Bug reports, benchmark replications, adversarial repositories, and small focused patches are welcome. Read CONTRIBUTING.md first. Please do not market unverified full-session savings as a project result.

License

MIT. See LICENSE.