Understand any codebase instantly. System intelligence for codebases, built for humans and AI.
TypeScript aiai-memoryclaude-codeclicode-analysiscode-mappingcode-memorycodebase-understandingcodexdeveloper-toolsllmopenclawpersistent-memoryprogram-analysissoftware-architecturesystem-intelligencesystem-mapping
docs: position high-level workflow commands as preferred entry points
riley0227e9231d3d8b6d
diff --git a/AGENTS.md b/AGENTS.mdindex f9357d0f..a6b5319a 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -53,7 +53,28 @@ Each result entity in `results` includes:## Command routing-### Finding code+### Start here — high-level workflow commands++These are the preferred entry points. Use them first; drop to low-level commands only when you need fine-grained control.++```+ix impact <target> --format json # Blast radius / dependency consequences+ix rank --by <metric> --kind <kind> --top N --format json # Hotspot discovery+ix overview <target> --format json # One-shot structural summary of a component+ix inventory --kind <kind> --format json # Scoped entity listing+```++**When to use which:**+- "What breaks if I change X?" → `ix impact X`+- "What are the most important classes?" → `ix rank --by dependents --kind class --top 10`+- "Tell me about UserService" → `ix overview UserService`+- "List all functions in auth.py" → `ix inventory --kind function --path auth.py`++### Low-level structural primitives++Useful for debugging, fine-grained inspection, or when high-level commands don't cover your case.++#### Finding code```ix search <term> --format json --limit 10ix text <term> --format json --language python@@ -61,13 +82,13 @@ ix locate <symbol> --format jsonix read <file:lines>```-### Understanding entities+#### Understanding entities```ix explain <symbol> --format jsonix entity <id> --format json```-### Navigating relationships+#### Navigating relationships```ix callers <symbol> --format jsonix callees <symbol> --format json@@ -93,10 +114,9 @@ ix diff <from> <to> --format json## Chaining pattern-1. Search: `ix search MyClass --format json --limit 5`-2. Pick the result with `resolved: true` and extract `id`-3. Drill in: `ix explain MyClass --format json` or `ix entity <id> --format json`-4. Navigate: `ix callers MyClass --format json`+1. Start broad: `ix overview MyClass --format json` or `ix impact MyClass --format json`+2. If you need more detail, drill in: `ix explain MyClass --format json` or `ix entity <id> --format json`+3. Navigate edges: `ix callers MyClass --format json`## Handling unresolved referencesdiff --git a/CLAUDE.md b/CLAUDE.mdindex 921e42cf..b94fb62f 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -21,7 +21,22 @@ All commands support `--format json` for machine-readable output. Use JSON whenUse bounded, composable CLI commands — never broad queries.-### Finding & Understanding Code+### 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 json` |+| Hotspot discovery | `ix rank` | `ix rank --by dependents --kind class --top 10` |+| One-shot summary | `ix overview` | `ix overview IngestionService --format json` |+| Scoped entity listing | `ix inventory` | `ix inventory --kind function --path auth.py` |++### 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` |@@ -31,7 +46,7 @@ Use bounded, composable CLI commands — never broad queries.| Fast text search | `ix text` | `ix text "verify_token" --language python --limit 20` || Find symbol (graph+text) | `ix locate` | `ix locate AuthProvider --limit 10` |-### Navigating Relationships+#### Navigating Relationships| Goal | Command | Example ||---|---|---|| What calls a function | `ix callers` | `ix callers verify_token --format json` |@@ -64,24 +79,28 @@ Use bounded, composable CLI commands — never broad queries.**"How does ingestion work?"**```bash-ix search IngestionService --kind class --format json-ix explain IngestionService --format json+ix overview IngestionService --format json # start here+# If you need more detail:ix contains IngestionService --format jsonix callees parseFile --format json```**"What depends on verify_token?"**```bash-ix depends verify_token --format json+ix impact verify_token --format json # one-shot answer# or manually:ix callers verify_token --format jsonix imported-by verify_token --format json```-**"List all files and their imports"**+**"What are the most important classes?"**+```bash+ix rank --by dependents --kind class --top 10 --format json+```++**"List all functions"**```bash-ix search "" --kind file --limit 50 --format json-ix imports <filename> --format json # for each file+ix inventory --kind function --format json```### Best Practices@@ -95,7 +114,6 @@ ix imports <filename> --format json # for each file## Do NOT Use- `ix query` — deprecated, produces oversized low-signal responses- MCP tools (`ix_query`, `ix_search`, etc.) — deprecated, use CLI instead-- Broad repo-wide inventory queries- NLP-style QA in a single command## Confidence Scoresdiff --git a/README.md b/README.mdindex a65ba600..30bc2a87 100644--- a/README.md+++ b/README.md@@ -12,6 +12,7 @@ MCP is still present for compatibility, but the primary interface is `ix` CLI co- File ingestion: `.py`, `.ts`, `.tsx`, `.scala`, `.sc`, `.json`, `.yaml`, `.yml`, `.toml`, `.md`- Graph navigation: search, explain, callers/callees, imports/imported-by, contains, depends+- High-level workflow: impact analysis, hotspot ranking, one-shot overviews, scoped inventory- Decision and intent tracking: `ix decide`, `ix decisions`, `ix truth ...`- Provenance + history: `ix patches`, `ix history`, `ix diff`, `ix conflicts`- GitHub ingestion: `ix ingest --github owner/repo` (issues/PRs/commits/comments)@@ -81,8 +82,13 @@ ix ingest ./src --recursiveAll commands support `--format json`.```bash-ix status-ix ingest ./src --recursive+# Start with high-level workflow commands+ix overview UserService # one-shot summary+ix impact UserService # what depends on it+ix rank --by dependents --kind class --top 10 # most important classes+ix inventory --kind function --path "src/" # list functions++# Low-level primitives for fine-grained inspectionix search IngestionService --kind class --format jsonix explain IngestionService --format jsonix callers parseFile --format json