Install
Existing installs keep working under omni, which is the same program as contexere.
Get the binary
macOS and Linux, via Homebrew:
brew install fajarhide/tap/contexere
macOS, Linux, WSL:
curl -fsSL omni.weekndlabs.com/install | bash
Windows, PowerShell:
irm omni.weekndlabs.com/install.ps1 | iex
From source, which needs the toolchain pinned in rust-toolchain.toml:
git clone https://github.com/fajarhide/contexere
cd contexere
cargo build --release
From inside Claude Code, if you would rather have the agent do the rest:
/plugin marketplace add fajarhide/contexere
/plugin install contexere@omni
On any agent that reads skills, the same skill installs through the skills directory CLI:
npx skills add fajarhide/contexere --skill contexere
Either way that installs a skill, not the binary. The skill carries the install commands below, the verification step, and how to read the markers, so the agent stops guessing at any of the three. Everything on this page still applies; the plugin only means someone else types it.
Wire it into your agent
contexere init # the host you are running in, or a menu if you have a terminal
contexere init --claude # or --cursor, --codex, --gemini, and 11 more
contexere init --all # every host, and a .vscode/mcp.json in the current directory
contexere init writes hooks and registers the MCP server. It is idempotent, so running it
again after an upgrade is the right move rather than a risk.
On Claude Code the hooks are the part that shortens output, and the MCP server is a convenience with a cache cost. Keeping it is fine; knowing what it costs is in Supported agents.
With no terminal to prompt on, which is how an agent runs it, contexere init configures
the host it is running inside instead of failing on the absent menu. It says which
host it picked. If it cannot name the host, a plain shell for instance, it stops and
asks for a flag rather than installing into somewhere nobody asked for.
Every supported flag is in init. Which hosts get what is in Supported agents, and that page matters more than it sounds: a host that cannot rewrite its own shell tool’s output will not show the agent distilled bytes however well the pipeline works.
Verify
contexere doctor
This is not optional ceremony. It checks the binary is on PATH, the database opens,
the hooks are actually installed where the host reads them, and the MCP server is
registered. contexere doctor --fix repairs what it can.
Codex CLI needs one extra step. It runs only hooks it has been told to trust and
skips the rest silently. After contexere init --codex, start codex once and approve
them under “Hooks need review”. contexere doctor will keep failing until you do.
Confirm it is really running
contexere doctor says the wiring is correct. This says the wiring is being used:
cat some-long-file.txt # through your agent, not this shell
contexere diff # raw against distilled, for the last command
contexere stats
If contexere stats shows rows and contexere diff shows a difference, the hook is live.
A trap worth knowing now rather than later: the numbers in contexere stats are split by
agent_id, and a row recorded under terminal is TTY output no model ever read.
When you are judging whether Contexere is earning its place, look at the rows for your
actual host.
Upgrade
contexere update # Homebrew installs
brew upgrade contexere
Installed before 0.8.2 as omni? The formula is now contexere, and Homebrew skips a renamed formula from a tap until you trust it. brew upgrade then says nothing and stays on the old version. Run this once:
brew trust --tap fajarhide/tap && brew upgrade fajarhide/tap/contexere
Re-run contexere init afterwards if a release changes the hook contract. The changelog
says when that happens.
Moving off the omni name
Contexere was called OMNI until 0.8.0, and the old names still work. They stop working in 0.9.0 (#1067):
| old name | becomes | what to do |
|---|---|---|
the omni command | contexere | run contexere init --<host> for each agent you use (--claude, --codex, --cursor and so on); each run rewrites that agent’s hooks and MCP entry |
OMNI_* settings | CONTEXERE_* | rename them in your shell profile or CI; CONTEXERE_* already wins when both are set |
omni_* MCP tools | contexere_* | nothing, once contexere init has replaced the MCP entry |
the [OMNI marker | [CONTEXERE | update any script or skill of your own that matches the prefix |
the ~/.omni directory | ~/.contexere | nothing; your history is kept |
The directory moves on the first run, in one rename, database and archive included, and ~/.omni stays behind as a link to it so an omni release still finds its data. The database keeps its omni.db name. If the move cannot happen, Contexere keeps reading ~/.omni where it is.
contexere doctor lists everything on your machine that still uses an old name, so you can tell which agents are left.
Remove it
contexere init --uninstall # hooks and MCP registration for one host
contexere reset --all # every integration, and offers to wipe the database
contexere reset without flags gives an interactive menu. Neither command touches your
shell configuration, because Contexere never wrote any.