CLAUDE.md · diff
git:20260905.fce9b5c to git:20260921.a221b51
10 added, 218 removed. Audit A to A.
# 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, 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
```bash
# 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.
+ - **After modifying code:** the editor plugins re-ingest the edited file on a
+ debounce, so `ix map --silent` is 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.
---
- 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 START -->
- # 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
- 1. BEFORE answering codebase questions → use targeted `ix` CLI commands (see routing below). Do NOT answer from training data alone.
- 2. **[Pro]** AFTER every design or architecture decision → run `ix decide <title> --rationale <text>`. Skip permanently if it reports it requires Ix Pro.
- 3. When you notice contradictory information → run `ix conflicts` and present results to the user.
- 4. NEVER guess about codebase facts — if Ix has structured data, use it.
- 5. IMMEDIATELY after modifying code → run `ix map --silent` to re-ingest and update the graph.
- 6. **[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:**
- ```json
- {
- "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?"**
- ```bash
- 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?"**
- ```bash
- 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?"**
- ```bash
- ix rank --by dependents --kind class --top 10 --format json
- ```
-
- **"List all functions"**
- ```bash
- 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`.
+ ## Using `ix` in this repo
- ## Do NOT Use
- - `ix query` — deprecated, produces oversized low-signal responses
- - NLP-style QA in a single command
+ 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`.
- ## 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
- <!-- IX-MEMORY END -->
+ 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.