Context Mode 2.0: what we rebuilt and what we learned

November 2, 2026Release8 min read

Context Mode 2.0 is here. Context Mode is a free plugin for coding agents, with its source open on GitHub. It runs on your machine, keeps raw tool output in a local index, and gives your agent the part it asks for. It sends zero telemetry, works offline after install, and runs in 10 agents: Claude Code, Codex, Gemini CLI, Qwen Code, Pi, OpenCode, Copilot CLI, Kiro, VS Code and ZCode.

2.0 installs from the next channel today, as version 2.0.0-next.27. Use the steps in Start now.

TL;DR

• We took the 357 open issues and PRs, read 351 in full, and wrote one outcome for each row. 124 real bugs became tests.
• Each agent installs Context Mode with its own command: its marketplace, its extensions or its package manager.
• Hooks, MCP and skills run in all 10 agents. CI checks all 10 on Linux, macOS and Windows.
• 2,071 tests in 34 files. A median saving of 99.4% on the 36 bench rows with 10 KB or more of raw output.

What Context Mode does

A coding agent reads tool output into its context window: a test log, a git history, a large JSON reply. Context Mode takes that output in a hook, runs it in a local sandbox and indexes it in SQLite. Your agent gets a short answer and searches the rest when it needs it. Every index lives in ~/.context-mode, one context.db per project. It is free at home and at work, under the Elastic License 2.0.

Why we rebuilt it

The 1.x line grew fast. From the first commit on 2026-02-23, people opened 590 issues and 659 PRs. We closed 416 of those issues and merged 258 PRs (our snapshot of 2026-10-14). Each fix made sense on its own day. Together they left us with fallback chains, heal scripts that ran npm on your machine, hooks that did heavy work, and one test file per fix.

On 2026-10-13 we started 2.0 from one written plan: one path per agent, light hooks, each agent's own install, and a test first for every real bug. The plan is public: PRD.md and 23 decision records.

The numbers

• 357 open issues and PRs at the start: 174 issues and 183 PRs. We read 351 in full, merged the duplicates, and wrote one outcome for each of the 328 rows that remained: 159 closed by design, 111 covered by a test, 55 closed with a written reason, 2 merged, 1 waiting for a check (the outcome table).
• 124 real bugs from the 1.x line became contract tests, and we rebuilt 33 more PRs as tests.
• 2,081 commits and 27 pre-releases, from 2.0.0-next.1 on 2026-10-27 to 2.0.0-next.27 on 2026-11-02.
• 2,071 tests in 34 files, grouped by decision record. CI is green on Linux, macOS and Windows.
• 147 recorded changes from the plan, each with its file and its test (DEVIATIONS.md).
• 2 tester reports, 3 faults each, 6 fixes. Each reply names the cause, the commit and the step to rerun.
• 99.4% median saving on the 36 bench rows with 10 KB or more of raw output, each row the median of 5 runs (bench results).
• 8 of 8 try-it prompts gave an answer that matched the source data, with savings from 95.7% to 99.96%. One API reply of 1,039,898 B reached the agent as 393 B (try-it evidence).

All of this rests on the 1.x line and the people who used it: 33K GitHub stars and 683K npm downloads.

What we learned

Eight lessons. Each one has what we saw in the 1.x line, what we decided, what changed, and the file that shows it.

1. A hook stays light

In the 1.x line, hooks opened the database, started child processes and called the network. One report measured 55 to 70 ms of CPU per Bash call. We decided that a hook reads the event and returns a decision, and the database, the network and child processes stay in the server. The design target for an idle server is 0% CPU. A hook now adds 7.5 ms to 12.3 ms per tool call over a bare node start, and every hook entry has a timeout. Source: PRD principles P4 and P5.

2. Each agent installs with its own command

The 1.x line installed packages at run time and ran heal scripts on your machine. On Windows, npm retried in a loop. We decided to bundle every dependency (ADR-0002) and to use each agent's own install (ADR-0023). Claude Code and Codex now install from their plugin marketplace, Gemini CLI and Qwen Code from their extensions, Pi and OpenCode from their own package command, and the other four with npm and one setup step. Setup saves your old config first and puts it back if a step ends early. Source: ADR-0023.

3. One path per agent

Fallback chains and platform probes in the 1.x line sometimes wrote data to the wrong store. We decided on one path, and the same code on every agent: agents differ in transport alone. Each project now has one context.db under ~/.context-mode. Source: ADR-0002.

4. Keep the whole output

The 1.x line cut long output to its head and tail, or to the last 30 lines of a build. The answer often sat in the middle. We decided to index the whole output and return the part the agent asks for. ctx_search finds the rest. Source: NO-LOSSY-CUT.md and ADR-0008.

5. Hooks in every agent

