Pi · context-mode

Install context-mode in the Pi Coding Agent as a package extension with full hook support and an MCP server, providing high session continuity.

Pi (the Pi Coding Agent) runs context-mode as a package extension backed by an MCP server. The extension wires directly into Pi's JavaScript runtime API (pi.on(...)), so context-mode gets real hook coverage — it intercepts tool calls for routing enforcement and captures lifecycle events for session continuity, rather than relying on advisory instructions alone.

Pi exposes hooks through its extension runtime, not the JSON stdin/stdout wire protocol. context-mode's adapter reports the mcp-only paradigm for the JSON-stdio harness, but the Pi extension registers tool_call, tool_result, session_start, and session_before_compact handlers — so routing is enforced and prior sessions are restored. 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 MCP config below points Pi at this binary.

npm install -g context-mode

Add the package to Pi

Install context-mode into Pi as a package extension. This registers the extension that wires the pi.on(...) hook handlers.

pi install npm:context-mode

Alternatively, add it to ~/.pi/agent/settings.json by hand (or .pi/settings.json for a project-level install):

~/.pi/agent/settings.json

{
  "packages": ["npm:context-mode"]
}

Register the MCP server

Add context-mode to Pi's MCP config at ~/.pi/agent/mcp.json (or .pi/mcp.json for a project-level install). The bare context-mode command starts the MCP server by default — there is no mcp subcommand.

~/.pi/agent/mcp.json

{
  "mcpServers": {
    "context-mode": {
      "command": "context-mode"
    }
  }
}

If you did not install globally, set "command": "npx" with "args": ["-y", "context-mode"] instead.

Restart Pi

Restart Pi so it loads the new package and MCP server.

Configure

The extension reads routing instructions from AGENTS.md and stores session state under ~/.pi/context-mode/sessions/, kept separate from other harnesses so Pi never shares session data with a different host. Settings live in ~/.pi/agent/settings.json and the MCP server in ~/.pi/agent/mcp.json. You rarely need to edit any of this by hand.

The extension registers these Pi runtime hooks:

session_start — initializes the per-session record (SessionStart equivalent)
tool_call — PreToolUse routing enforcement (blocks curl/wget/inline fetch)
tool_result — PostToolUse event capture
session_before_compact — builds a resume snapshot (PreCompact equivalent)

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

In a Pi session, type ctx stats — the context-mode tools should appear and respond. For a deeper check, run the doctor, which inspects language runtimes, the FTS5 knowledge base, and the Pi extension registration:

Verify the setup

context-mode doctor

If you took the npx path instead of a global install, run npx -y context-mode doctor. A clean run means the extension is registered and context-mode is ready to route your next data-heavy command.

OMP (Oh My Pi)

A Pi-compatible harness with its own isolated storage under ~/.omp/.

Tool selection

How context-mode decides what to route into the sandbox.

Pi

OMP (Oh My Pi)

Tool selection

On this page