Ix — Persistent Codebase Map

Ix parses a repository with tree-sitter (27 languages) into a graph of symbols, calls and imports, kept in a local backend (ArangoDB via Docker) and persisted between sessions. Query it for structural answers — what a symbol is, what calls it, how a flow moves, what a change breaks, which files carry the most weight, where the smells are — instead of reading files to find out. It does not answer prose or history questions.

First run

bash scripts/bootstrap.sh [repo-root] [--no-map]                                     # macOS / Linux / Git Bash
powershell -ExecutionPolicy Bypass -File scripts/bootstrap.ps1 [repo-root] [-NoMap]  # Windows

Checks Node >= 22, git, Docker and ripgrep, installs the CLI if missing, starts the backend, and maps the repo. Re-run it per repo.

Core workflow

Over MCP

When the ix-memory MCP server is connected (ix mcp; register it with ix mcp install), the same graph is five tools. Reach for them where Grep, Glob and Read need several steps or cannot answer at all:

Not for a literal string or a line in a file you already have open: that is Grep and Read. ix_context and ix_impact end in next records phrased as tool calls; an ambiguous name answers with candidates and pick=/path= to choose one. No health check is needed first. ix mcp --tools=all serves every command as a tool.

How to spend calls

1. Start with ix context <file-or-symbol> — one bounded call that names the files and symbols that matter, with line ranges.
2. Read the ranges, not the files. ix read <symbol>, or path:120-180, is one to three thousand tokens; the file around it is commonly thirty to sixty thousand — and every one of those is re-sent on every later step of the turn.
3. Ask the graph what grep cannot: ix callers, ix imported-by and ix impact answer "who uses this" and "what does a change reach" across files. Drill further with ix search, ix callees, ix contains, ix imports, ix depends, reusing the exact entity IDs from earlier output.
4. Do not poll ix status. A command that needs the backend says so itself, with a hint; a health check in front of every call is a wasted round trip.
5. Format: llm is the one to read, and IX_FORMAT=llm (or ix config set format llm) makes it the default so it need not be typed per call; json is for chaining or extracting a field. On ix context the same answer runs about 7.6 : 0.8 : 1 for json : llm : text.

Rules

1. Answer codebase questions from targeted ix commands, not from training data.
2. Never guess a codebase fact that Ix holds.
3. The graph is kept current for you: bootstrap maps the repo and editor plugins re-ingest edited files. Run ix map --silent only when results are visibly stale, such as after a branch switch or a pull.
4. When Ix reports low confidence, say so, and never present it as established fact.

References — load on demand

• references/commands.md — command routing tables, decomposition recipes, best practices, the do-not-use list. Before any command beyond the table above.
• references/flags.md — every flag the CLI registers, per command, with values and defaults. Before guessing whether a flag exists.
• references/output-formats.md — the llm|json|text rules, what does not implement llm, and which commands are Pro-gated.
• references/troubleshooting.md — prerequisites, ix doctor, backend health, environment flags. When a command fails.
• scripts/bootstrap.sh / scripts/bootstrap.ps1 — first-run setup (bash; and native PowerShell for Windows).