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 — 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 all four hooks. 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",
        "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" }
        ]
      }
    ]
  }
}

Hooks

Hook	What it does
`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.
`SessionStart`	Loads prior session memory so context survives a restart.

Compaction guidance is advisory on Gemini CLI. The PreCompress hook suggests what context-mode would keep, but Gemini CLI controls the final compression.

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

See /docs/configuration for the full list of environment variables, storage paths, and permission rules.

Verify

Confirm the install with the doctor. It checks language runtimes, the FTS5 knowledge base, and hook registration, then reports anything that needs attention.

Verify the setup

context-mode doctor

A clean run 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