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.
node --versionInstall the package
This installs the MCP server, the hook dispatcher, and the context-mode command
line.
npm install -g context-modeConfigure 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-modewith no arguments — this matches the shippedconfigs/jetbrains-copilot/mcp.json - No global install? Use
npx -y context-modeas the command instead - Then: confirm the server connects
JetBrains stores this registration in the Settings UI, not in a project file.
{
"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.
{
"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.
cp node_modules/context-mode/configs/jetbrains-copilot/copilot-instructions.md .github/copilot-instructions.mdTool 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_executef1e_ctx_searchf1e_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).
| Purpose | Signal |
|---|---|
| Workspace / project directory | IDEA_INITIAL_DIRECTORY |
| Host-detection fallback | presence of a ~/.config/JetBrains/ directory |
| Explicit override | CONTEXT_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 variable | Session ID derived |
|---|---|
JETBRAINS_CLIENT_ID | jetbrains-<id> |
IDEA_HOME | idea-<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
context-mode doctorThe 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.