Skip to content

armgit / Ix

Public Imported from GitHub
0

Understand any codebase instantly. System intelligence for codebases, built for humans and AI.

docs(skill): steer the skill to ranges, and stop shipping install notes in it (#684)

Ian Hockc39f1bdc8192
diff --git a/docs/README.md b/docs/README.md
index 438cb3c4..b19d9631 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -5,4 +5,5 @@
- [`ix mcp`](mcp.md) — serving the graph tools over MCP, and registering AI clients
- [Consolidating the per-host plugins onto `ix mcp`](mcp-plugin-consolidation.md)
- [System prerequisites](prerequisites.md) — what the installer checks for and installs
+- [Installing the skill into a harness](skill-harnesses.md) — where `install-skill.sh` writes, and how it decides a harness is present
- [Parse-pool teardown](parse-pool-teardown.md) — why nothing calls `terminate()`, and what was measured
diff --git a/docs/skill-harnesses.md b/docs/skill-harnesses.md
new file mode 100644
index 00000000..6eee8fb4
--- /dev/null
+++ b/docs/skill-harnesses.md
@@ -0,0 +1,38 @@
+# Installing the skill into a harness
+
+Where `scripts/install-skill.sh` puts `skills/ix`, how it decides a harness is
+present, and the two environment seams its probe battery reads.
+
+This lived in `skills/ix/SKILL.md` until it was moved here. It is contributor
+documentation: an agent that loads the skill to answer a question about a
+codebase pays for every byte of it and can act on none of it.
+
+The skill installer (`scripts/install-skill.sh`) reads an explicit, small harness table from `ix-cli/scripts/skill-harnesses.mjs` — claude, agents, codex and cursor only. Each entry's skills directory is verified against what that harness actually reads (Cursor uses `~/.cursor/skills-cursor`, not `~/.cursor/skills`); gemini, opencode, openclaw and vscode have no skills convention, so they are deliberately not install targets. Adding a harness is a one-line edit in that table, after checking where the harness really looks. `ix mcp install` uses the separate MCP host registry (`ix-cli/src/mcp/hosts.ts`) — a different table answering a different question.
+
+When `TOOLSCAN_PATH` is set, both surfaces consult its discovery output so a harness CLI installed outside `PATH` can still be found — and `ix mcp install` executes the absolute path toolscan reports, so the off-PATH harness is inspected and registered through the binary toolscan found. Toolscan is optional and additive: if it is unset or fails, the embedded `PATH` and config-directory probes remain authoritative. `TOOLSCAN_PATH` is opt-in: neither surface ever looks `toolscan` up on `PATH` (the CLI executes whatever `TOOLSCAN_PATH` names, so only set it to a binary you trust).
+
+The probe battery has two environment seams:
+
+| Seam | Used by | Default |
+|---|---|---|
+| `TOOLSCAN_PATH` | `skill-harnesses.mjs --probe`, `ix mcp install` | Unset — no toolscan, embedded probes decide |
+| `HARNESS_HOME` | `skill-harnesses.mjs --probe` | `os.homedir()`; `install-skill.sh` uses the shell's `$HOME` |
+
+For a hermetic probe with no real user configuration:
+
+```bash
+HARNESS_HOME="$(mktemp -d)" \
+ node ix-cli/scripts/skill-harnesses.mjs --probe
+```
+
+To drive the same probe with a local or npm-installed toolscan bundle:
+
+```bash
+TOOLSCAN_PATH=/path/to/toolscan/dist/toolscan.mjs \
+ HARNESS_HOME="$(mktemp -d)" \
+ node ix-cli/scripts/skill-harnesses.mjs --probe
+```
+
+`--probe` emits `id|label|bin|config-dir|skill-dir|present|detectedVia`, where `present` is `1` or `0` and `detectedVia` names the probe that decided (`toolscan` | `path` | `config-dir` | `none`). `scripts/install-skill.sh --dry-run --json` emits the same per-harness view as machine-readable JSON: one object per host with `action` (`would-install` | `would-refuse` | `installed` | `refused` | `skip`), `dest`, and `detectedVia` — so CI can assert *how* a harness was found, not just that it was. A `would-refuse` in the preview exits 1, matching the real run's conflict exit, so scripts can rely on the two agreeing.
+
+The install report's `--format json|llm` output carries `detectedVia` per host (`toolscan` | `path` | `config-dir` | `none`), so a consumer can see which probe decided presence — a host toolscan found reads `toolscan` even when its CLI also happens to be on PATH, and a host found by the PATH probe reads `path` rather than being misattributed to its config directory.
diff --git a/skills/ix/SKILL.md b/skills/ix/SKILL.md
index 35a0a363..21112044 100644
--- a/skills/ix/SKILL.md
+++ b/skills/ix/SKILL.md
@@ -1,6 +1,6 @@
---
name: ix
-description: "This skill should be used when answering structural questions about a codebase: understanding what a symbol is, tracing flows, measuring change impact, finding callers/callees/imports, or detecting code smells. It drives the Ix CLI (ix map/explain/trace/impact/search/rank/smells) against a persistent code graph stored in a local backend, instead of grepping or guessing. Run scripts/bootstrap.sh once to install the CLI and start the backend, then ix map on the repo root."
+description: "Answer structural questions about a codebase — what a symbol is, what calls it, what a change breaks, where the hotspots are — from a persistent code graph via the ix CLI, instead of grepping."
license: Apache-2.0
metadata:
version: 1.0.0
@@ -9,108 +9,70 @@ metadata:
# Ix — Persistent Codebase Map
-## Overview
+Ix parses a repository with tree-sitter (26 languages) into a graph of symbols,
+calls and imports, kept in a local backend (ArangoDB via Docker) and persisted
+between sessions. Query it for structural answers — what a symbol is, what calls
+it, how a flow moves, what a change breaks, which files carry the most weight,
+where the smells are — instead of reading files to find out. It does not answer
+prose or history questions.
-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:
+## First run
```bash
-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
+bash scripts/bootstrap.sh [repo-root] [--no-map] # macOS / Linux / Git Bash
+powershell -ExecutionPolicy Bypass -File scripts/bootstrap.ps1 [repo-root] [-NoMap] # Windows
```
-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:
+Checks Node >= 22, git, Docker and ripgrep, installs the CLI if missing, starts
+the backend, and maps the repo. Re-run it per repo.
-```bash
-ix map --silent
-```
-
-## Core Workflow
-
-Map → Explain → Trace → Impact
+## Core workflow
| Step | Command | Example |
|---|---|---|
-| Build/refresh the graph | `ix map` | `ix map .` |
+| Bounded context to start from | `ix context` | `ix context IngestionService` |
| Understand a component | `ix explain` | `ix explain IngestionService` |
-| Bounded deterministic context | `ix context` | `ix context IngestionService --max-entities 20` |
| Trace a flow | `ix trace` | `ix trace user_login_flow` |
-| Analyze impact | `ix impact` | `ix impact verify_token --format llm` |
-
-## 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; for a command's complete flag list, load references/flags.md.
-5. If the backend is unreachable or a command fails, load references/troubleshooting.md.
+| Blast radius of a change | `ix impact` | `ix impact verify_token` |
+| Build / refresh the graph | `ix map` | `ix map .` |
+
+## How to spend calls
+
+1. **Start with `ix context <file-or-symbol>`** — one bounded call that names the
+ files and symbols that matter, with line ranges.
+2. **Read the ranges, not the files.** `ix read <symbol>`, or `path:120-180`, is
+ one to three thousand tokens; the file around it is commonly thirty to sixty
+ thousand — and every one of those is re-sent on every later step of the turn.
+3. Drill down with primitives, reusing the exact entity IDs from earlier output:
+ `ix search`, `ix callers`, `ix callees`, `ix contains`, `ix imports`,
+ `ix imported-by`, `ix depends`.
+4. **Do not poll `ix status`.** A command that needs the backend says so itself,
+ with a hint; a health check in front of every call is a wasted round trip.
+5. Format: `llm` is the one to read, and `IX_FORMAT=llm` (or
+ `ix config set format llm`) makes it the default so it need not be typed per
+ call; `json` is for chaining or extracting a field. On `ix context` the same
+ answer runs about 7.6 : 0.8 : 1 for json : llm : text.
## 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.
-
-## Harness install seam
-
-The skill installer (`scripts/install-skill.sh`) reads an explicit, small harness table from `ix-cli/scripts/skill-harnesses.mjs` — claude, agents, codex and cursor only. Each entry's skills directory is verified against what that harness actually reads (Cursor uses `~/.cursor/skills-cursor`, not `~/.cursor/skills`); gemini, opencode, openclaw and vscode have no skills convention, so they are deliberately not install targets. Adding a harness is a one-line edit in that table, after checking where the harness really looks. `ix mcp install` uses the separate MCP host registry (`ix-cli/src/mcp/hosts.ts`) — a different table answering a different question.
-
-When `TOOLSCAN_PATH` is set, both surfaces consult its discovery output so a harness CLI installed outside `PATH` can still be found — and `ix mcp install` executes the absolute path toolscan reports, so the off-PATH harness is inspected and registered through the binary toolscan found. Toolscan is optional and additive: if it is unset or fails, the embedded `PATH` and config-directory probes remain authoritative. `TOOLSCAN_PATH` is opt-in: neither surface ever looks `toolscan` up on `PATH` (the CLI executes whatever `TOOLSCAN_PATH` names, so only set it to a binary you trust).
-
-The probe battery has two environment seams:
-
-| Seam | Used by | Default |
-|---|---|---|
-| `TOOLSCAN_PATH` | `skill-harnesses.mjs --probe`, `ix mcp install` | Unset — no toolscan, embedded probes decide |
-| `HARNESS_HOME` | `skill-harnesses.mjs --probe` | `os.homedir()`; `install-skill.sh` uses the shell's `$HOME` |
-
-For a hermetic probe with no real user configuration:
-
-```bash
-HARNESS_HOME="$(mktemp -d)" \
- node ix-cli/scripts/skill-harnesses.mjs --probe
-```
-
-To drive the same probe with a local or npm-installed toolscan bundle:
-
-```bash
-TOOLSCAN_PATH=/path/to/toolscan/dist/toolscan.mjs \
- HARNESS_HOME="$(mktemp -d)" \
- node ix-cli/scripts/skill-harnesses.mjs --probe
-```
-
-`--probe` emits `id|label|bin|config-dir|skill-dir|present|detectedVia`, where `present` is `1` or `0` and `detectedVia` names the probe that decided (`toolscan` | `path` | `config-dir` | `none`). `scripts/install-skill.sh --dry-run --json` emits the same per-harness view as machine-readable JSON: one object per host with `action` (`would-install` | `would-refuse` | `installed` | `refused` | `skip`), `dest`, and `detectedVia` — so CI can assert *how* a harness was found, not just that it was. A `would-refuse` in the preview exits 1, matching the real run's conflict exit, so scripts can rely on the two agreeing.
-
-The install report's `--format json|llm` output carries `detectedVia` per host (`toolscan` | `path` | `config-dir` | `none`), so a consumer can see which probe decided presence — a host toolscan found reads `toolscan` even when its CLI also happens to be on PATH, and a host found by the PATH probe reads `path` rather than being misattributed to its config directory.
-
-## 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/flags.md** — every flag the CLI registers, per command, with values and defaults. Load when a command needs shaping beyond the examples in commands.md, or to check whether a flag exists before guessing.
-- **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.
+1. Answer codebase questions from targeted `ix` commands, not from training data.
+2. Never guess a codebase fact that Ix holds.
+3. On contradictory information, run `ix conflicts` and present the results.
+4. Refresh with `ix map --silent` when the graph has gone stale — after a branch
+ switch, a pull, or a batch of edits. Editor plugins re-ingest edited files on
+ a debounce; this is not a per-edit step.
+5. When Ix reports low confidence, say so, suggest re-running `ix map`, and never
+ present it as established fact.
+
+## References — load on demand
+
+- **references/commands.md** — command routing tables, decomposition recipes,
+ best practices, the do-not-use list. Before any command beyond the table above.
+- **references/flags.md** — every flag the CLI registers, per command, with
+ values and defaults. Before guessing whether a flag exists.
+- **references/output-formats.md** — the `llm|json|text` rules, what does not
+ implement `llm`, and which commands are Pro-gated.
+- **references/troubleshooting.md** — prerequisites, `ix doctor`, backend health,
+ environment flags. When a command fails.
+- **scripts/bootstrap.sh** / **scripts/bootstrap.ps1** — first-run setup (bash;
+ and native PowerShell for Windows).
diff --git a/skills/ix/references/commands.md b/skills/ix/references/commands.md
index 418e67f6..90e0596e 100644
--- a/skills/ix/references/commands.md
+++ b/skills/ix/references/commands.md
@@ -7,17 +7,23 @@ This file routes a goal to a command. For the complete flag surface of any
command — every option, its accepted values and its default — see
[flags.md](flags.md).
+The examples carry no `--format`. Set it once instead of per call: `IX_FORMAT=llm`
+in the environment, or `ix config set format llm`. `llm` is the format to read —
+records, one per line, and on `ix context` roughly a ninth of the bytes of the
+same answer in `json`. Reach for `--format json` on the one call whose output you
+are going to parse. See [output-formats.md](output-formats.md).
+
## High-Level Workflow Commands (prefer first)
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` |
-| Deterministic context bundle | `ix context` | `ix context IngestionService --format llm` |
-| Scoped entity listing | `ix inventory` | `ix inventory --kind function --path auth.py --format llm` |
+| Blast radius / impact | `ix impact` | `ix impact UserService` |
+| Hotspot discovery | `ix rank` | `ix rank --by dependents --kind class --top 10` |
+| One-shot summary | `ix overview` | `ix overview IngestionService` |
+| Deterministic context bundle | `ix context` | `ix context IngestionService` |
+| Scoped entity listing | `ix inventory` | `ix inventory --kind function --path auth.py` |
## Finding & Understanding Code
@@ -26,7 +32,7 @@ These aggregate multiple graph operations into single bounded responses.
| 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` |
+| Full entity details | `ix entity` | `ix entity <id>` |
| Fast text search | `ix text` | `ix text "verify_token" --language python --limit 20` |
| Find symbol (graph+text) | `ix locate` | `ix locate AuthProvider --kind class` |
@@ -34,7 +40,7 @@ These aggregate multiple graph operations into single bounded responses.
| Goal | Command | Example |
|---|---|---|
-| What calls a function | `ix callers` | `ix callers verify_token --format json` |
+| What calls a function | `ix callers` | `ix callers verify_token` |
| 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` |
@@ -45,18 +51,18 @@ These aggregate multiple graph operations into single bounded responses.
| 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` |
+| Entity history | `ix history` | `ix history <entityId>` |
+| Changes between revisions | `ix diff` | `ix diff 1 5 --summary` |
+| Detect contradictions | `ix conflicts` | `ix conflicts` |
## 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` |
+| Detect code smells | `ix smells` | `ix smells` |
+| Score subsystems | `ix subsystems` | `ix subsystems --level 2` |
+| List smell claims | `ix smells --list` | `ix smells --list` |
+| List subsystem scores | `ix subsystems --list` | `ix subsystems --list` |
## Ingestion & Health
@@ -67,14 +73,14 @@ These aggregate multiple graph operations into single bounded responses.
| Backend health | `ix status` | `ix status` |
| System doctor | `ix doctor` | `ix doctor` |
| Start backend | `ix docker start` | `ix docker start` |
-| Graph statistics | `ix stats` | `ix stats --format json` |
+| Graph statistics | `ix stats` | `ix stats` |
## Session Metrics
| Goal | Command | Example |
|---|---|---|
-| Token savings so far | `ix savings` | `ix savings --format llm` |
-| Per-command breakdown | `ix savings --detail` | `ix savings --detail --format llm` |
+| Token savings so far | `ix savings` | `ix savings` |
+| Per-command breakdown | `ix savings --detail` | `ix savings --detail` |
| Clear lifetime totals | `ix savings reset` | `ix savings reset` |
`ix savings` reports how many tokens the graph saved against a naive
@@ -92,7 +98,7 @@ estimates.
|---|---|---|---|
| `--detail` | — | off | Add one record per command type, within each scope |
| `--model <model>` | `opus\|sonnet\|haiku\|gpt-4o` | `opus` | Pricing table for `money_saved` only — token and water figures do not change |
-| `--format <fmt>` | `text\|json\|llm` | `text` | See output-formats.md |
+| `--format <fmt>` | `text\|json\|llm` | `IX_FORMAT`, else `format` in config, else `text` | See output-formats.md |
`ix savings reset` clears **both** scopes (`DELETE /v1/savings`, which runs
`session.set(empty) *> store.resetSavings`). It takes no flags, does not prompt,
@@ -122,26 +128,26 @@ Reading a graph command's savings needs the backend up: the numbers come from
**"How does ingestion work?"**
```bash
-ix overview IngestionService --format json # start here
-ix contains IngestionService --format json # more detail if needed
-ix callees parseFile --format json
+ix overview IngestionService # start here
+ix contains IngestionService # more detail if needed
+ix callees parseFile
```
**"What depends on verify_token?"**
```bash
-ix impact verify_token --format json # one-shot answer
-ix callers verify_token --format json # or manually
-ix imported-by verify_token --format json
+ix impact verify_token # one-shot answer
+ix callers verify_token # or manually
+ix imported-by verify_token
```
**"What are the most important classes?"**
```bash
-ix rank --by dependents --kind class --top 10 --format json
+ix rank --by dependents --kind class --top 10
```
**"List all functions in a file"**
```bash
-ix inventory --kind function --path auth.py --format llm
+ix inventory --kind function --path auth.py
```
## Best Practices
diff --git a/skills/ix/references/output-formats.md b/skills/ix/references/output-formats.md
index 22e958c9..4aa0bd29 100644
--- a/skills/ix/references/output-formats.md
+++ b/skills/ix/references/output-formats.md
@@ -5,17 +5,31 @@
Query commands accept `--format text|json|llm`:
- **`--format llm`** — use when reading the result yourself. Token-minimal,
- newline-delimited (`key=value`, one record per line). Smallest output.
+ newline-delimited (`key=value`, one record per line). Smallest output; on
+ `ix context` it is roughly a ninth of the same answer in `json`.
- **`--format json`** — use when chaining results between commands or pulling a
specific field out of a response.
- **`--format text`** — human-oriented tables and trees.
+### Setting it once
+
+Resolution is: the flag, then `IX_FORMAT`, then `format` in `~/.ix/config.yaml`
+(`ix config set format llm`), then `text`. Set the env var or the config key and
+stop passing the flag; an explicit `--format` still wins on the call that needs
+something else. `ix config show` reports when `IX_FORMAT` is overriding the
+stored value.
+
+A command that does not implement the configured format keeps its own default
+rather than being handed one it cannot render — `query` renders `text` and
+`json` only, so `IX_FORMAT=llm` leaves it on `text`.
+
### Commands that accept `--format` but route `llm` to `text`
-`explain`, `read`, `status`, and the deprecated `query` do not implement `llm`
-and fall back to human-oriented text without an error. Use `--format json` on
-those if the output needs to be parsed. Everywhere else, `llm` behaves as
-documented.
+The deprecated `query` takes `text|json` only. `diff --content` (verbatim hunks)
+and `ingest` fall back to text without an error. `explain`, `read`, `status`,
+`doctor` and `savings` **do** implement `llm` — that was the last prose
+fallback, and `explain`'s records are about 55% smaller than the `json` people
+used as a workaround.
### Commands with no `--format` at all