Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

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 namebecomeswhat to do
the omni commandcontexererun 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_* settingsCONTEXERE_*rename them in your shell profile or CI; CONTEXERE_* already wins when both are set
omni_* MCP toolscontexere_*nothing, once contexere init has replaced the MCP entry
the [OMNI marker[CONTEXEREupdate any script or skill of your own that matches the prefix
the ~/.omni directory~/.contexerenothing; 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.