omp-load injects the full contents of local files, directories, and glob matches into an Oh My Pi turn — the whole haul, delivered before the model gets to ask.
A native @file reference is polite: it points at things. @load is not polite. It eagerly reads every eligible match and drops the results in as a hidden user-attributed message before the agent starts. Your prompt stays clean; the model wakes up already knowing the codebase.
Front-loading context is also an economic decision. Agentic file exploration is paid for in output tokens: every read round trip is decoding, and with frontier models pricing decoding the way Fable 5 does, watching an agent narrate its way through a directory tree is watching money evaporate. One eager injection up front, and the expensive tokens go to the actual work.
- Oh My Pi 17.0.4 or newer
- Bun 1.3.14 or newer
No runtime dependencies outside the OMP host. It's one file.
Install directly from GitHub:
omp plugin install github:pahorema/omp-loadFor local development, clone the repository and link it:
git clone https://github.com/pahorema/omp-load.git
cd omp-load
omp plugin link .Or go full artisanal and just copy the file:
cp index.ts ~/.omp/agent/extensions/omp-load.tsRestart OMP after installing or copying the extension.
A directive fires only when it owns an entire line — mentioning @load mid-sentence does nothing.
@load src test README.md
With glob patterns and exclusions:
@load "src/**/*.ts" README.md !"src/**/*.test.ts" !fixtures
Paths containing spaces can be quoted:
@load "docs/design notes.md"
With no included path, the current working directory is loaded — which makes an exclusion-only directive a perfectly good way to say "everything except the junk":
@load !dist !coverage !"**/*.snap"
Multiple @load lines in one prompt are combined. Files are de-duplicated by resolved path.
The directive fires wherever a turn starts, not only in prompts you type. In OMP the main agent can place a standalone @load line inside a subagent's task prompt to inject the crates or packages that subagent must work on directly into its context. The subagent starts with the code already loaded instead of spending its opening turns — and your decoding budget — rediscovering the tree.
@load crates/parser crates/lexer !"**/*.snap"
@loadViaImage src
@loadViaImage renders the loaded text into PNG pages typeset like a tiny newspaper: monospace columns, gutter rules, 7 px JetBrains Mono. Yes, it sends your code to the model as pictures. Yes, that is cheaper — see the receipts below. The idea comes from DeepSeek-OCR: Contexts Optical Compression, but the pages ride OMP's normal vision input; no DeepSeek-OCR involved.
Optical mode engages only when the active model accepts image input and Bun.Image is available; otherwise the extension quietly falls back to plain text. Every rendered page is attached, so the model's image and context limits are the practical ceiling. Non-ASCII characters outside a small typography map render as ? — when a byte-exact value matters (hashes, keys), re-read it from disk instead of trusting the model's eyesight.
Measured with bench/optical-stats.ts against Anthropic's /v1/messages/count_tokens endpoint (claude-sonnet-4-5, message overhead subtracted) on a real ~20-package TypeScript monorepo — actual tokenizer, actual image pricing, no proxy BPE hand-waving:
| Corpus | Files | KB | @load tokens |
@loadViaImage tokens |
Pages | Savings |
|---|---|---|---|---|---|---|
| Whole-project spec (one Markdown file) | 1 | 60 | 17,464 | 18,374 | 12 | 0.95x |
docs/**/*.md |
22 | 71 | 20,653 | 9,566 | 6 | 2.16x |
One package (packages/simulation/**/*.ts) |
16 | 228 | 72,104 | 33,727 | 22 | 2.14x |
Apps (apps/**/*.ts) |
12 | 111 | 35,027 | 16,996 | 11 | 2.06x |
All packages (packages/**/*.ts) |
142 | 969 | 313,649 | 144,400 | 94 | 2.17x |
| Total | 458,897 | 223,063 | 2.06x |
A page costs a flat ~1,522 tokens (API-measured; theory says 1568x733/750 = 1,533) whether it holds a shopping list or half a compiler. Savings therefore scale with how densely text packs into pages: source code and structured Markdown land around 2.1x, while long-line prose that hard-wraps the full column width fights the tokenizer to a draw — SPECS.md above actually lost by 5%. Rule of thumb: pictures for code, plain @load for the one giant design document.
Run it on your own corpus:
ANTHROPIC_API_KEY=... bun bench/optical-stats.ts --cwd <repo> "src/**/*.ts" "docs/**/*.md"- Directories are traversed recursively in deterministic name order.
- Glob results are sorted before loading.
- Duplicate resolved paths are loaded once.
- Symbolic links are ignored.
- PDFs are converted to Markdown through OMP's Markit document extractor.
- Binary/media files, generated directories, caches, dependency trees, lockfiles, editor state, and common secret-bearing paths are ignored.
.env*, private-key formats, credential files, and common credential directories are ignored even when requested explicitly.- Unreadable, missing, excluded, binary, or unsupported explicit paths appear in a
Skippedsection, de-duplicated and capped at 20 entries. - Glob patterns support
*,?,[…], and{a,b}alternation viaBun.Glob. - Bare-word tokens with no path separator, extension, or glob construct that fail to resolve are treated as trailing prose and collapsed into a single summary line instead of per-token errors.
Loaded contents are sent to the active model provider as part of the turn. display: false only hides the injected message from the transcript UI; it is not a privacy boundary.
Review broad directory loads before submitting them. The built-in denylist reduces accidental credential exposure but cannot recognize every secret filename or sensitive document. Use explicit paths and !exclusions for repositories containing confidential data.
Loaded files are untrusted model input. A file can contain prompt-injection text even when it is valid source code or documentation.
The extension performs no network requests itself. It reads local paths only in response to a standalone directive in the submitted prompt.
The extension is released under the MIT License.
The embedded glyph bitmap used by optical mode is derived from JetBrains Mono and remains covered by the SIL Open Font License 1.1.