mksglu/context-mode

★ 33,774⑂ 2,312

Free, local plugin that keeps tool output out of your coding agent's context window. Sandbox and SQLite FTS5 search, 99% fewer bytes in context.

About mksglu/context-mode

mksglu/context-mode is an open-source project on GitHub, mainly written in JavaScript. Free, local plugin that keeps tool output out of your coding agent's context window. Sandbox and SQLite FTS5 search, 99% fewer bytes in context. It currently holds 33,774 stars and 2,312 forks with 22 open issues, and was last pushed on 2026-11-10 (repository created 2026-02-23).

Project Overview

Git Homed tracks it on the AI Agent Skills Trending board and on the AI AI Agent Skills Trending list.

GitHub Repository Details

Repository mksglu/context-mode · default branch main · size 57264 KB · watchers 108 · source: GitHub REST API and repository README

README

Context Mode

A free, local plugin for 11 coding agents. It keeps tool output out of your agent's context window and keeps all usage data on your machine. The plugin is free forever.

npm downloads GitHub stars Discord License: ELv2

34K GitHub stars · 846K npm downloads (read 2026-11-17, stats.json) · on the Hacker News front page and GitHub Trending: charts and sources

The Context Mode plugin is free and local, with its source open on GitHub. Context Mode Gateway is a separate hosted service with its own account and subscription. It takes the same idea from tool output to the whole conversation: Gateway Recall keeps long sessions searchable, and Gateway Memory shares what your agents learn across sessions and tools. See how the Gateway works

https://github.com/mksglu/context-mode/blob/HEAD/Context Mode plugin: free and local, zero telemetry, the plugin keeps your data on your machine. Bench of 2026-11-01: 99.4% of output bytes saved (median of 36 rows with 10 KB or more of raw output). A full debugging session (row g-session-total): 281,261 B raw to 3,266 B in context, about 70K to 817 tokens (an estimate at 4 B per token). Resume after compaction (row e-long-session): a 442,893 B transcript to a 2,019 B block, about 111K to 505 tokens (an estimate). Runs in 10 coding agents with 9 MCP tools.

Contents: Why · Adoption · Install · Try it · Use cases · Benchmarks · How it works · Tools · Security and privacy · Context Mode Gateway · License · Community

Why

A coding agent reads files, runs commands and fetches pages, and every result goes into its context window. The Context Mode plugin runs that work in a local sandbox, keeps the full output in a SQLite index on your machine, and gives the agent the part it asks for.

Adoption: stars and npm downloads

https://github.com/mksglu/context-mode/blob/HEAD/Line chart of cumulative GitHub stars for mksglu/context-mode since 2026-02-23. A daily job redraws it. https://github.com/mksglu/context-mode/blob/HEAD/Area chart of npm downloads per day for context-mode, the last 90 days. A daily job redraws it.

Open the interactive chart and point at a bar to read its value. Tabs there show days, weeks, months and years. Stars come from the GitHub GraphQL API (starredAt); npm downloads come from api.npmjs.org/downloads/range. The total up to 2026-10-29 is 683K npm downloads (stats.json keeps a daily copy). A daily job redraws both charts.

https://github.com/mksglu/context-mode/blob/HEAD/Companies that stargazers of mksglu/context-mode name in their GitHub profile, Microsoft, Tencent, Alibaba, ByteDance, Google and more.

Starred by engineers at these companies: each name is the company field of 2 or more stargazer profiles, read with the GitHub GraphQL API on 2026-11-01 (data).

Install

Pick your agent: Claude Code · Codex · Gemini CLI · Qwen Code · Pi · OMP · OpenCode · Copilot CLI · Kiro · VS Code · ZCode

Open its block and copy its own install command. Each block also holds the update, check and remove steps, and the Install guide walks through them.

The plugin needs Node 24.15.0 or later, from the engines field in package.json. On Windows, add Git for Windows: the shell tools run in Git Bash, and doctor checks for it. contextmode installs as the npm package and command context-mode. Claude Code, Codex, Gemini CLI and Qwen Code install from GitHub, and each of their commands names the release branch.

Claude Code
claude plugin marketplace add mksglu/context-mode
claude plugin install context-mode@context-mode
# update
claude plugin update context-mode@context-mode

check

claude plugin list

remove

claude plugin marketplace remove context-mode

Hooks ✓ (package) · MCP ✓ · Skills ✓

Codex

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

one-time step: trust the plugin hooks

npm i -g context-mode context-mode setup --agents codex
# update
codex plugin marketplace upgrade context-mode

check

codex mcp list

remove

codex plugin remove context-mode@context-mode

Hooks ✓ (hook file) · MCP ✓ · Skills ✓

Gemini CLI

gemini extensions install https://github.com/mksglu/context-mode
# update
gemini extensions update context-mode

