# Context Mode 2.0: what we rebuilt and what we learned November 2, 2026 Release 8 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](#start). ## 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](https://github.com/mksglu/context-mode/blob/d873866d92ec9a1db0c48ecda123a27f5b0debac/docs/architecture/PRD.md) and [23 decision records](https://github.com/mksglu/context-mode/tree/d873866d92ec9a1db0c48ecda123a27f5b0debac/docs/architecture/adr). ## 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](https://github.com/mksglu/context-mode/blob/274600e2ffab843e89c1dfa09b0d649e650c962f/docs/v2/review/ISSUE-OUTCOMES-r4.md)). - **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](https://github.com/mksglu/context-mode/actions/runs/41429664114) on Linux, macOS and Windows. - **147 recorded changes** from the plan, each with its file and its test ([DEVIATIONS.md](https://github.com/mksglu/context-mode/blob/d873866d92ec9a1db0c48ecda123a27f5b0debac/docs/architecture/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](https://github.com/mksglu/context-mode/blob/d873866d92ec9a1db0c48ecda123a27f5b0debac/bench/results/2026-11-01-darwin-arm64.md)). - **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](https://github.com/mksglu/context-mode/blob/d873866d92ec9a1db0c48ecda123a27f5b0debac/bench/evidence/try-it-2026-11-02/README.md)). 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](https://github.com/mksglu/context-mode/blob/d873866d92ec9a1db0c48ecda123a27f5b0debac/docs/architecture/PRD.md#2-principles). ### 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](https://github.com/mksglu/context-mode/blob/d873866d92ec9a1db0c48ecda123a27f5b0debac/docs/architecture/adr/ADR-0023-native-install.md). ### 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](https://github.com/mksglu/context-mode/blob/d873866d92ec9a1db0c48ecda123a27f5b0debac/docs/architecture/adr/0002-single-db-git-distribution.md). ### 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](https://github.com/mksglu/context-mode/blob/d873866d92ec9a1db0c48ecda123a27f5b0debac/docs/architecture/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](https://github.com/mksglu/context-mode/blob/d873866d92ec9a1db0c48ecda123a27f5b0debac/docs/architecture/release/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](https://github.com/mksglu/context-mode/blob/d873866d92ec9a1db0c48ecda123a27f5b0debac/docs/architecture/adr/0024-test-layout-by-adr.md). ### 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](https://github.com/mksglu/context-mode/blob/d873866d92ec9a1db0c48ecda123a27f5b0debac/docs/architecture/release/windows-retest-2026-11-01-reply.md). ### 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](https://github.com/mksglu/context-mode/blob/d873866d92ec9a1db0c48ecda123a27f5b0debac/docs/architecture/release/candidate-baaa3149-retest-reply.md). ## 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](https://contextmode.ai/docs/engine/privacy?utm_source=blog&utm_medium=social&utm_campaign=launch-2-0). ## 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](https://contextmode.ai/?utm_source=blog&utm_medium=social&utm_campaign=launch-2-0) and [its privacy page](https://contextmode.ai/privacy?utm_source=blog&utm_medium=social&utm_campaign=launch-2-0). ## 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 Code Plugin. Context Mode installs with the agent's own plugin command. Install ``` claude plugin marketplace add mksglu/context-mode#release claude plugin install context-mode@context-mode ``` Check ``` /ctx-doctor ``` **Update and remove** Update ``` claude plugin update context-mode@context-mode ``` Remove ``` context-mode setup --remove --agents claude-code ``` The hook check passed on 2026-10-26 with Claude Code 2.1.309. [Source: the install guide](https://github.com/mksglu/context-mode/blob/baaa3149e881980288944e90179895fa6a2be13e/docs/install/README.md) ### Codex Plugin. Context Mode installs with the agent's own plugin command. Install ``` codex plugin marketplace add mksglu/context-mode@release codex plugin add context-mode@context-mode ``` Next, trust the hooks ``` npm i -g context-mode@next context-mode setup --agents codex ``` Check ``` /ctx-doctor ``` **Update and remove** Update ``` codex plugin marketplace upgrade context-mode ``` Remove ``` context-mode setup --remove --agents codex ``` The hook check passed on 2026-10-26 with Codex 0.164.0. [Source: the install guide](https://github.com/mksglu/context-mode/blob/baaa3149e881980288944e90179895fa6a2be13e/docs/install/README.md) ### Gemini CLI Plugin. Context Mode installs with the agent's own plugin command. Install ``` gemini extensions install https://github.com/mksglu/context-mode --ref release ``` Check ``` /ctx-doctor ``` **Update and remove** Update ``` gemini extensions update context-mode ``` Remove ``` context-mode setup --remove --agents gemini gemini extensions uninstall context-mode ``` The hook check passed on 2026-10-26 with Gemini CLI 0.65.0. [Source: the install guide](https://github.com/mksglu/context-mode/blob/baaa3149e881980288944e90179895fa6a2be13e/docs/install/README.md) ### Qwen Code Plugin. Context Mode installs with the agent's own plugin command. Install ``` qwen extensions install https://github.com/mksglu/context-mode:context-mode --ref release ``` Check ``` /ctx-doctor ``` **Update and remove** Update ``` qwen extensions update context-mode ``` Remove ``` context-mode setup --remove --agents qwen qwen extensions uninstall context-mode ``` The hook check passed on 2026-10-26 with Qwen Code 0.26.1. [Source: the install guide](https://github.com/mksglu/context-mode/blob/baaa3149e881980288944e90179895fa6a2be13e/docs/install/README.md) ### Pi Plugin inside the agent. The agent loads Context Mode as a plugin in its own process. Its tools come from that plugin. Install ``` pi install npm:context-mode@next ``` Check ``` pi list ``` **Update and remove** Update ``` pi update --extensions ``` Remove ``` pi remove npm:context-mode@next ``` @next is the npm tag of the newest Context Mode release. The hook check passed on 2026-10-26 with Pi 0.73.1. [Source: the install guide](https://github.com/mksglu/context-mode/blob/baaa3149e881980288944e90179895fa6a2be13e/docs/install/README.md) ### OpenCode Plugin inside the agent. The agent loads Context Mode as a plugin in its own process. Its tools come from that plugin. Install ``` opencode plugin add context-mode@next ``` ``` opencode plugin context-mode@next --global ``` Check ``` /ctx-doctor ``` **Update and remove** Update ``` opencode plugin update ``` Remove ``` opencode plugin remove context-mode@next context-mode setup --remove --agents opencode ``` @next is the npm tag of the newest Context Mode release. The hook check passed on 2026-10-26. Install and hooks are checked. The plugin's tool name gets its check in a live OpenCode session next. [Source: the install guide](https://github.com/mksglu/context-mode/blob/baaa3149e881980288944e90179895fa6a2be13e/docs/install/README.md) ### Copilot CLI npm and setup. Install Context Mode with npm. Then setup adds its hooks to the agent. Install ``` npm i -g context-mode@next context-mode setup --agents copilot-cli ``` Check ``` /ctx-doctor ``` **Update and remove** Update ``` context-mode upgrade ``` Remove ``` context-mode setup --remove --agents copilot-cli ``` @next is the npm tag of the newest Context Mode release. The hook check passed on 2026-10-26 with Copilot CLI 1.0.103. [Source: the install guide](https://github.com/mksglu/context-mode/blob/baaa3149e881980288944e90179895fa6a2be13e/docs/install/README.md) ### Kiro npm and setup. Install Context Mode with npm. Then setup adds its hooks to the agent. Install ``` npm i -g context-mode@next context-mode setup --agents kiro ``` Check ``` /ctx-doctor ``` **Update and remove** Update ``` context-mode upgrade ``` Remove ``` context-mode setup --remove --agents kiro ``` @next is the npm tag of the newest Context Mode release. Checked at hook setup on 2026-10-26. A live run in the host app comes next. [Source: the install guide](https://github.com/mksglu/context-mode/blob/baaa3149e881980288944e90179895fa6a2be13e/docs/install/README.md) ### VS Code npm and setup. Install Context Mode with npm. Then setup adds its hooks to the agent. Install ``` npm i -g context-mode@next context-mode setup --agents vscode ``` Check ``` /ctx-doctor ``` **Update and remove** Update ``` context-mode upgrade ``` Remove ``` context-mode setup --remove --agents vscode ``` @next is the npm tag of the newest Context Mode release. Checked at hook setup on 2026-10-26. A live run in the host app comes next. [Source: the install guide](https://github.com/mksglu/context-mode/blob/baaa3149e881980288944e90179895fa6a2be13e/docs/install/README.md) ### ZCode npm and setup. Install Context Mode with npm. Then setup adds its hooks to the agent. Install ``` npm i -g context-mode@next context-mode setup --agents zcode ``` Check ``` /ctx-doctor ``` **Update and remove** Update ``` context-mode upgrade ``` Remove ``` context-mode setup --remove --agents zcode ``` @next is the npm tag of the newest Context Mode release. The hook check passed on 2026-10-26. [Source: the install guide](https://github.com/mksglu/context-mode/blob/baaa3149e881980288944e90179895fa6a2be13e/docs/install/README.md) Full steps for each agent: [the install guide](https://contextmode.ai/docs/engine/install?utm_source=blog&utm_medium=social&utm_campaign=launch-2-0). The source is on [GitHub](https://github.com/mksglu/context-mode). ## 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. [Open the Gateway console](https://console.contextmode.ai/login) [All posts](https://contextmode.ai/blog)