Skip to content

armgit / Ix

Public Imported from GitHub
0

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

docs: update CLI help text to brand voice and add README v2

Tanner Kocherb2fe9adc8c1f
diff --git a/README.md b/README.md
index 9db84a00..a0b8fc2e 100644
--- a/README.md
+++ b/README.md
@@ -1,161 +1,250 @@
-# Ix
-
-Understand any system instantly.
-Your virtual cartographer.
+<p align="center">
+ <img src="./assets/logo.jpg" width="40%" />
+</p>
+
+<h1 align="center">Understand any system instantly.</h1>
+<p align="center"><em>Your virtual cartographer.</em></p>
+
+<p align="center">
+ <img src="https://img.shields.io/github/stars/ix-infrastructure/IX-Memory" />
+ <img src="https://img.shields.io/github/license/ix-infrastructure/IX-Memory" />
+ <img src="https://img.shields.io/github/actions/workflow/status/ix-infrastructure/IX-Memory/ci.yml?label=tests" />
+ <img src="https://img.shields.io/badge/platform-windows%20%7C%20macOS%20%7C%20linux-lightgrey" />
+</p>
+
+<p align="center">
+ <img src="https://img.shields.io/badge/status-alpha-blue" />
+ <img src="https://img.shields.io/badge/focus-system--intelligence-purple" />
+ <img src="https://img.shields.io/badge/AI-persistent--memory-blueviolet" />
+ <img src="https://img.shields.io/badge/LLMs-Claude%20%7C%20Codex-orange" />
+</p>
+
+<p align="center">
+ <a href="https://www.ix-infra.com">Website</a> ·
+ <a href="https://www.ix-infra.com/docs">Docs</a> ·
+ <a href="https://www.ix-compass.com/">Demo</a>
+</p>
+
+<p align="center">
+ ⭐ Star this repo if you find it useful
+</p>
+
+<br/>
---
-Software systems are too complex to understand manually.
+<br/>
-Millions of lines of code.
-Hundreds of services.
-Thousands of dependencies.
+## Problem
-You shouldn't have to guess how your system works.
+Software systems are too complex to understand.
-Ix maps it.
+You read code.
+You search logs.
+You still guess.
----
+Ix maps your system instead.
-## The Problem
+AI can’t reason about systems.
+LLMs can’t remember them either.
-Understanding a system today means:
+Ix fixes both.
-- reading code
-- searching logs
-- asking teammates
-- guessing how things connect
+## Demo
-It doesn't scale.
+<p align="center">
+ <img src="./assets/demo.gif" width="90%" />
+</p>
----
+Stop digging through files.
+Open the map instead.
-## The Shift
+Ix improves how AI systems reason about your codebase.
-What if you could open a map instead?
+## Results
-Ix creates a living map of your system.
+**30% fewer tokens** on development tasks
+**43% increase in daily LLM usage**
+**Understand systems in minutes, not hours**
-A map you can explore.
-A map you can trace.
-A map that evolves as your system evolves.
+Directed context. More signal. Persistent system memory.
----
+## Install
-## What Ix Does
+```bash
+curl -fsSL https://ix-infra.com/install.sh | sh
+```
-Ix turns your system into something you can:
+## Requirements
-- **Explore** — navigate architecture like a map
-- **Trace** — follow how data and logic flow
-- **Understand** — instantly see how components connect
-- **Analyze impact** — know what changes affect before you make them
-- **Remember** — build persistent system memory over time
+- macOS, Linux, or Windows
+- Git installed
+- Docker (for full functionality)
----
+## Supported Languages
-## Demo
+Ix currently supports:
+
+- TypeScript / JavaScript
+- Python
+- Go
+- Java
+- more coming
+
+(See docs for full list)
+
+## Quick Start
+
+Map your system:
```bash
ix map .
+```
+
+Understand a component:
+
+```bash
ix explain auth-service
+```
+
+Trace a flow:
+
+```bash
ix trace user_login_flow
+```
+
+Analyze impact:
+
+```bash
ix impact database.schema
```
-Stop digging through files.
+Stop guessing. Start navigating.
-Open the map instead.
+Map → Explain → Trace → Impact
----
+## Why Ix
-## Install
+Modern systems are not just complex — they are constantly changing.
-**macOS / Linux**
-```bash
-curl -fsSL https://get.ix.dev | bash
-```
+Every time you switch context, onboard to a new service, or debug a flow, you start from zero.
-**Windows (PowerShell)**
-```powershell
-irm https://raw.githubusercontent.com/ix-infrastructure/Ix/main/install.ps1 | iex
-```
+- knowledge is fragmented across code, logs, and people
+- context is lost between sessions
+- understanding does not persist
-or
+AI doesn’t solve this.
+It amplifies it — reasoning is limited to the current prompt, and memory disappears between interactions.
-```bash
-npm install -g ix
-```
+Ix is built to fix this at the system level.
----
+- builds a structured map of your system
+- captures relationships and flows
+- persists understanding over time
+- gives both humans and AI a shared source of truth
-## Quick Start
+Stop re-learning your system.
+Start navigating it.
-Map your system:
+## Use Cases
-```bash
-ix map .
-```
+Ix is most useful for:
-Explore it:
+- large codebases
+- unfamiliar systems
+- onboarding new engineers
+- debugging complex flows
+- improving LLM-assisted development
-```bash
-ix ask "how does authentication work?"
-```
+## The Shift
----
+Ix turns your system into a living map.
-## Why It Matters
+Not static diagrams.
+Not outdated docs.
-Systems change. Knowledge fades.
+A map you can explore.
+A map you can trace.
+A map that evolves with your system.
-Ix doesn't just map your system — it remembers it.
+With Ix you can:
-Every trace, every flow, every decision becomes part of a persistent system memory.
+- Understand architecture instantly
+- Trace how anything works
+- See impact before making changes
+- Debug systems faster
+- Build persistent system memory over time
-So understanding doesn't reset every time.
+## Built for humans and AI
-It compounds.
+Developers use Ix to explore and understand systems.
----
+LLMs use Ix as persistent system memory.
+
+Instead of guessing from limited context,
+AI can navigate a real system map — with structure, history, and relationships.
+
+The result:
+
+- better reasoning
+- more consistent answers
+- understanding that compounds over time
+
+## Architecture
+<p align="center">
+ <img src="./assets/arch.png" width="100%"/>
+</p>
+
+**How it works:**
+
+1. **Map** — build a system map from code and signals
+2. **Structure** — identify boundaries, flows, and relationships
+3. **Remember** — persist decisions and system knowledge
+4. **Understand** — explore, trace, and analyze with context
## Core Capabilities
-**A living system map**
+**A living system map**
Your architecture, always up to date.
-**Trace flows instantly**
+**Trace flows instantly**
Follow how anything moves through your system.
-**Understand impact**
+**Understand impact**
See what changes affect before you make them.
-**Persistent system memory**
-Knowledge doesn't disappear — it builds over time.
+**Persistent system memory**
+Knowledge builds over time.
-**AI-assisted reasoning**
-Ask questions and explore your system naturally.
+**AI-assisted reasoning**
+Explore systems with both humans and AI.
----
+## Philosophy
+
+Every complex system should have a map.
-## CLI
+Ix gives you yours.
-Ix is designed around navigation:
+LLMs process. Ix remembers.
-`map` → `explore` → `trace` → `impact` → `understand`
+Early stage. Rapidly evolving.
-Commands:
+If you're building complex systems — we'd love your feedback.
-- `ix map`
-- `ix trace`
-- `ix impact`
-- `ix explain`
-- `ix ask`
+## Contributing
----
+We welcome contributions.
-## Philosophy
+If you’re building with Ix or want to improve it:
-Every complex system should have a map.
+- open an issue
+- submit a PR
+- share feedback
-Ix gives you yours.
+Early stage. Moving fast.
+
+## Status
+
+Ix is in early development (alpha).
+
+APIs and behavior may change.
diff --git a/assets/arch.png b/assets/arch.png
new file mode 100644
index 00000000..e25c3b8e
Binary files /dev/null and b/assets/arch.png differ
diff --git a/assets/demo.gif b/assets/demo.gif
new file mode 100644
index 00000000..20029265
Binary files /dev/null and b/assets/demo.gif differ
diff --git a/assets/logo.jpg b/assets/logo.jpg
new file mode 100644
index 00000000..75248f15
Binary files /dev/null and b/assets/logo.jpg differ
diff --git a/assets/logo.png b/assets/logo.png
new file mode 100644
index 00000000..6eabd352
Binary files /dev/null and b/assets/logo.png differ
diff --git a/ix-cli/src/cli/help-text.ts b/ix-cli/src/cli/help-text.ts
index 52c7fd81..5d352395 100644
--- a/ix-cli/src/cli/help-text.ts
+++ b/ix-cli/src/cli/help-text.ts
@@ -1,40 +1,41 @@
import chalk from "chalk";
const OSS_HELP = [
- `${chalk.cyan("ix")} — Code Memory CLI`,
+ `${chalk.cyan("ix")} — System Intelligence CLI`,
``,
chalk.bold(`Start:`),
- ` map [path] Map the architectural hierarchy of a codebase`,
- ` watch Watch files and auto-ingest on change`,
- ` config Show or update configuration`,
+ ` map [path] Map system`,
+ ` watch Watch changes`,
+ ` config Update config`,
``,
chalk.bold(`Understand:`),
- ` search <term> Search the knowledge graph by term`,
- ` locate <symbol> Resolve symbol to definition with context`,
- ` explain <symbol> Explain an entity with history`,
- ` impact <target> Blast-radius / dependency analysis`,
- ` overview <target> One-shot structural summary`,
- ` read <target> Read file content or symbol source code`,
+ ` search <term> Search system`,
+ ` locate <symbol> Find definition`,
+ ` explain <symbol> Explain behavior`,
+ ` impact <target> Analyze impact`,
+ ` overview <target> Summarize structure`,
+ ` read <target> Read source`,
+ ` smells Detect issues`,
``,
chalk.bold(`Explore:`),
- ` trace <symbol> Follow how a symbol connects upstream and downstream`,
- ` inventory List entities by kind`,
- ` rank Hotspot discovery by metric`,
- ` history <entityId> Show entity provenance chain`,
- ` diff <from> <to> Show diff between revisions`,
+ ` trace <symbol> Trace flow`,
+ ` subsystem Explore structure`,
+ ` inventory List components`,
+ ` rank Rank importance`,
+ ` history <target> Show history`,
+ ` diff <from> <to> Compare changes`,
``,
chalk.bold(`System:`),
- ` status Show backend health`,
- ` stats Show graph statistics`,
- ` doctor Check system health`,
- ` docker <action> Manage the IX backend containers`,
- ` reset Wipe all graph data for a clean re-ingest`,
- ` upgrade Upgrade ix CLI and backend to the latest version`,
+ ` status Check status`,
+ ` stats Show stats`,
+ ` doctor Diagnose issues`,
+ ` docker <action> Manage backend`,
+ ` reset Reset map`,
+ ` upgrade Update ix`,
``,
].join("\n");
-const FOOTER = `Use "ix help advanced" for low-level graph commands.
-Use "ix <command> --help" for details on any command.
+const FOOTER = `Use "ix <command> --help" for details.
`;
export function buildHelpText(