Understand any codebase instantly. System intelligence for codebases, built for humans and AI.
Project: Ix (this repo)
This checkout is Ix itself plus the ix agent skill that wraps it. The
backend is NOT in this repo — it is the released Docker image running at
http://localhost:8090; the Compass visualizer serves the SPA + API proxy on
http://localhost:8080. Requires Node ≥ 22, git, Docker, ripgrep.
Layout
| Path | What it is |
|---|---|
ix-cli/ |
The @ix/cli TypeScript package — command routing (src/cli/), registration hub (src/cli/register/oss.ts), HTTP client (src/client/api.ts), response types (src/client/types.ts) |
core-ingestion/ |
Tree-sitter parser/classifier (27 languages) |
skills/ix/ |
The agent skill this project ships: SKILL.md, references/ (commands, flags, output-formats, troubleshooting), scripts/ (bootstrap.sh/ps1) |
docs/ |
api/ (HTTP API reference + OpenAPI spec), llm-format.md, prerequisites.md |
scripts/ |
bootstrap.sh (first-run), install-skill.sh (deploy skill to ~/.claude/skills + ~/.agents/skills) |
Commands
# CLI dev (from ix-cli/)
npm run build # build-core-ingestion + tsc
npm run typecheck # tsc --noEmit
npm test # core-ingestion build + vitest + parser smoke; does NOT rebuild
# ix-cli/dist -- run `npm run build` before using dist/cli/main.js
npm run dev # tsx src/cli/main.ts
# Skill + tooling (from repo root)
bash scripts/bootstrap.sh [repo-root] # install CLI, start backend, map repo
bash scripts/install-skill.sh # deploy skills/ix to ~/.claude + ~/.agents
# Repackage the skill zip into ./dist (gitignored). Needs the skill-creator
# skill installed; on Windows set PYTHONIOENCODING=utf-8 or its emoji print crashes.
python "$HOME/.agents/skills/skill-creator/scripts/package_skill.py" skills/ix ./dist
# Visualizer / preview
ix view start --all --no-open --port 8080 # combined multi-workspace view
ix map --silent # refresh the graph after code changes
Boundaries & Gotchas (all verified this session — write these down, they cost hours)
ix resetis GLOBAL.ix reset/ix reset --codetake no workspace_id and wipe every workspace's graph in the shared backend (Ix + packwise + any other). The only scoped variant is/v1/reset/workspace, exposed asix reset --workspace(the registered workspace containing cwd, nothing else). After a global reset, re-map each workspace.- The OSS↔Pro command boundary is derived at runtime, not declared.
run-cli.tssnapshotsossCmdNamesright after registering the OSS commands; the Pro probe diffs against it. Adding a command tooss.tssilently makes it OSS; removing one makes Pro own it.registerProCommandsis async and MUST be awaited. - A new OSS command goes in two places:
registerOssCommands()inregister/oss.tsandOSS_COMMAND_TABLEinregister/oss-table.ts. With Pro absent,run-cli.tsloads only the table entry for the command being run. A command missing from the table still works (it takes the full path), butstartup-fast-path.test.tsfails until it is added. The shared per-command setup is inregister/oss-setup.ts. ix patchesis OSS, not Pro (#371). It is implemented here and registered inoss.ts.@ix/proalso registers apatches; commander throws on the duplicate and Pro'stryRegisterswallows the throw, so the OSS one — which registers first — wins on a Kartr install too. Do not re-add it toPRO_COMMANDS(register/pro-stubs.ts): a stub for a command that exists in OSS shadows the real implementation, and the failure is silent rather than a crash.ix upgradewipes~/.ix/cli/compass. The Compass assets ship only viaix upgrade, and re-running the installer re-extracts over them, so a re-install can leaveix viewwith no UI.bootstrap.shre-runsix upgradewhen it finds the directory missing; skip that withIX_SKIP_COMPASS=1.- Windows path trap: Git Bash
/tmp≠ WindowsC:\tmp— node/python cannot read files Git Bash wrote to/tmp. Use project-relative paths.
Patterns
- Skill edit workflow: edit
skills/ix/→bash scripts/install-skill.shto deploy to~/.claude/skills/ixand~/.agents/skills/ix→ start a new agent session so the skill is re-read. - After modifying code: the editor plugins re-ingest the edited file on a
debounce, so
ix map --silentis for when you are working without one, or want the whole graph refreshed now — not for every edit.
Typecheck & Test Discipline
Run npm run typecheck (from ix-cli/) after non-trivial CLI edits and
node --check on any edited standalone script before deploying.
Using ix in this repo
Command routing, what each command answers, and the output formats are not
repeated here — they live where they are read on demand: skills/ix/SKILL.md
and skills/ix/references/, docs/llm-format.md, and ix <command> --help.
A ~10 KB copy of that reference used to sit in this file behind
<!-- IX-MEMORY START --> markers, labelled auto-generated. Nothing in this
repo has generated it for a long time.