Getting Started

Quickstart: Your First 5 Minutes

Follow along with the Ix repo to go from zero to productive. Every command and output below is real.

Prerequisites: Docker Desktop installed and running. Works on macOS, Linux, and Windows.
Follow along: This tutorial uses the Ix repo as the example project. All output below is real — captured from running these exact commands on this repo. Clone it and run each command yourself.

01 — Install Ix

One command. Installs the CLI, starts the Docker backend (ArangoDB + Memory Layer), and sets up Claude Code hooks if you have Claude installed.

# macOS / Linux
curl -fsSL https://ix-infra.com/install.sh | sh

# Windows (PowerShell)
irm https://ix-infra.com/install.ps1 | iex

# or Homebrew (macOS)
brew install ix-infrastructure/ix/ix && ix docker start

02 — Clone the tutorial repo

This tutorial uses the Ix repo itself as the example project. Clone it so you can follow along and run every command yourself. The output you see below is real — captured from this exact repo.

git clone https://github.com/ix-infrastructure/Ix.git
cd Ix

03 — Map the project

This is where everything starts. Ix parses every source file with Tree-Sitter (14+ languages detected automatically), extracts entities and relationships, then runs Louvain community detection to group files into architectural regions based on how they actually connect.

ix map

OUTPUT

Architectural Map — 140 files · 10 regions

●  SYSTEM  Api  65 files  Well-defined 75%
   ├─  MODULE  Context    14 files  Moderate 51%
   └─  MODULE  Map         4 files  Moderate 53%

●  SYSTEM  Cli  75 files  Well-defined 75%
   ├─  MODULE  Explain     7 files  Fuzzy 46%
   └─  MODULE  Builder     7 files  Fuzzy 44%

04 — Search for something

Find entities by name. Always use --kind to filter — without it you get files, variables, claims. With it you get exactly what you're looking for. Results are ranked: exact matches first, then partial, then provenance matches.

ix search IxClient --kind class

OUTPUT

IxClient (class)
  ix-cli/src/client/api.ts
  score: 100  matchSource: name_exact

05 — Understand what you found

Without reading a single line of source code, you get: what it is, how important it is, who uses it, and what to do next. The explain engine uses 18-rule role inference and 4-tier importance scoring.

ix explain IxClient

OUTPUT

IxClient (class) — ix-cli/src/client/api.ts

  Role: api-client (high confidence)
  Importance: high — broad-shared-dependency
    45 dependents, 30 callers
    81 downstream dependents across 4 levels

  Members: search, explain, expand, commitPatch, commitPatchBulk, ...
  Used by: registerReadCommand, registerExplainCommand, and 42 others

  Suggested: ix impact IxClient

06 — Check what breaks before you change it

Impact analysis classifies risk into four categories: foundation (deeply embedded), boundary (connects subsystems), shared (widely used within a subsystem), and localized (safe to change).

ix impact IxClient

OUTPUT

Risk: HIGH (boundary)

  At-risk behaviors:
    commitPatch             12 callers
    search                   8 callers

  45 downstream entities across 3 subsystems.
  This is a boundary class connecting CLI to server.

07 — Trace a flow

Follow how something moves through your system. Trace maps the execution path or call chain for any symbol — across files and boundaries.

ix trace user_login_flow

OUTPUT

Trace: user_login_flow

  1. UserRouter.login         → routes/user.ts:12
  2. AuthService.authenticate → auth/service.ts:45
  3. validateToken             → auth/tokens.ts:12
  4. SessionStore.create       → sessions/store.ts:28

  4 hops · 3 files · 2 subsystems

08 — Read only the code you need

Now that you understand the architecture, dependencies, and risk — read the specific code by name. No file path required. Use --pick to disambiguate when a name exists in multiple files.

ix read ingestFiles --pick 1

OUTPUT

ix-cli/src/cli/commands/ingest.ts:45-92

  45 | async function ingestFiles(client: IxClient, paths: string[], ...) {
  46 |   const modules = await loadIngestionModules();
  47 |   const hashes = await loadExistingHashes(client);
  48 |   const batch: GraphPatchPayload[] = [];
  49 |   for (const file of paths) {
  50 |     const parsed = modules.parse(file);
  51 |     batch.push(buildPatch(parsed));
  52 |     if (batch.length >= BATCH_SIZE) await flushBatch(client, batch);
  ...

09 — What’s Next

You now know the core workflow. These tutorials go deeper — each one uses the same Ix repo you just cloned, so you can keep following along.

Understand a Codebase

Onboard to unfamiliar code top-down

Trace a Pipeline

Follow calls across system boundaries

Impact Analysis

Systematic blast-radius assessment