context-mode
Installation

JetBrains Copilot

Install context-mode in the JetBrains Copilot agent, a package host that integrates through JSON hooks and an MCP server.

The JetBrains Copilot agent is GitHub Copilot's agentic mode inside JetBrains IDEs. It runs context-mode with the same JSON lifecycle hooks and host-side tool naming as the VS Code Copilot agent. The hooks route data-heavy tool output into the sandbox and keep about 98% of raw payload bytes out of your window — the model writes a program that processes the data and prints only the answer.

  • Hooks wired: PreToolUse, PostToolUse, PreCompact, SessionStart
  • Dispatch command: context-mode hook jetbrains-copilot <event> with a lowercase event name
  • Session continuity: the four hooks below cover capture, snapshot, and restore

context-mode runs 100% locally with zero telemetry. Indexing and execution never leave your machine.

Install

The Copilot agent has no plugin marketplace, so install the package globally first, then configure the server and hooks.

Check the prerequisites

You need Node 22.5+ or Bun on your PATH, and a JetBrains IDE with the GitHub Copilot plugin v1.5.57+ (required for MCP server support). The hook dispatcher and sandbox run on this runtime.

Check the runtime
node --version

Install the package

This installs the MCP server, the hook dispatcher, and the context-mode command line.

Global install
npm install -g context-mode

Configure the MCP server

Configure the context-mode MCP server from the IDE settings.

  • Open: Settings, then Tools, then GitHub Copilot, then MCP, then Configure
  • Name: context-mode
  • Command: context-mode with no arguments — this matches the shipped configs/jetbrains-copilot/mcp.json
  • No global install? Use npx -y context-mode as the command instead
  • Then: confirm the server connects

JetBrains stores this registration in the Settings UI, not in a project file.

MCP server entry
{
  "servers": {
    "context-mode": {
      "command": "context-mode"
    }
  }
}

Add the hooks

Add the context-mode hooks file at .github/hooks/context-mode.json. The four hooks point at the context-mode dispatcher, which decides whether a tool call should run in the sandbox. The dispatch command is context-mode hook jetbrains-copilot <event> with a lowercase event name.

The adapter also declares Stop, SubagentStart, and SubagentStop for parity with the VS Code Copilot agent, but context-mode ships no scripts for them. Only the four events below are wired, so those are the ones to register.

.github/hooks/context-mode.json
{
  "hooks": {
    "PreToolUse": [
      { "type": "command", "command": "context-mode hook jetbrains-copilot pretooluse" }
    ],
    "PostToolUse": [
      { "type": "command", "command": "context-mode hook jetbrains-copilot posttooluse" }
    ],
    "PreCompact": [
      { "type": "command", "command": "context-mode hook jetbrains-copilot precompact" }
    ],
    "SessionStart": [
      { "type": "command", "command": "context-mode hook jetbrains-copilot sessionstart" }
    ]
  }
}

Copy the routing instructions (optional)

Routing is automatic through the SessionStart hook. For full model awareness, copy the shipped instructions into your repository so Copilot reads them on every turn.

Optional routing file
cp node_modules/context-mode/configs/jetbrains-copilot/copilot-instructions.md .github/copilot-instructions.md

Tool names

context-mode tools are surfaced under the IDE's own naming scheme. JetBrains Copilot prefixes MCP tools with f1e_ — the same prefix the VS Code Copilot agent uses — so the ctx_* tools appear as:

  • f1e_ctx_execute
  • f1e_ctx_search
  • f1e_ctx_batch_execute
  • …and so on

They are the same tools documented elsewhere; only the host-side display name differs.

GitHub Copilot plugin v1.5.57 or newer is required for MCP server support. Update the plugin from the JetBrains plugins marketplace before configuring context-mode.

Detection

context-mode self-identifies as JetBrains Copilot from the IDE environment. The session ID arrives as sessionId (camelCase).

PurposeSignal
Workspace / project directoryIDEA_INITIAL_DIRECTORY
Host-detection fallbackpresence of a ~/.config/JetBrains/ directory
Explicit overrideCONTEXT_MODE_PLATFORM=jetbrains-copilot

IDEA_HOME and JETBRAINS_CLIENT_ID are no longer used for host detection, but they still contribute to session-ID derivation when sessionId is absent:

Environment variableSession ID derived
JETBRAINS_CLIENT_IDjetbrains-<id>
IDEA_HOMEidea-<pid>

Verify your savings

Confirm context-mode is actually saving you tokens, not just that the tools respond.

Check the session savings

In Copilot Chat, type ctx stats. It reports the context-window tokens saved this session and the savings ratio, with a per-tool breakdown so you can see routing at work.

Confirm hooks and MCP are registered

Run the doctor. It checks:

  • Language runtimes
  • The FTS5 knowledge base
  • The hooks in .github/hooks/context-mode.json
Verify the setup
context-mode doctor

The MCP-registration check intentionally reports WARN on JetBrains: MCP servers are registered in the IDE Settings UI, which is not CLI-inspectable. Confirm the context-mode server manually under Settings, then Tools, then GitHub Copilot, then MCP.

A clean doctor run plus a non-zero ctx stats savings ratio means context-mode is routing your data-heavy commands and keeping raw bytes out of your window.

On this page