check

GEMINI_CLI_TRUST_WORKSPACE=true gemini mcp list

remove

gemini extensions uninstall context-mode

Hooks ✓ (package) · MCP ✓ · Skills ✓

Qwen Code

qwen extensions install https://github.com/mksglu/context-mode:context-mode
# update
qwen extensions update context-mode

check

qwen extensions list

remove

qwen extensions uninstall context-mode

Hooks ✓ (package) · MCP ✓ · Skills ✓

Pi

pi install npm:context-mode
# update
pi update --extensions

check

pi list

remove

pi remove npm:context-mode

Hooks ✓ (the plugin's own event handlers) · MCP ✓ (ctx tools built into the plugin) · Skills ✓

OMP

omp plugin install context-mode
# update
omp plugin upgrade context-mode

check

omp plugin list

remove

omp plugin uninstall context-mode

Hooks ✓ (the plugin's own event handlers) · MCP ✓ (ctx tools built into the plugin) · Skills ✓

OpenCode

opencode plugin add context-mode
# update
opencode plugin update

check

opencode mcp list --pure # OpenCode 1.19 opencode mcp list --standalone # OpenCode 2

remove

opencode plugin remove context-mode

Hooks ✓ (the plugin's own event handlers) · MCP ✓ · Skills ✓

Copilot CLI

npm i -g context-mode
context-mode setup --agents copilot-cli
# update
context-mode upgrade

check

context-mode doctor --agents copilot-cli copilot mcp list

remove

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

Hooks ✓ (hook file) · MCP ✓ · Skills ✓

Kiro

npm i -g context-mode
context-mode setup --agents kiro
# update
context-mode upgrade

check

context-mode doctor --agents kiro

remove

context-mode setup --remove --agents kiro

Hooks ✓ (hook file) · MCP ✓ · Skills ✓

VS Code (Copilot)

npm i -g context-mode
context-mode setup --agents vscode
# update
context-mode upgrade

check

context-mode doctor --agents vscode

remove

context-mode setup --remove --agents vscode

Hooks ✓ (hook file) · MCP ✓ · Skills ✓

ZCode

zcode plugins marketplace add mksglu/context-mode
zcode plugins install context-mode@context-mode
# update
zcode plugins update context-mode@context-mode

check

zcode plugins list

remove

zcode plugins uninstall context-mode@context-mode

Hooks ✓ (hook file) · MCP ✓ · Skills ✓

The npm route works for every agent:

npm i -g context-mode
context-mode setup

Setup is also the repair. It shows a plan, saves your earlier config, then applies the plan; when a step ends early, it restores the saved config. To uninstall:

context-mode setup --remove
npm rm -g context-mode

Restart the agent, then run /ctx-doctor in it. Each check prints PASS or a fix command, and the Doctor guide explains each check.

How we tested the install

Every agent gets hooks, the MCP server and the plugin skills; the last line of each block above says how. Hooks reach each agent in one of three ways: in the plugin package (Claude Code, Gemini CLI, Qwen Code), in a hook file (Codex, Copilot CLI, Kiro, VS Code, ZCode), or in a plugin inside the agent (OpenCode, Pi, OMP). The Agents guide shows what each agent runs. We ran the real binary of each agent with the plugin hook: Claude Code, Codex, Gemini CLI, Qwen Code, Pi, OpenCode, Copilot CLI and ZCode. Each run used a clean temp home and a local test model, on 2.0.0-next.15. OMP 18.20.0 ran the same way with ADR-0026, and CI installs the real OMP on Linux, macOS and Windows. For VS Code and Kiro, the check covers the hook setup: VS Code runs the hook command with the documented payload, and kiro-cli 2.35.2 loads all 6 hook entries. CI runs setup, doctor, a hook and an MCP handshake for all 11 agents from the packed package on Linux, macOS and Windows. Record: HOOKS-FIRE.md. Each agent uses its own install command, and ADR-0023 says why.

Your first task with the plugin, step by step: First session. Or paste a prompt from Try it right now.

Try it

Paste one of these prompts into your agent after the install. Each one ran once, live, in Claude Code 2.1.312, and its answer matched the source data (evidence and rerun steps). The headline numbers in Benchmarks use the median of 5 runs. Other agents do the same job with the same tools: ctx_execute, ctx_index and ctx_search. After a prompt, run the stats skill and read the report yourself (See the saving).

On https://react.dev/reference/react/useEffect, show me the example that connects to a chat server and cleans up, and list the rules for the dependency array.
The hook sends WebFetch to the sandbox, and the agent searches the page for the example and the rules. 601,984 B raw, 20,860 B reached the context, 96.5% saved (2026-11-02, 2.0.0-next.26, claude-haiku-5-5).
Fetch https://jsonplaceholder.typicode.com/photos. Which photo has the longest title (give its id and title), and how many photos have a title that contains the word "est"?
The agent runs code over 5,000 JSON records in the sandbox and gets back two answers. 1,039,898 B raw, 393 B reached the context, 99.96% saved (2026-11-02, 2.0.0-next.26, claude-haiku-5-5). The answer is two short facts, so this is the best case of the four.
Here is a Linux syslog sample: https://raw.githubusercontent.com/logpai/loghub/master/Linux/Linux_2k.log. How many authentication failures does it contain, and which 3 remote hosts caused the most?
The agent counts failures in a 1,999-line syslog in the sandbox. 216,485 B raw, 566 B reached the context, 99.7% saved (2026-11-02, 2.0.0-next.26, claude-haiku-5-5).
What are the top 10 stories on the Hacker News front page right now? Give title, points and domain for each.
The hook sends WebFetch to the sandbox, and the agent reads ten stories from the page. 35,087 B raw, 1,501 B reached the context, 95.7% saved (2026-11-02, 2.0.0-next.26, claude-haiku-5-5). The front page changes, so the raw size changes with each run.

See the saving

Run the stats skill right after a prompt. Each agent uses its own command; the skill calls ctx_stats and shows its report unchanged.

| Agent | Command | |---|---| | Claude Code | /ctx-stats | | Codex | $ctx-stats | | Copilot CLI | /ctx-stats | | Gemini CLI | Call ctx_stats and show me the report. | | Kiro | Call ctx_stats and show me the report. | | OMP | /skill:ctx-stats | | OpenCode | Call ctx_stats and show me the report. | | Pi | /skill:ctx-stats | | Qwen Code | Call ctx_stats and show me the report. | | VS Code (Copilot) | /ctx-stats | | ZCode | Call ctx_stats and show me the report. |

The first lines of a real report, after the JSON prompt above ran as one ctx_execute call:

context-mode stats
────────────────────────────────────────────────────────────────────────────────

This session · 1 call · <1m active 1015.5 KB became 3.7 KB: 1011.8 KB kept out (99.6%) Without context-mode |████████████████████████████████████████| 1015.5 KB With context-mode |█░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░| 3.7 KB about 259K tokens kept out, 1.3 times a 200K window

Captured 2026-11-03 with 2.0.0-next.35: release-out/server.mjs over MCP in a temp HOME.

Next, the same numbers for 20 real tools, in Use cases.

Use cases

Real tool output from public projects, run through Context Mode. Bench of 2026-11-01 on 2.0.0-next.23 (commit 16a4bcc5), median of 5 runs.

| What you do | Tool | Raw | Reaches the context | Saved | |---|---|---:|---:|---:| | Read a browser page | Chrome DevTools MCP take_snapshot, Code Mode | 136,514 B | 463 B | 99.7% | | List 40 issues | GitHub CLI gh issue list --json, Code Mode | 182,943 B | 850 B | 99.5% | | List 25 pull requests with checks | GitHub CLI gh pr list --json, Code Mode | 195,471 B | 776 B | 99.6% | | Look up library docs | Context7 query-docs, Code Mode | 6,917 B | 473 B | 93.2% | | Run 1,106 tests | Vitest vitest run --reporter=verbose, Code Mode | 62,909 B | 429 B | 99.3% | | Lint a source folder | Biome biome lint --reporter=json, Code Mode | 288,523 B | 577 B | 99.8% | | Install a workspace | pnpm pnpm install --frozen-lockfile, Code Mode | 14,988 B | 199 B | 98.7% | | Install packages | npm npm install --loglevel http, Code Mode | 37,761 B | 435 B | 98.8% | | Read container logs | Docker docker logs, Code Mode | 60,374 B | 587 B | 99.0% | | Plan 72 resources | Terraform terraform plan, Code Mode | 34,081 B | 166 B | 99.5% | | Read 300 commits with file stats | git git log --stat, Code Mode | 164,385 B | 268 B | 99.8% | | Read an 89 KB source file | Read, sent to ctx_execute by the hook | 91,362 B | 375 B | 99.6% | | Fetch a 265 KB docs page | WebFetch, sent to ctx_index and ctx_search | 271,731 B | 439 B | 99.8% | | Fetch a 214 KB API reply | curl in Bash, replaced after it runs | 219,175 B | 291 B | 99.9% | | Print a 187 KB git log in Bash | Bash, output replaced after it runs | 191,120 B | 204 B | 99.9% | | Print the same git log through a host tool | Host tool output over the cap, indexed whole | 191,120 B | 2,842 B | 98.5% | | Print a 214 KB GitHub API reply through a host tool | Host tool output over the cap, indexed whole | 219,175 B | 4,060 B | 98.1% | | Read a 45 KB log file | Read, sent to ctx_execute by the hook | 46,216 B | 371 B | 99.2% | | Read a 60 KB source file | Read, sent to ctx_execute by the hook | 61,576 B | 374 B | 99.4% | | Debug for a full session: 8 outputs, 3 searches | All hooks and tools | 281,261 B | 3,266 B | 98.8% |

Source: bench/results/2026-11-01-darwin-arm64.json, one row per line; SOURCE.md names where each input comes from. Click a task to open its case: the command, the input file with its sha256, and the run command, so you can run the same row on your machine.

The agent gets the part it asks for. The full output stays in the local index, and ctx_search reads it back. Rows with a command run in the sandbox; the agent then finds the rest with search. The Context7 row has 6,917 B of raw output, under the 10 KB line of the headline rule, so the headline leaves it out.

Next, how the bench counts these bytes, in Benchmarks.

Benchmarks

https://github.com/mksglu/context-mode/blob/HEAD/Bar chart: median output bytes saved per category for rows of 10 KB or more. Sandbox 99.5%, Batch 93.1%, Externalize 98.3%, Hook redirect 99.8%, Session total 98.8%. The table below adds Retrieval, 77.2%.

Rule for every headline number in this README: rows with 10 KB or more of raw output, median of 5 runs per row, measured with ctx_bytes against raw_bytes; a category is the median of its rows; 1 KB = 1,024 B. All 36 such rows, the six categories below: the plugin keeps a median of 99.4% of output bytes out of the context. Bench on 2.0.0-next.23 (commit 16a4bcc5 and the local edits that the file records), macOS arm64, 2026-11-01.

| Category | What runs | Rows | Median saved | |---|---|---:|---:| | a. Sandbox | ctx_execute on a file or command | 19 | 99.5% | | b. Retrieval | ctx_search over the local index | 3 | 77.2% | | c. Batch | ctx_batch: many commands, then search | 2 | 93.1% | | d. Externalize | Host tool output over the cap, indexed whole | 4 | 98.3% | | f. Hook redirect | A big Read, curl or WebFetch sent to the sandbox | 7 | 99.8% | | g. Session total | One full scripted session | 1 | 98.8% |

Search replies (category b) carry the matching text, so they save 77.2%. Category e (long sessions) is in Longer sessions. The full file lists every row, small ones too: 2026-11-01-darwin-arm64.md. Reproduce with cd bench && node run.mjs. It needs plain Node and runs offline; bench/README.md lists each scenario and its options. Method, data files and rerun steps: Benchmarks guide.

Longer sessions

https://github.com/mksglu/context-mode/blob/HEAD/A session grows, the context stays small. The PreToolUse hook sends a tool call to ctx_execute or ctx_index; the full output goes into context.db and a small reply returns. At compaction a snapshot keeps the state, and ctx_resume and ctx_search read it back.

Say you debug a slow test all afternoon. The agent reads files, runs the suite and fetches docs, and each result goes into the context window. When the window is full, the host compacts it, and from then on the agent sees a short summary plus your next message.

Context Mode keeps the full output of each large tool call in context.db on your machine and gives the agent a small reply. At compaction, a snapshot of at most 2,048 B keeps the session state. After the compaction, the agent calls ctx_resume to read that snapshot back and ctx_search to find any earlier output by keyword.

In the bench, a scripted session of 40 tool outputs and one compaction made a 442,893 B transcript, and the ctx_resume block that brought the agent back was 2,019 B (row e-long-session in the bench file; open the case). In the same bench, one large log of 666,796 B put 3,380 B into the context, and the full log stayed in the index for ctx_search (row d-synth-1m; [open the c

GitHub Stars & Activity

33,774Stars
2,312Forks
22Open issues
JavaScriptLanguage

GitHub Popularity

GitHub stars33,774
Forks2,312
Open issues22
Primary languageJavaScript
LicenseNOASSERTION
Stars gained today0
Created2026-02-23
Last pushed2026-11-10

Trending History

Trending statusnot on today's boards

Related GitHub Projects

1

affaan-m / ECC

JavaScript★ 304,932⑂ 0
→
2

DietrichGebert / ponytail

JavaScript★ 192,510⑂ 0
→
3

addyosmani / agent-skills

JavaScript★ 118,497⑂ 0
→
4

Leonxlnx / taste-skill

JavaScript★ 117,275⑂ 0
→
5

tt-a1i / archify

JavaScript★ 97,318⑂ 0
→
6

Ebony-Vinyl / dsh-our-free-model

JavaScript★ 78,057⑂ 0
→
7

Mintplex-Labs / anything-llm

JavaScript★ 68,356⑂ 0
→
8

gsd-build / get-shit-done

JavaScript★ 64,129⑂ 0
→

More Trending Repositories