🇺🇸 English | 🇯🇵 日本語 | 🇨🇳 简体中文 | 🇸🇦 العربية | 🇮🇩 Bahasa Indonesia | 🇻🇳 Tiếng Việt | 🇰🇷 한국어
brew install fajarhide/tap/omni && omni init
What it does
Drops the noise. Build logs, Docker layer hashes, progress bars, ANSI colour. The part of the output nobody reads is removed before it reaches the model.
Stops re-sending what the agent has already seen. A run of lines it was shown earlier in the session comes back as one marker with a handle, not as the bytes again. This is the half a filter cannot do: it removes bytes because they are already in the context, not because a pattern calls them noise.
Remembers across sessions. Restart your editor or switch agents, and the project context is still there.
Gets out of the way. A failing command passes through verbatim. JSON, YAML and CSV are never touched. Most commands are handed back unchanged, and that is the intended behaviour rather than a gap.
It runs as two hooks around a tool call your agent host already makes. Nothing proxies your shell, and the database never leaves the machine.
The second read is free
An agent re-reads the same file constantly. Without OMNI it pays for every byte
again. With OMNI the second read is one marker carrying a handle, because those bytes
are already in its context, and omni retrieve <hash> hands the file back in full if
it is ever needed.
This is the half a filter cannot reach. No pattern in that file is noise, so nothing in it can be dropped on its own merits. It goes because the agent has already seen it.
The same git log, side by side
Without OMNI, one commit's Author / Date / body already fills the screen. With
OMNI, every commit is kept, as one hash subject line. Nothing is summarised away.
Measured on the fixtures in tests/fixtures/, so you can reproduce any row:
| Command | Without OMNI | With OMNI | Saved |
|---|---|---|---|
cargo test (490 passed, 10 failed) |
16.5 KB of per-test output | the runner's own pass/fail summary | 93.0% |
git status (dirty) |
496 B of porcelain | the branch and the changed paths | 66.7% |
docker build (heavy cache noise) |
9.2 KB of layer hashes and progress bars | the build result, cache hits folded | 98.9% |
git diff (multi-file) |
lockfiles, whitespace, generated churn | the code that actually changed | 37.8% |
kubectl get pods (35 pods, 5 crashing) |
the full table | the full table | 0%, by design |
That last row is the point of the table. A pod listing is an enumeration where every row is a datum, so there is nothing to drop, and OMNI reports nothing rather than inventing a saving.
Nothing is ever lost. It never makes something up.
Four guarantees, each one a link to the code or the issue that made it true rather than a sentence asking you to trust it.
| Guarantee | How | Proof |
|---|---|---|
| Get the original back, byte-for-byte | everything cut is archived in a local SQLite RewindStore; the marker carries a handle, and omni retrieve <handle> prints it on any host, with the omni_retrieve MCP tool where MCP is wired |
#388 |
| Never fabricates a result | a distiller that parsed no signal returns the raw output, never a green no errors / passed string |
#143 |
| Failures are never masked | a command that exits non-zero passes through verbatim | #120 |
| Structured data is never touched | JSON / YAML / NDJSON / CSV pass through byte-for-byte | pipeline::format |
What OMNI remembers, and for how long
Three tiers, already in the schema, never written down until now. The short answer to "will OMNI still know my project after a month away" is yes for the conclusions and no for the raw bytes.
| Tier | What | Kept |
|---|---|---|
| Permanent | project knowledge, recurring error patterns, engrams, goal memory | until you delete it, except goal memory, which honours its own ttl_days |
| Working, 30 days | sessions, distillation rows, hot files, the RewindStore, the event index, the ledger | rolling window |
| Verbatim, 7 days | execution_traces and the session transcript |
shorter on purpose: it is two orders of magnitude heavier per row |
The boundary this sets is worth stating plainly, because it is the one thing a handle
cannot promise: omni retrieve for content archived more than 30 days ago will not
resolve. Hold the shortest window open while measuring with
OMNI_TRACE_RETENTION_DAYS=90.
omni reset wipes all of it, and omni doctor shows the live counts.
What each host lets OMNI do
| Tier | Hosts | What you get |
|---|---|---|
| Full | Claude Code, Codex CLI, Gemini CLI, Aider (pipe) | The host applies OMNI's rewrite, so the model reads distilled output from its own built-in tools. |
| Handoff-first | Cursor, Windsurf | The host cannot rewrite built-in tool output. omni_run distils anything you route through it, and omni init --cursor installs the rule that makes the agent reach for it. |
| MCP-only | Cline, Roo, OpenCode, VS Code, Zed, Copilot, Antigravity, Hermes, Pi | Memory, recall and session state. No shell distillation, and no claim of it. |
omni doctor prints the tier for every installed host. Savings are only ever counted
where the model actually received less.
Codex CLI needs one extra step. It runs only hooks it has been told to trust and skips
the rest without a word, so after omni init --codex start codex once and approve
them under "Hooks need review". omni doctor fails until you do. See
#359.
Install
macOS / Linux:
brew install fajarhide/tap/omni
omni init # interactive setup for Claude, Cursor, VS Code, Codex, Antigravity
omni doctor # verify, or `omni doctor --fix`
Universal (macOS / Linux / WSL):
curl -fsSL omni.weekndlabs.com/install | bash
Windows (PowerShell):
irm omni.weekndlabs.com/install.ps1 | iex
Claude Code, from inside the session:
/plugin marketplace add fajarhide/omni
/plugin install omni@omni
Any agent that reads skills, listed at skills.sh/fajarhide/skills/omni:
npx skills add fajarhide/skills --skill omni
Both install a skill, not the binary. The skill is what tells the agent how to get the binary, verify it, and read the markers OMNI leaves when it shortens output.
Then run your commands normally. There is nothing to prefix and no proxy to wrap.
Numbers
Every figure OMNI publishes states the corpus it came from and the week it covers,
because execution_traces is pruned after seven days and a n