How Context Mode Engine works: hooks, sandbox, index

Context Mode Engine adds hooks, an MCP server with nine tools and one SQLite database per project to your coding agent. When a tool call makes big output, the hooks send it to a sandbox and a SQLite FTS5 index on your machine, and the agent reads a short reply with a search hint. Your agent keeps its own permissions, and a hook error lets the call go on as usual.

Free · Local · Private · Yours to keep

Context Mode Engine is source-available under the Elastic License 2.0. Use it, copy it, change it and share it at zero cost, for as long as you follow the licence terms. It runs on your machine, sends zero usage data, and keeps your data in ~/.context-mode.

What does the plugin do to my agent?

You add a plugin, and it sits between your agent and its tools. Before you trust it, you want to know three things: what it reads, what it changes and what it gives back to the model.

The answer is short. Context Mode Engine listens to a few hook events. It reads your deny rules first. It sends big output to a local sandbox and index. The agent then reads a short reply and searches the rest when it needs it.

One example: before and after

Your agent runs a vitest suite of 1106 tests. The suite prints 61.4 KB.

The model reads 99% fewer bytes for this call. Median of 5 runs on an Apple M1 Pro, benchmark of 2026-11-01 (raw file). The rest of this page shows each step that makes this happen.

Four words on this page

PreToolUse

The event your agent fires just before it calls a tool.

PostToolUse

The event your agent fires just after a tool call ends.

MCP

Model Context Protocol, the standard way an agent connects to extra tools. The nine ctx_ tools come in through it.

FTS5

The full-text search part of SQLite. It finds words in stored output fast.

The hooks it adds

Your agent fires an event at each point of its work. Context Mode Engine listens to these events and does one job at each one.

Each agent keeps its own event names. Gemini CLI, for example, uses BeforeAgent, BeforeTool and AfterTool. The full table is on Agents.

Follow one tool call

Here your agent runs the test suite. The output is 61.4 KB. Step through what happens to it.

Before a tool call: your deny rules come first

Your agent keeps its own permissions: its prompts, its allow and deny lists and its own sandbox. PreToolUse checks rules in a fixed order:

1. Your deny list. On Claude Code it reads .claude/settings.local.json, then .claude/settings.json in the project, then your user settings.json, and applies them to Bash and Read.
2. WebFetch. It sends the page to ctx_index, and the agent searches it with ctx_search.
3. curl, HTTP and build commands, on agents that send the call to a ctx_ tool before it runs.
4. Read and shell dumps. A full-file Read of a file over 16,384 B gets a message that names the exact ctx_execute call to use. A Read with a range runs as usual.

Set CONTEXT_MODE_REQUIRE_SECURITY=1 to turn a read error on a policy file into a deny.

After a tool call: big output goes to the index

PostToolUse logs each call in context.db, the database for this project. When the output of a host tool is over 4,096 B, it splits the output into chunks and indexes all of it.

On Claude Code, Gemini CLI, Copilot CLI and Pi, the agent then gets the best-matching whole chunks and a ctx_search line in place of the full output. On the other agents, PreToolUse sends the big call to a ctx_ tool first, so the same short reply comes back. The full output stays in the index, word for word, until the agent asks for more.

The index lives at ~/.context-mode/projects/<projectKey>/context.db, one database per project, outside your repo.

A hook error lets the call go on

A hook always exits 0. On any error, it gives the agent's "allow" reply and writes one line to ~/.context-mode/hook-errors.log. Your agent keeps working, and you can read the log later. A spawned hook stops after 5,000 ms.

To check the hooks on your machine, run context-mode doctor. Its D5 check makes one hook call and shows the result. See Doctor.

What it costs in time

A hook adds 7.3 ms to 14.6 ms over a bare node start, per agent. A ctx_search call takes 1.7 ms median (range 1.6-2.0 ms), over 20 queries on 8 indexed files. Each figure is the median of 5 runs on an M1 Pro with Node 26.8.1, from the 2026-10-31 benchmark (raw file, source on GitHub).

What you get

Your agent works as before, with the same tools and the same permissions. Big output goes to a sandbox and index on your machine, and the model reads a short reply. You get more room in the context window for your own work, at zero cost.

Next, see how the sandbox runs code and keeps only what it prints.