ix-gemini-plugin

A Gemini CLI extension that turns Gemini into a graph-reasoning engineering agent using Ix Memory as its structured memory backend.

Gemini + Ix = reasoning engine + persistent code knowledge graph. Skills are cognitive abstractions, not CLI wrappers.

Requirements

• Ix Memory CLI >= 0.11.0 installed and running (ix status returns ok)
• python3 in PATH for hook scripts
• ripgrep (rg) is recommended

Ix Pro is optional. If present, the BeforeAgent hook injects the Ix session briefing once per 10 minutes.

Skills

High-level cognitive skills:

Skill	What it does	Key rule
ix-help <task or question>	Route to the right Ix skill or direct ix command	Route only; do not execute
ix-understand [target]	Build a mental model of a system or the whole repo	Graph only; no code reads
ix-investigate <symbol>	Deep dive: what it is, how it connects, execution path	Graph first; one symbol read max
ix-impact <target>	Change risk: blast radius, affected systems, test targets	Depth scales with risk
ix-plan <targets...>	Risk-ordered implementation plan for a set of changes	Parallel impact; finds shared dependents
ix-debug <symptom>	Root cause analysis from symptom to candidates	Minimal source reads at suspects only
ix-architecture [scope]	Design health: coupling, smells, hotspots	Graph only; never reads source
ix-docs <target> [--full]	Generate narrative-first documentation with selective reference	Default is onboarding-focused

MCP Server

The extension registers one MCP server, ix-memory, which is the Ix CLI's own: ix mcp --tools=all, started in the workspace directory (cwd: ${workspacePath}) so it answers for the project you opened Gemini in. Nothing is built or bundled; tool names are the CLI's (ix_context, ix_search, ix_impact, ix_neighbors, ix_read, ...). --tools needs Ix >= 0.11.0.

ix mcp install --host gemini registers a server with the same name, ix-memory, in ~/.gemini/settings.json. You do not need it with this extension. If both exist, Gemini merges them into one server and the settings entry's command/args win, so remove it (gemini mcp remove --scope user ix-memory) or keep its args at mcp --tools=all.

Agent Playbooks

Reusable playbook docs in agents/:

Playbook	Purpose
ix-explorer	General-purpose graph exploration
ix-system-explorer	Full architectural model of a codebase or region
ix-bug-investigator	Root cause analysis from symptom to candidates
ix-safe-refactor-planner	Blast radius plus safe change sequencing
ix-architecture-auditor	Structural health report with ranked improvements

Automatic Hooks

Trigger	Gemini hook	Effect
Session starts	SessionStart	Injects Ix operating guidance and graph-first rules into the model's context
Before agent plans	BeforeAgent	Injects ix briefing once per 10 min if Ix Pro is available
After shell search/read	AfterTool (run_shell_command)	Appends ix text + ix locate (for grep/rg) or ix overview + ix impact (for cat/head/...) context to the tool result the model reads
After a file edit	AfterTool (run_shell_command, write_file, replace)	After a file-modifying shell command or a native edit, refreshes an already-mapped git repo in the background (ix map <root> --silent, at most once per 5 min per repo)
Session ends	SessionEnd	Same guarded background refresh of the project's git root

Install

Quick install

gemini extensions install /path/to/ix-gemini-plugin

Or from GitHub:

gemini extensions install https://github.com/ix-infrastructure/ix-gemini-plugin

Manual install

git clone git@github.com:ix-infrastructure/ix-gemini-plugin.git
cd ix-gemini-plugin
./install.sh

The installer copies the extension to ~/.gemini/extensions/ix-memory/.

On Windows PowerShell:

.\install.ps1

Repo-local install

./install.sh --repo /path/to/project

This copies the extension to /path/to/project/.gemini/extensions/ix-memory/.

PowerShell equivalent:

.\install.ps1 -Repo C:\path\to\project

Local Validation

Run the hook and manifest tests with:

./test-local.sh

The tests run every hook against a strict fake ix, never a real backend, and skip live Gemini CLI validation when gemini is not installed.

Repo Guidance

The repo-level operating guide lives in GEMINI.md. It carries the graph-first reasoning model, skill reference, and token-budget rules.