Context Mode: what it is and how I'd set it up

By Shah Rukh, software developer · October 5, 2026 · 8 min read

If you’ve spent real time with an AI coding agent — Claude Code, Gemini CLI, Copilot, whatever — you know the quiet frustration. You’re deep in a task, the agent is finally being useful, then it runs one command that dumps a wall of log output into the conversation. A few of those and it starts forgetting what you asked twenty minutes ago. Context Mode is built for exactly that problem.

I wrote this after reading through the project’s repository, so everything below comes from its own docs rather than my imagination. Let’s start with what it actually is.

So what is it

Context Mode is an MCP plugin — MCP being the Model Context Protocol that modern coding agents use to talk to external tools. You install it as an npm package called context-mode, and it sits between your agent and the heavy stuff it does: fetching web pages, reading big log files, running shell commands. Instead of letting raw output flood into the chat, it runs that work in a sandbox and feeds only the small, useful result back to the model.

The project describes three things it does. First, context saving: it runs code in an isolated subprocess and returns only what you console.log(), so a 315 KB blob can come back as a few kilobytes — the repo claims up to 98% reduction. Second, session continuity: it records your file edits, git operations, tasks and decisions into a local SQLite database, so when the conversation gets compacted the agent picks up where it left off instead of asking you to repeat yourself. Third, a habit it calls “think in code” — the agent writes a script that counts or filters your data and prints the answer, rather than reading fifty files into the chat by hand.

Who’s it for? People who run long agent sessions on real codebases. If you ask your agent one quick question and close it, you won’t feel the pain this solves. If you babysit a multi-step task for an hour and watch it go senile halfway through, this is aimed squarely at you.

Before you start — the catch

Context Mode changes how your agent behaves. It intercepts and hard-blocks commands like curl and wget and inline HTTP calls, redirecting them to its own sandbox. That’s the whole point, but it means the tool is opinionated about your agent’s workflow. Also note the licence: it’s the Elastic License 2.0, which is source-available but not classic open source (more on that below). And it needs Node.js — the repo lists Node.js 22.5 or newer (Bun also works). Older setups won’t run it.

There’s no pricing page because the tool is free to install and use — the repo says no account is required and nothing is sent to a server. The README does carry a row of big company logos (“used across teams at…”) plus a Hacker News ranking and large user counts; treat those as the project’s own marketing, not independently verified facts.

What you need first

• A supported agent. The package says it works with Claude Code, Gemini CLI, VS Code Copilot, OpenCode and Codex CLI, among a longer list of clients.
• Node.js 22.5+ (or Bun). Check with node --version.
• No API keys of its own. It doesn’t ask you for keys — it piggybacks on tools you already have, so authenticated CLIs like gh, aws and docker work through your existing credentials.

Installing on a Mac

The cleanest path, if you use Claude Code, is the plugin marketplace. Inside a Claude Code session, run these:

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

Then restart Claude Code (or /reload-plugins). The repo says routing is automatic here — a SessionStart hook injects the rules at runtime, so nothing gets written into your project folder. Verify it worked:

/context-mode:ctx-doctor

Every check should show [x]. If Claude Code doesn’t recognise /plugin, update it first — on a Mac that’s usually brew upgrade claude-code.

For other agents (Gemini CLI, Copilot, OpenCode and friends), the shared first step is a global npm install, which is identical on Mac and Windows:

npm install -g context-mode

After that you add a small MCP-server entry to that agent’s config file — the repo has a copy-paste block for each one. On Gemini CLI, for instance, you add a context-mode server plus its hooks to ~/.gemini/settings.json and restart. I’d follow the project’s per-platform section exactly, because the config keys differ between agents.

Installing on Windows

Good news: the Claude Code marketplace commands above are identical on Windows — you type them inside the agent, so there’s no OS difference. The global install is the same too:

npm install -g context-mode

Context Mode uses a native SQLite module (better-sqlite3), and on Windows that’s historically where native modules go wrong. The repo says it handles this: if the compiled binding ends up missing after install, a postinstall script and a runtime hook automatically re-fetch and repair it — no manual npm rebuild needed. If you’d rather skip native compilation entirely, running your agent on Bun avoids it, because Context Mode uses Bun’s built-in SQLite instead.

Two Windows-specific gotchas worth knowing. If you install it into Cursor from a local folder, Cursor doesn’t follow Windows symlinks, so the repo tells you to copy the files with robocopy instead. And the OpenClaw install path needs a bash shell — Git Bash or WSL — so plain cmd.exe won’t do.

Your first real run

Once it’s in, you don’t do anything special — you use your agent normally and let the routing do its job. To feel the difference, ask it to fetch a web page, pull out the data you care about and summarise it, then run /context-mode:ctx-stats (or just type ctx stats on agents without slash commands). The readout shows how much context you saved. The first time you watch a multi-megabyte fetch come back as under a kilobyte, the tool sort of explains itself.

The settings and features actually worth knowing

You get 11 MCP tools. The ones you’ll feel day to day are the sandbox tools — ctx_execute (run code, return only stdout), ctx_execute_file (process a file in the sandbox), and ctx_fetch_and_index (fetch a URL straight into a searchable index). Then there’s a small knowledge base: ctx_index and ctx_search store and query content using SQLite’s FTS5 full-text search, so the agent can look things up later instead of re-reading them.

