Gemini CLI

Install context-mode in Gemini CLI, the package host that integrates through JSON lifecycle hooks.

Gemini CLI is Google's terminal coding agent. It integrates context-mode through JSON lifecycle hooks — BeforeAgent, BeforeTool, AfterTool, an advisory PreCompress hook, and SessionStart — that route data-heavy tool output into the sandbox and keep about 98% of raw payload bytes out of your window. Instead of reading raw bytes, the model writes a program that processes the data and prints only the answer.

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

Install

Gemini CLI has no plugin marketplace, so install the package globally first, then let the host pick up the MCP server and hooks.

Check the prerequisites

You need Node 22.5+ or Bun on your PATH. 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

Wire up the server and hooks

Add the following to ~/.gemini/settings.json (or .gemini/settings.json in a project). This single file registers the MCP server and the four hooks below. The MCP entry uses the global context-mode binary; each hook points at the same dispatcher with the command context-mode hook gemini-cli <event> and a lowercase event name.

~/.gemini/settings.json

{
  "mcpServers": {
    "context-mode": {
      "command": "context-mode"
    }
  },
  "hooks": {
    "BeforeTool": [
      {
        "matcher": "run_shell_command|read_file|read_many_files|grep_search|search_file_content|web_fetch|activate_skill|mcp__plugin_context-mode|mcp__context-mode|mcp__(?!.*context-mode)",
        "hooks": [
          { "type": "command", "command": "context-mode hook gemini-cli beforetool" }
        ]
      }
    ],
    "AfterTool": [
      {
        "matcher": "",
        "hooks": [
          { "type": "command", "command": "context-mode hook gemini-cli aftertool" }
        ]
      }
    ],
    "PreCompress": [
      {
        "matcher": "",
        "hooks": [
          { "type": "command", "command": "context-mode hook gemini-cli precompress" }
        ]
      }
    ],
    "SessionStart": [
      {
        "matcher": "",
        "hooks": [
          { "type": "command", "command": "context-mode hook gemini-cli sessionstart" }
        ]
      }
    ]
  }
}

The BeforeTool matcher targets only the tools that produce large output (run_shell_command, read_file, read_many_files, grep_search, search_file_content, web_fetch, activate_skill), context-mode's own tools, and an external-MCP catch-all (mcp__(?!.*context-mode)) so any other server's large payloads are intercepted too. This avoids hook overhead on lightweight tools while catching everything that could flood your window.

Wire BeforeAgent (recommended)

Run context-mode upgrade to additionally wire BeforeAgent, the UserPromptSubmit-equivalent that fires on prompt submit and powers session-continuity capture. Restart Gemini CLI afterward.

Add BeforeAgent

context-mode upgrade

Run the manual JSON in Step 3 first, then context-mode upgrade. On Gemini CLI, upgrade only wires BeforeAgent, BeforeTool, and SessionStart — it does not wire AfterTool or PreCompress. Those two come only from the Step 3 JSON, so upgrade alone is not a complete setup.

Hooks

Hook	What it does
`BeforeAgent`	Fires when you submit a prompt (the UserPromptSubmit equivalent). Captures user prompts and decisions for session continuity. Wired by `context-mode upgrade`.
`BeforeTool`	Inspects and reroutes data-heavy tool calls into the sandbox before they run.
`AfterTool`	Indexes tool output into the FTS5 knowledge base for later search.
`PreCompress`	Advises the model on what to preserve before compaction (advisory only, async, cannot block).
`SessionStart`	Loads prior session memory so context survives a restart.

The CLI dispatcher routes beforeagent, beforetool, aftertool, precompress, and sessionstart.

User prompts and decisions are captured on Gemini CLI via the BeforeAgent hook. Blocking uses decision: "deny" (not permissionDecision), and arg rewrites land in hookSpecificOutput.tool_input (merged with the original).

Compaction guidance is advisory on Gemini CLI. The PreCompress hook suggests what context-mode would keep, but Gemini CLI controls the final compression. The shipped AfterModel per-turn token/cost hook is emitted but not yet routed through the CLI dispatcher (#882), so don't hand-add aftermodel — it would no-op.

Configure

context-mode reads the project root from GEMINI_PROJECT_DIR. If that variable is unset, it falls back to the CLAUDE_PROJECT_DIR alias, so a shared setup that already exports the alias keeps working without changes.

Set the project directory

export GEMINI_PROJECT_DIR=/home/you/project

Captured sessions are stored under ~/.gemini/context-mode/sessions/.

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 that the tools respond.

Check the savings in chat

Type ctx stats in Gemini CLI. It reports the context-window tokens saved this session — the savings ratio plus a per-tool token breakdown — so you can watch routing pay off after a few data-heavy operations.

Confirm hooks and MCP are registered

Run the doctor. It validates the BeforeTool/SessionStart hook config, probes all six hook scripts on disk under hooks/gemini-cli/, checks the FTS5 knowledge base, and confirms that context-mode is registered in ~/.gemini/settings.json. A hook failure shows as a fail row with context-mode upgrade as the fix.

Verify the setup

context-mode doctor

A warn on plugin registration ("context-mode not found in extensions — might be using standalone MCP mode") is expected on Gemini CLI. There is no plugin marketplace, so the MCP server is registered standalone in settings.json rather than as an extension. Treat that row as benign, not a failure.

A clean doctor run plus a climbing savings ratio means context-mode is ready to route your next data-heavy command.

Configuration

Environment variables, storage, and permission rules.

CLI reference

Every context-mode command and what it does.

Configuration

CLI reference

On this page