Ix — Persistent Codebase Map

Overview

Ix parses a repository with tree-sitter (26 languages), builds a graph of its symbols, calls, and imports, and stores it in a local backend (ArangoDB via Docker). Query that graph with ix commands to answer bounded, structural questions instead of reading files blindly. The graph persists between sessions.

Use this skill whenever the question is about structure, relationships, or impact: what a symbol is, what calls it, what it calls, how data flows, what breaks if a change lands, which files are most depended-on, or where the smells are.

When to Use

• Answering "what is this / what does it touch" questions about a symbol, class, or module.
• Tracing how a flow moves through the system.
• Estimating blast radius before a change.
• Finding callers, callees, imports, and dependents.
• Detecting smells, ranking hotspots, and scoring subsystems.
• Onboarding to an unfamiliar codebase.

Do not use this skill for prose-style or history questions — use it for structural, graph-backed answers.

Quick Start (first run)

Map the target repo with the bootstrap script:

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

The bootstrap checks Node >= 22, git, Docker, and ripgrep; installs the ix CLI if missing; starts the local Docker backend; and maps the repo by default. Re-run scripts/bootstrap.sh on each new repo to register and map it.

Refresh the graph after code changes:

ix map --silent

Core Workflow

Map → Explain → Trace → Impact

Using the Skill

1. Start with high-level commands for one-shot answers: ix overview, ix impact, ix rank.
2. Drill down with primitives — ix search, ix callers, ix callees, ix contains, ix imports, ix imported-by, ix depends — reusing exact entity IDs from prior JSON output.
3. Prefer --format llm when reading output yourself (token-minimal); use --format json when chaining commands or extracting a field. See references/output-formats.md.
4. For the full command surface, decomposition recipes, and best practices, load references/commands.md.
5. If the backend is unreachable or a command fails, load references/troubleshooting.md.

Rules

1. Before answering codebase questions, run targeted ix commands. Do not answer from training data alone.
2. After noticing contradictory information, run ix conflicts and present the results.
3. Never guess codebase facts — if Ix has structured data, use it.
4. Immediately after modifying code, run ix map --silent to re-ingest.
5. When Ix reports low confidence, mention the uncertainty to the user, suggest re-running ix map, and never present low-confidence data as established fact.

References

• references/commands.md — full command routing tables, decomposition recipes, best practices, and the do-not-use list. Load before running any command beyond the core four above.
• references/output-formats.md — --format llm|json|text rules, commands that do not implement llm, and Pro-gated commands. Load when formatting output or when a "requires Ix Pro" error appears.
• references/troubleshooting.md — prerequisites, backend health checks, ix doctor, and environment flags. Load when a command fails or the backend is unreachable.

Scripts

• scripts/bootstrap.sh — cross-platform first-run setup (bash; works on macOS, Linux, and Windows under Git Bash / MSYS2 / WSL).
• scripts/bootstrap.ps1 — native Windows PowerShell first-run setup.