ix-claude-plugin

A Claude Code plugin that turns Claude into a graph-reasoning engineering agent using Ix Memory as its structured memory backend.

Claude + Ix = reasoning engine + persistent code knowledge graph. Skills are cognitive abstractions (not CLI wrappers) that minimize token usage and maximize accuracy.

Installation

/plugin marketplace add ix-infrastructure/ix-claude-plugin
/plugin install ix-memory

Restart Claude Code after installing.

After install, Claude is taught to prefer Ix for structural questions, hooks automatically front-run common search/edit paths with Ix context, and Claude appends a short final Ix section when hooks materially helped on that turn.

Requirements

• Ix Memory installed and running (ix status returns ok)
• jq in PATH
• ripgrep (rg) in PATH

# Ubuntu/Debian
sudo apt install jq ripgrep

# macOS
brew install jq ripgrep

Ix Pro is optional. All skills and hooks work with basic Ix. Pro adds session briefing injection (goals, bugs, decisions) via the ix-briefing.sh hook.

Skills

High-level cognitive skills — each one infers intent, orchestrates multiple graph queries, and synthesizes output. None are CLI aliases.

Skill	What it does	Key rule
/ix-understand [target]	Build a mental model of a system or the whole repo	Graph only — no source 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 level
/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	Targeted reads at suspects only
/ix-architecture [scope]	Design health: coupling, smells, hotspots	Graph only — never reads source
`/ix-docs [--full] [--style narrative	reference	hybrid] [--split] [--single-doc] [--out ]`

All skills fall back gracefully when ix is unavailable.

Skills are slash commands you type. They are hidden from the model (disable-model-invocation: true), so Claude does not start one by itself, and their descriptions are not sent with every model call.

Agent

One agent, ix-explorer: graph-first exploration for open-ended questions about unfamiliar code. Its one-line description is the only part of the plugin's skills and agents that Claude Code lists in every model call.

Skills that delegate deeper work launch ix-explorer with a role brief that sits beside the skill:

Skill	Role brief	Purpose
/ix-understand, /ix-docs	skills/ix-understand/system-explorer-brief.md	Full architectural model of a codebase or region
/ix-debug	skills/ix-debug/bug-investigator-brief.md	Investigation from symptom to root cause candidates
/ix-plan	skills/ix-plan/refactor-planner-brief.md	Blast radius + safe change sequencing for refactors
/ix-architecture	skills/ix-architecture/architecture-auditor-brief.md	Full structural health report with ranked improvements

Automatic hooks

Trigger	Hook	Default	Effect
User sends any prompt	UserPromptSubmit → ix-briefing.sh	on	Injects session briefing (goals, bugs, decisions) once per 10 min — requires Ix Pro. On a session's first task-sized prompt, also the files Ix trusts as starting points for it (ix context --from-issue - --lean; IX_ISSUE_START=off to disable). Can also ask Claude to append a short final Ix section (IX_ANNOTATE_CHANNEL)
Claude runs Grep or Glob	PreToolUse → ix-intercept.sh	off: IX_GREP_INTERCEPT=on (or IX_BLOCK_ON_HIGH_CONFIDENCE=1)	Grep naming one definition: where it is defined and its callers at their call sites (ix locate + ix callers), else silent. Glob with a path: ix inventory. When on, costs ix locate + ix text before every Grep and ix inventory before most Globs with a path; it rarely names something the search does not find itself
Claude runs Bash with grep/rg	PreToolUse → ix-bash.sh	off: IX_GREP_INTERCEPT=on	Extracts the pattern; if it names one definition, adds where it is defined and its callers, else silent. When on, costs one ix locate before every shell grep
Claude edits a file	PreToolUse → ix-pre-edit.sh	off: IX_PRE_EDIT_GATE=on	Runs ix impact before the edit and warns when the file has many dependents (a count and a risk level). When on, costs one ix impact before every edit
Claude edits a file	PostToolUse → ix-ingest.sh (async)	on	Requests the guarded root map (below); never maps the single file
Claude edits, by tool or through Bash	PostToolUse → ix-dependents.sh	off: IX_EDIT_DEPENDENTS=on	ix hook claude-post-edit (Ix CLI 0.12.1+): from the working tree's diff, the callers, importers and tests of each symbol the edit changed, once per session. When on, costs one ix hook after every edit and after every Bash command that may write; a Bash command that can only read (cat, ls, git diff, ...) skips it, except right after a report (IX_BASH_EDIT_CLASSIFIER=off runs it after every Bash command)
Claude finishes responding	Stop → ix-annotate.sh	on	Emits a factual summary of how ix helped on that turn on non-modelSuffix channels
Claude finishes responding	Stop → ix-map.sh (async)	on	Guarded ix map <root> --silent: git root of the session's cwd (not $HOME), already-mapped projects only, debounced per root, detached

The hooks that are off by default block the tool call while they run, and what they say rarely changes what Claude does next. Off, each exits on its first lines (no ix call, no jq, nothing printed). To turn one back on, set its switch in the environment Claude Code starts in, e.g. export IX_EDIT_DEPENDENTS=on.

hooks/ix-read.sh remains in the repo as a disabled placeholder, but it is not registered in hooks/hooks.json and does not run at runtime.

All hooks bail silently if ix is not in PATH or the backend is unreachable.

Debugging ix Hook Calls

If you want to see exactly which ix CLI commands Claude-triggered hooks run, start Claude Code with IX_DEBUG_LOG set in its environment:

export IX_DEBUG_LOG=/tmp/ix-hooks.log
tail -f /tmp/ix-hooks.log

The hooks will append lines like:

[2026-04-19T12:34:56-0700] [ix-intercept] CMD ix text AuthService --limit 15 --format json --path src/
[2026-04-19T12:34:56-0700] [ix-intercept] CMD ix locate AuthService --format json

CMD ... lines are the exact shell-escaped ix invocations. INJECT ... lines show the exact context a hook injected back into Claude.

Every hook run also ends with exactly one EXIT line, on every path (including the runs where the hook decided to say nothing): wall time in milliseconds from the hook's first line to its exit, its exit code, and the payload's tool_name (- when there is none):

[2026-10-15T18:54:03] [ix-intercept] EXIT ms=37 rc=0 tool=Grep

To see where a recorded session's hook time went, sum them by hook:

awk '/ EXIT ms=/ { sub(/^ms=/, "", $4); n[$2]++; t[$2] += $4 }
     END { for (h in t) printf "%-16s %5d runs %8d ms\n", h, n[h], t[h] }' /tmp/ix-hooks.log

With IX_DEBUG_LOG unset the hooks skip all of this: no timer, no trap, no file.

Uninstall

/plugin uninstall ix-memory