Some agents in the 1.x line had MCP alone. The model ran raw commands, and the output filled its context. We decided that every agent gets hooks and skills (ADR-0020). All 10 agents now get hooks, MCP and skills. Real agent binaries ran the hooks for 8 agents, and we checked VS Code and Kiro at hook setup. CI runs setup, doctor, a hook and an MCP handshake for all 10 agents on Linux, macOS and Windows. Source: HOOKS-FIRE.md.

6. Test first, grouped by decision

The 1.x line had 210 test files, most of them one per fix. We decided that every real bug gets a golden-path test before its code (ADR-0017), and that tests live in one file per decision record (ADR-0024). 2.0 has 34 test files, and they run in parallel. Source: ADR-0024.

7. Windows gets the same care

On Windows, the 1.x line had a bare npx in configs, PowerShell hooks and path labels with backslashes. We decided on an absolute node path in every config, Git Bash for shell tools, and one path label form on every OS. Schema version 6 renames old labels in place. CI now runs on Windows, and a Windows tester's 3 reports were fixed in 2.0.0-next.24. Source: the reply to the Windows tester.

8. The doctor checks what the agent sees

In a 2.0 test build, a tester saw the trust check pass while Codex had yet to trust the hooks. We decided on one resolver for the Codex home, and the check now passes when Codex itself lists every plugin hook as trusted. The fix shipped in 2.0.0-next.25. Source: the reply to the tester.

What got better for you

• Install the way your agent installs everything else. Your agent's own command, and one check after it.
• Hooks in all 10 agents. Large output goes to the index from the first tool call.
• A doctor with one row per check. ctx_doctor reads your setup and prints the command that fixes each row that needs work.
• Fast search. ctx_search answers in 1.62 ms at the median over 20 queries, and ctx_index takes 150 ms per MB.
• Long sessions. After the agent compacts, Context Mode builds a block of at most 2,048 bytes from this session's journal: your last request, open errors and changed files. It picks whole items by rules, with zero model calls. A large item becomes a pointer the agent can open.
• Private by design. Zero telemetry, and a CI test keeps the short list of network calls fixed. Read more on plugin privacy.

Context Mode Gateway

The plugin works on tool output, on your machine, per project, and it is complete on its own. Context Mode Gateway is a separate hosted service with its own account and subscription. It applies the same idea to the whole conversation, on every request, across all your agents. It adds Recall, Memory, Skills, Search and Session resume. With the Gateway on, your requests pass through its server on the way to the model, and it keeps a searchable record of your sessions. Install the plugin first, and connect the Gateway when you want the same memory across tools. See the Gateway and its privacy page.

What comes next

• 2.0 moves to the main branch. The first release from main goes out on the next channel, we check each agent's own install from main, and then the stable release makes 2.x the npm latest.
• Open design questions stay on the list, such as PowerShell hooks on Windows, a retrieval mode for OpenCode, and a token budget for tool descriptions.
• Requests for new agents are open.

Start now

Pick your agent. Each one installs Context Mode with its own command. Then run the check.

claude plugin marketplace add mksglu/context-mode#release
claude plugin install context-mode@context-mode

/ctx-doctor

claude plugin update context-mode@context-mode

context-mode setup --remove --agents claude-code

codex plugin marketplace add mksglu/context-mode@release
codex plugin add context-mode@context-mode

npm i -g context-mode@next
context-mode setup --agents codex

/ctx-doctor

codex plugin marketplace upgrade context-mode

context-mode setup --remove --agents codex

gemini extensions install https://github.com/mksglu/context-mode --ref release

/ctx-doctor

gemini extensions update context-mode

context-mode setup --remove --agents gemini
gemini extensions uninstall context-mode

qwen extensions install https://github.com/mksglu/context-mode:context-mode --ref release

/ctx-doctor

qwen extensions update context-mode

context-mode setup --remove --agents qwen
qwen extensions uninstall context-mode

pi install npm:context-mode@next

pi list

pi update --extensions

pi remove npm:context-mode@next

opencode plugin add context-mode@next

opencode plugin context-mode@next --global

/ctx-doctor

opencode plugin update

opencode plugin remove context-mode@next
context-mode setup --remove --agents opencode

npm i -g context-mode@next
context-mode setup --agents copilot-cli

/ctx-doctor

context-mode upgrade

context-mode setup --remove --agents copilot-cli

npm i -g context-mode@next
context-mode setup --agents kiro

/ctx-doctor

context-mode upgrade

context-mode setup --remove --agents kiro

npm i -g context-mode@next
context-mode setup --agents vscode

/ctx-doctor

context-mode upgrade

context-mode setup --remove --agents vscode

npm i -g context-mode@next
context-mode setup --agents zcode

/ctx-doctor

context-mode upgrade

context-mode setup --remove --agents zcode

Full steps for each agent: the install guide. The source is on GitHub.

Thank you

Thank you to the two testers who reran every step and wrote up each fault they found. Thank you to the 100+ people with code in the 1.x line, and to everyone who opened one of its 590 issues and 659 PRs. Each of the 357 open ones got a written outcome, and 124 became tests.