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 (26 languages)
`skills/ix/`	The agent skill this project ships: `SKILL.md`, `references/` (commands, 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              # build + vitest + parser smoke
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 reset is GLOBAL. ix reset / ix reset --code take 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, which the CLI does not expose. After a reset, re-map each workspace.
The OSS↔Pro command boundary is derived at runtime, not declared. main.ts snapshots ossCmdNames right after registerOssCommands(); the Pro probe diffs against it. Adding a command to oss.ts silently makes it OSS; removing one makes Pro own it. registerProCommands is async and MUST be awaited.
ix patches is OSS, not Pro (#371). It is implemented here and registered in oss.ts. @ix/pro also registers a patches; commander throws on the duplicate and Pro's tryRegister swallows the throw, so the OSS one — which registers first — wins on a Kartr install too. Do not re-add it to PRO_COMMANDS: a stub for a command that exists in OSS shadows the real implementation, and the failure is silent rather than a crash.
ix upgrade wipes ~/.ix/cli/compass. The Compass assets ship only via ix upgrade, and re-running the installer re-extracts over them, so a re-install can leave ix view with no UI. bootstrap.sh re-runs ix upgrade when it finds the directory missing; skip that with IX_SKIP_COMPASS=1.
Windows path trap: Git Bash /tmp ≠ Windows C:\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.sh to deploy to ~/.claude/skills/ix and ~/.agents/skills/ix → start a new agent session so the skill is re-read.
After modifying code: run ix map --silent to re-ingest.

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.

The section below is the auto-generated Ix CLI command reference (regenerated by the Ix Memory system — do not hand-edit between the markers):

Ix Memory System

This project uses Ix Memory — persistent, time-aware context for LLM assistants.

Interface

Use the ix CLI exclusively.

Output format. Query commands accept --format text|json|llm:

--format llm — prefer this when you are reading the result yourself. It is token-minimal and newline-delimited, and noticeably smaller than json on tree- and table-shaped output.
--format json — use when chaining results between commands, or when you need to pull a specific field out of the response.

Every command that accepts --format implements llm, with two exceptions that fall back to text without an error: diff --content (verbatim hunks) and ingest. The deprecated query accepts only text|json — passing --format llm to it silently renders text.

--format llm is not accepted at all by config, init, reset, upgrade, view, watch and docker, which take no --format; passing it is an unknown option error, not a fallback. Do not pass it blind. (ingest does accept --format, despite being an action command.)

Pro features. Some commands below are marked [Pro], as are the whole Planning and Workflows sections — every command in those two tables is Pro-only, including plan, plans, task, tasks and workflow. If any Pro command prints The '<name>' command requires Ix Pro., this install does not have them — skip that step, do not retry it, and do not mention it again for the rest of the session. Nothing outside those marks and those two sections is Pro-gated.

MANDATORY RULES

BEFORE answering codebase questions → use targeted ix CLI commands (see routing below). Do NOT answer from training data alone.
[Pro] AFTER every design or architecture decision → run ix decide <title> --rationale <text>. Skip permanently if it reports it requires Ix Pro.
When you notice contradictory information → run ix conflicts and present results to the user.
NEVER guess about codebase facts — if Ix has structured data, use it.
IMMEDIATELY after modifying code → run ix map --silent to re-ingest and update the graph.
[Pro] When the user states a goal → run ix truth add "<statement>". Skip permanently if it reports it requires Ix Pro.

Ix CLI Command Routing

Use bounded, composable CLI commands — never broad queries.

High-Level Workflow Commands (Preferred)

Start here. These aggregate multiple graph operations into single bounded responses.

Goal	Command	Example
Blast radius / impact	`ix impact`	`ix impact UserService --format llm`
Hotspot discovery	`ix rank`	`ix rank --by dependents --kind class --top 10 --format llm`
One-shot summary	`ix overview`	`ix overview IngestionService --format llm`
Scoped entity listing	`ix inventory`	`ix inventory --kind function --path auth.py --format llm`
[Pro] Plan work	`ix plan`	`ix plan task "title" --plan <id> --resolves <bugId> --workflow-staged '{"discover":["cmd"]}' --format json`
[Pro] Track decisions	`ix decide`	`ix decide "Use X" --rationale "..." --affects Entity --responds-to <bugId>`
[Pro] Create goals	`ix goal`	`ix goal create "Support GitHub" --format json`
[Pro] Session resume	`ix briefing`	`ix briefing --format json`
[Pro] Track bugs	`ix bug`	`ix bug create "title" --affects Entity`

Low-Level Primitives

Underlying structural commands — useful for debugging or fine-grained inspection.

Finding & Understanding Code

Goal	Command	Example
Find entity by name	`ix search`	`ix search IngestionService --kind class --limit 10`
Understand a symbol	`ix explain`	`ix explain IngestionService`
Read source code	`ix read`	`ix read src/auth.py:10-50` or `ix read verify_token`
Full entity details	`ix entity`	`ix entity <id> --format json`
Fast text search	`ix text`	`ix text "verify_token" --language python --limit 20`
Find symbol (graph+text)	`ix locate`	`ix locate AuthProvider --kind class`

Navigating Relationships

Goal	Command	Example
What calls a function	`ix callers`	`ix callers verify_token --format json`
What a function calls	`ix callees`	`ix callees processPayment`
Members of a class	`ix contains`	`ix contains IngestionService`
What an entity imports	`ix imports`	`ix imports auth_provider.py`
What imports an entity	`ix imported-by`	`ix imported-by AuthProvider`
Dependency impact	`ix depends`	`ix depends verify_token --depth 2`

History & Decisions

Only the first four work without Pro.

Goal	Command	Example
Entity history	`ix history`	`ix history <entityId> --format llm`
Changes between revisions	`ix diff`	`ix diff 1 5 --summary --format llm`
Detect contradictions	`ix conflicts`	`ix conflicts --format llm`
List recent patches	`ix patches`	`ix patches --limit 20 --format llm`
[Pro] Design decisions	`ix decisions`	`ix decisions --topic ingestion --limit 10`
[Pro] Record a decision	`ix decide`	`ix decide "Use CONTAINS" --rationale "Normalize edges" --responds-to <bugId>`
[Pro] Record a goal	`ix truth add`	`ix truth add "Support 100k file repos"`
[Pro] List goals	`ix truth list`	`ix truth list --format json`
[Pro] Bug tracking	`ix bug create`	`ix bug create "title" --severity high --affects Entity`
[Pro] Update bug status	`ix bug update`	`ix bug update <id> --status resolved`
[Pro] Bug listing	`ix bug list`	`ix bug list --status open --format json`
[Pro] Bug details	`ix bug show`	`ix bug show <id> --format json`

Planning (Pro)

Goal	Command	Example
Create a goal	`ix goal create`	`ix goal create "Support GitHub" --format json`
List goals	`ix goal list`	`ix goal list --status active --format json`
Create a plan	`ix plan create`	`ix plan create "Fix auth" --goal <id> --responds-to <bugId> --format json`
Add a task	`ix plan task`	`ix plan task "Step 1" --plan <id> --depends-on <taskId> --resolves <bugId> --workflow-staged '{"discover":["ix overview X"],"implement":["ix map"],"validate":["ix smells"]}' --format json`
Plan status	`ix plan status`	`ix plan status <id> --format json`
Next actionable task	`ix plan next`	`ix plan next <id> --with-workflow --format json`
Run next task workflow	`ix plan next`	`ix plan next <id> --run-workflow --stage discover --format json`
List all plans	`ix plans`	`ix plans --format json`
List tasks	`ix tasks`	`ix tasks --status pending --plan <id> --format json`
Task details	`ix task show`	`ix task show <id> --with-workflow --format json`
Update task	`ix task update`	`ix task update <id> --status done --format json`
Run task workflow stage	`ix task update`	`ix task update <id> --run-workflow discover --format json`

Workflows (Pro)

Workflows are staged command sequences (discover → implement → validate) attached to tasks, plans, or decisions. All commands must start with ix — no shell operators.

Goal	Command	Example
Attach workflow	`ix workflow attach`	`ix workflow attach task <id> --file workflow.json`
Show workflow	`ix workflow show`	`ix workflow show task <id> --format json`
Validate workflow	`ix workflow validate`	`ix workflow validate task <id>`
Run workflow	`ix workflow run`	`ix workflow run task <id> --stage implement --format json`

Workflow JSON format:

{
  "discover":   ["ix overview AuthService", "ix impact AuthService"],
  "implement":  ["ix map --silent"],
  "validate":   ["ix smells --format json", "ix subsystems --format json"]
}

Architecture Analysis

Goal	Command	Example
Detect code smells	`ix smells`	`ix smells --format json`
Score subsystems	`ix subsystems`	`ix subsystems --level 2 --format json`
List smell claims	`ix smells --list`	`ix smells --list --format json`
List subsystem scores	`ix subsystems --list`	`ix subsystems --list --format json`

Ingestion & Health

Goal	Command	Example
Update graph + map	`ix map --silent`	`ix map --silent`
Ingest GitHub data	`ix ingest`	`ix ingest --github owner/repo --limit 50`
Backend health	`ix status`	`ix status`
Graph statistics	`ix stats`	`ix stats --format json`

Decomposition Examples

"How does ingestion work?"

ix overview IngestionService --format json    # start here
# If you need more detail:
ix contains IngestionService --format json
ix callees parseFile --format json

"What depends on verify_token?"

ix impact verify_token --format json          # one-shot answer
# or manually:
ix callers verify_token --format json
ix imported-by verify_token --format json

"What are the most important classes?"

ix rank --by dependents --kind class --top 10 --format json

"List all functions"

ix inventory --kind function --format json

Best Practices

Always use --kind with ix search to get bounded results
Use ix inventory instead of ix search "" for listing entities by kind
Use ix diff --summary for broad revision comparisons (server-side, fast)
Use --full only when you need every individual change
Always use --limit to cap result sets — except on ix diff, where --summary and --full each already fix the volume and passing --limit alongside either is refused rather than silently ignored
Use --format llm when you are reading the output; --format json only when chaining results between commands or extracting a specific field
Use --path or --language to restrict text searches
Use exact entity IDs from previous JSON results
Decompose large questions into multiple targeted calls

Semantic Boundaries [Pro]

These record types are Pro-only. Use the right one for the purpose:

decision — a choice between alternatives, with rationale. Use ix decide.
bug — something broken, missing, or incorrect. Use ix bug create.
task/plan — intended work and sequencing. Use ix plan / ix plan task.

Do NOT Use

ix query — deprecated, produces oversized low-signal responses
NLP-style QA in a single command

Confidence Scores

Ix returns confidence scores with results. When data has low confidence:

Mention the uncertainty to the user
Suggest re-running ix map to refresh the graph
Never present low-confidence data as established fact

Navigation Menu

Uh oh!

Project: Ix (this repo)

Layout

Commands

Boundaries & Gotchas (all verified this session — write these down, they cost hours)

Patterns

Typecheck & Test Discipline

Ix Memory System

Interface

MANDATORY RULES

Ix CLI Command Routing

High-Level Workflow Commands (Preferred)

Low-Level Primitives

Finding & Understanding Code

Navigating Relationships

History & Decisions

Planning (Pro)

Workflows (Pro)

Architecture Analysis

Ingestion & Health

Decomposition Examples

Best Practices

Semantic Boundaries [Pro]

Do NOT Use

Confidence Scores

Uh oh!

FilesExpand file tree

CLAUDE.md

Latest commit

History

CLAUDE.md

File metadata and controls

Project: Ix (this repo)

Layout

Commands

Boundaries & Gotchas (all verified this session — write these down, they cost hours)

Patterns

Typecheck & Test Discipline

Ix Memory System

Interface

MANDATORY RULES

Ix CLI Command Routing

High-Level Workflow Commands (Preferred)

Low-Level Primitives

Finding & Understanding Code

Navigating Relationships

History & Decisions

Planning (Pro)

Workflows (Pro)

Architecture Analysis

Ingestion & Health

Decomposition Examples

Best Practices

Semantic Boundaries [Pro]

Do NOT Use

Confidence Scores