Pi
Install context-mode in the Pi Coding Agent as an extension with full in-process hooks and an auto-bridged MCP server, for high session continuity.
Pi (the Pi Coding Agent) runs context-mode as an extension installed at
~/.pi/extensions/context-mode/. Pi has no JSON-stdio hooks and no native MCP
support, so the extension does both jobs:
- Hooks — wires in-process hooks through Pi's JavaScript runtime API
(
pi.on(...)). - MCP bridge — bootstraps a bridge that registers each
ctx_*tool with Pi viapi.registerTool().
The result is real hook coverage — context-mode intercepts tool calls for routing enforcement and captures lifecycle events for session continuity, rather than relying on advisory instructions alone.
The adapter-layer capabilities report the mcp-only paradigm for the
JSON-stdio harness, but the integration actually lives in the extension. The
extension registers session_start, before_agent_start, tool_call,
tool_result, session_before_compact, and turn_end handlers (the
capture and routing subset) — so the MCP bridge is wired, routing is enforced,
prior sessions are restored, and real per-turn tokens are captured. See
Tool selection for how routing decisions are
made.
Prerequisites
Node.js 22.5 or newer (or Bun), with the Pi Coding Agent already installed.
Install
Install context-mode globally
Install the package so the context-mode binary is on your PATH. The extension
and its MCP bridge both run this binary.
npm install -g context-modeInstall the Pi extension
Run the upgrade command. It syncs the extension into
~/.pi/extensions/context-mode/, which is where Pi discovers it by directory
presence.
context-mode upgradeThere is no pi install npm: / packages[] mechanism and no
~/.pi/agent/settings.json to edit — Pi's config root is ~/.pi/.
Let the extension bridge MCP automatically
Pi has no native MCP support, so the extension auto-bridges the ctx_* tools
into Pi via pi.registerTool() on before_agent_start. No mcp.json edit is
needed or honored — do not create ~/.pi/agent/mcp.json.
Restart Pi
Restart Pi so it loads the new extension and registers the bridged tools.
Configure
The extension reads routing instructions from AGENTS.md and rarely needs
hand-editing. Its paths:
| Path | Holds |
|---|---|
~/.pi/ | Pi's config root |
~/.pi/extensions/context-mode/ | The extension itself |
~/.pi/context-mode/sessions/ | Session state, kept separate from other harnesses so Pi never shares session data with a different host |
The extension registers these Pi runtime hooks:
| Hook | Stands in for | Role |
|---|---|---|
session_start | SessionStart | Initializes the per-session record |
before_agent_start | — | Lazily spawns and awaits the MCP bridge before each agent turn, and injects resume and active-memory context |
tool_call | PreToolUse | Routing enforcement (see HTTP-blocking rules below) |
tool_result | PostToolUse | Captures tool events |
session_before_compact | PreCompact | Builds a resume snapshot before compaction |
turn_end | — | Captures per-turn token and cost telemetry |
The tool_call hook applies these HTTP-blocking rules:
- Inline HTTP clients (
fetch,requests,http,urllib,Invoke-WebRequest) — blocked unconditionally by returning{ block: true }. curl/wget— blocked only when not in a silent file-output form.curl -s -o /tmp/x.json URLorwget -q -O /tmp/x.json URLis allowed as an escape hatch when the MCP bridge is unreachable.
Pi is detected through any of these signals:
| Signal | Type |
|---|---|
PI_CONFIG_DIR, PI_SESSION_FILE, PI_COMPILED, or PI_CODING_AGENT marker | Environment |
Presence of the ~/.pi/ directory | Filesystem |
CONTEXT_MODE_PLATFORM=pi override | Explicit |
If your project also has a CLAUDE.md, Pi reads both it and AGENTS.md and
duplicates the routing instructions in context. Keep only one to avoid the
duplication.
See /docs/configuration for the full list of environment variables, storage paths, and permission rules.
Verify your savings
Confirm context-mode is actually saving you tokens, not just installed.
In a Pi session, type ctx stats in chat. After a few tool calls it reports the
tokens saved and the savings ratio for the session — backed by the per-session DB
at ~/.pi/context-mode/sessions/, and accurate because the turn_end hook
captures real per-turn tokens.
For a structural check, run the doctor. It detects Pi, inspects language
runtimes, the FTS5 knowledge base, and validates that the extension package is
present at ~/.pi/extensions/context-mode/. The structural doctor checks the
extension's registration, not the live MCP bridge:
context-mode doctorInside a Pi session you can also run the registered ctx-doctor slash command —
a quick in-session diagnostic distinct from the CLI context-mode doctor. It
reports:
- The per-session DB path
- Session id
- Event and compaction counts
- Resume-snapshot state
If the bridge fails to spawn, the ctx_* tools won't appear and Pi's log file
records [context-mode] WARNING: failed to bridge MCP tools to Pi — the
warning is routed to Pi's file logger, not stderr or the TUI. The fix is
context-mode upgrade.
A clean run means the extension is registered and context-mode is ready to route your next data-heavy command.
Related
OpenClaw
Install context-mode in OpenClaw as a native gateway plugin via the dedicated installer, with an MCP sidecar and registration as the context engine for compaction-aware session resume.
Antigravity
Install context-mode in the Antigravity IDE as an MCP-only host: register the context-mode MCP server and copy a GEMINI.md routing file that steers data-heavy output into the sandbox.