The rest are housekeeping: ctx stats for savings, ctx doctor for diagnostics, ctx upgrade to pull the latest version, and ctx purge to wipe the local knowledge base. One behaviour to note — the repo says that if you don’t resume a session (with --continue or --resume), the previous session’s tracked data is deleted. A fresh session means a clean slate, by design.

Real precautions for this tool

A few things I’d genuinely pay attention to:

• Approving a sandbox run means approving arbitrary code. The repo is blunt about this: ctx_execute runs whatever code it’s given and still inherits your process’s filesystem access. It’s not a full OS jail, so keep host-level sandboxing on and don’t treat the approval prompt as a safety net.
• Where your data lives. Indexed content and session databases are stored locally, under your home directory (for example ~/.context-mode/content/). The project says nothing leaves your machine — no telemetry, no cloud sync — and content older than 14 days is cleaned up on startup.
• Secrets. Context Mode redacts common credential fields (tokens, passwords, API keys, cookies) before writing tool arguments to its session database. Helpful, but I still wouldn’t paste live secrets into a prompt.
• Permissions carry over. Deny rules like Read(**/.env*) or Bash(sudo *) in your Claude settings apply inside the sandbox too, and ctx_execute_file is confined to your project root by default — paths that escape it are refused.

Updating and removing it

Updating is documented: run ctx upgrade (or npm install -g context-mode@latest for the global binary). Removing it cleanly is less clearly spelled out across every platform — for a global install you’d remove the npm package and strip the context-mode entry back out of your agent’s config. The repo doesn’t give a single universal uninstall recipe, so I’m not going to invent one; check your agent’s plugin docs.

Things that went sideways / watch out for

From the notes in the repo, a few predictable snags. On some agents, having both the old MCP entry and the new plugin entry registers zero tools — the fix is to run ctx upgrade to drop the legacy entry. On Cursor, session restore after compaction isn’t available yet because Cursor rejects the SessionStart hook. And a few clients (Antigravity IDE, Zed) have no hook support at all, so they fall back to a manually-copied instructions file with weaker enforcement. If routing feels like it isn’t kicking in, ctx doctor is the first place I’d look.

A note on the licence

Context Mode is under the Elastic License 2.0 (ELv2). In plain terms: you can use it, copy it, modify it and distribute it for free. The two real limits are that you may not offer it to others as a hosted or managed service that exposes its features, and you may not remove or obscure the licensing and copyright notices. It’s “source-available,” which is not the same as an OSI-approved open-source licence like MIT — the project chose ELv2 to stop someone repackaging it as a competing closed SaaS. For a dev using it on their own machine, none of that gets in the way.

If you work with the kinds of data this tool shuffles around, a few small ToolsCloset utilities pair nicely: Markdown to HTML for docs, CSV to JSON for reshaping exported data, and Base64 Encoder/Decoder for the usual encoding chores.

I wrote this from the project’s repo as it was on October 5, 2026 (version 1.0.169), so commands, flags and limits may have changed since — always check the current README before you install. ToolsCloset isn’t connected to or affiliated with Context Mode or its author; this is an independent guide.

More AI tips

Free Claude Code Setup Guide

Run the Claude Code app with free AI models on Windows or Mac. Full steps, plus the precautions most guides skip.

EmailOSINT Review and Guide

See which accounts, data breaches and stolen-password logs are tied to your email, and what to do about each result.

FastMCP for beginners

Turn a plain Python function into a tool an AI assistant can call. Setup on Windows and Mac, step by step.

TradingView MCP Guide

Self-host the free TradingView MCP server on Windows or Mac, or pay for hosting — and mind the data-not-advice caveat.

AWS MCP servers, explained

AWS publishes a big set of open-source MCP servers. Here's what they do and how to wire one into your AI coding assistant.

MCP servers in TypeScript

A beginner-friendly look at mcp-use for building and connecting MCP servers, clients and agents in TypeScript.

OpenHands Agent Canvas Guide

Set up the OpenHands control centre for AI coding agents on Windows or Mac, with the safety steps to take first.

Dify Self-Hosting Guide

Run the Dify AI app builder on your own computer with Docker Compose, and know the costs and licence limits first.

LibreChat Docker Setup Guide

Run your own ChatGPT-style chat app on your computer with Docker. Full steps, real costs and safety checks.

🤖

Unity MCP Setup Guide

Let Claude Code, Cursor or Copilot work inside the Unity Editor. Full install steps, plus the precautions to take first.

sprite-gen Setup Guide

Turn one character drawing into a transparent game sprite sheet. Setup steps, real costs and precautions.

Logo Design Skill Setup Guide

Add a free logo-design skill to Claude or another AI agent on Windows or Mac, with the precautions to take first.

🤖

Openvid Screen Demo Guide

Record your screen and turn it into a polished demo in the browser, or run Openvid yourself on Windows or Mac.

ReelMimic Setup Guide

Set up ReelMimic to make an original 2D animation in the style of a reference video, with the copyright checks to do first.

Related tools