Skip to content

armgit / Ix

Public Imported from GitHub
0

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

docs: rewrite README with map-first brand voice

Tanner Kocher8cf43ce24b7c
diff --git a/README.md b/README.md
index 45d37c19..a7979682 100644
--- a/README.md
+++ b/README.md
@@ -1,149 +1,155 @@
-# Ix Memory
+# Ix
-Persistent, versioned knowledge graph for codebases. Gives LLM assistants structured memory across conversations.
+Understand any system instantly.
+Your virtual cartographer.
-## Install
+---
-Pick one method. All install the same thing: the `ix` CLI + a local Docker backend.
+Software systems are too complex to understand manually.
-### curl (macOS / Linux)
+Millions of lines of code.
+Hundreds of services.
+Thousands of dependencies.
-```bash
-curl -fsSL https://raw.githubusercontent.com/ix-infrastructure/Ix/main/install.sh | bash
-```
+You shouldn't have to guess how your system works.
-### PowerShell (Windows)
+Ix maps it.
-```powershell
-irm https://raw.githubusercontent.com/ix-infrastructure/Ix/main/install.ps1 | iex
-```
+---
-### Homebrew (macOS / Linux)
+## The Problem
-```bash
-brew tap ix-infrastructure/ix https://github.com/ix-infrastructure/Ix
-brew install ix
-ix docker start
-```
+Understanding a system today means:
-### Prerequisites
+- reading code
+- searching logs
+- asking teammates
+- guessing how things connect
-- **Docker Desktop** — the backend runs as two containers (ArangoDB + Memory Layer). The installer will prompt you if Docker is missing.
+It doesn't scale.
-## Quick Start
+---
-```bash
-# 1. Start the backend
-ix docker start
-
-# 2. Connect a project
-cd ~/my-project
-ix init
-ix map ./src
-
-# 3. Use it
-ix overview MyService
-ix impact MyService
-ix search parseFile --kind function
-ix callers parseFile
-```
+## The Shift
+
+What if you could open a map instead?
-## Managing the Backend
+Ix creates a living map of your system.
+
+A map you can explore.
+A map you can trace.
+A map that evolves as your system evolves.
+
+---
+
+## What Ix Does
+
+Ix turns your system into something you can:
+
+- **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
+
+---
+
+## Demo
```bash
-ix docker start # Start ArangoDB + Memory Layer
-ix docker stop # Stop containers (keeps data)
-ix docker stop --remove-data # Stop and wipe all data
-ix docker status # Health check
-ix docker logs # Tail container logs
-ix docker restart # Restart containers
+ix map .
+ix explain auth-service
+ix trace user_login_flow
+ix impact database.schema
```
-## Commands
+Stop digging through files.
-All commands support `--format json`.
+Open the map instead.
-### Workflow Commands (start here)
+---
+
+## Install
```bash
-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
-ix briefing # session resume
+curl -fsSL https://get.ix.dev | bash
```
-### Code Navigation
+or
```bash
-ix search IngestionService --kind class
-ix explain IngestionService
-ix callers parseFile
-ix callees parseFile
-ix imports IngestionService
-ix imported-by IngestionService
-ix contains IngestionService
-ix depends IngestionService --depth 2
-ix read src/main/scala/ix/memory/Main.scala:1-80
-ix text "commitPatch" --language ts --limit 20
+npm install -g ix
```
-### Planning and Tracking
+---
+
+## Quick Start
+
+Map your system:
```bash
-ix goal create "Support 100k file repos"
-ix plan create "Scale ingestion" --goal <id>
-ix plan task "Batch writes" --plan <id>
-ix task update <id> --status done
-ix decide "Use CONTAINS edge" --rationale "Normalize hierarchy"
-ix bug create "Parser fails on decorators" --severity high
+ix map .
```
-### GitHub Ingestion
+Explore it:
```bash
-ix map --github owner/repo --since 2026-01-01 --limit 50
+ix ask "how does authentication work?"
```
-Auth resolution: `--token <pat>` → `GITHUB_TOKEN` env → `gh auth token`
+---
-## Claude Code Plugin
+## Why It Matters
-Automatically installed if `claude` is in your PATH. To install separately:
+Systems change. Knowledge fades.
-```bash
-curl -fsSL https://raw.githubusercontent.com/ix-infrastructure/Ix/main/ix-plugin/install.sh | bash
-```
+Ix doesn't just map your system — it remembers it.
-What the hooks do:
-- **On search** (Grep/Glob): injects graph-aware results before the native tool runs
-- **On edit** (Write/Edit): auto-ingests changed files to keep the graph current
+Every trace, every flow, every decision becomes part of a persistent system memory.
-## Supported File Types
+So understanding doesn't reset every time.
-`.py`, `.ts`, `.tsx`, `.scala`, `.sc`, `.json`, `.yaml`, `.yml`, `.toml`, `.md`
+It compounds.
-## Uninstall
+---
-```bash
-# macOS / Linux
-curl -fsSL https://raw.githubusercontent.com/ix-infrastructure/Ix/main/uninstall.sh | bash
+## Core Capabilities
-# Windows
-irm https://raw.githubusercontent.com/ix-infrastructure/Ix/main/uninstall.ps1 | iex
+**A living system map**
+Your architecture, always up to date.
-# Homebrew
-brew uninstall ix && brew untap ix-infrastructure/ix
-ix docker stop --remove-data
-```
+**Trace flows instantly**
+Follow how anything moves through your system.
-## Architecture
+**Understand impact**
+See what changes affect before you make them.
-```
-ix CLI (TypeScript) → Memory Layer (Scala/http4s) → ArangoDB
- local Docker :8090 Docker :8529
-```
+**Persistent system memory**
+Knowledge doesn't disappear — it builds over time.
+
+**AI-assisted reasoning**
+Ask questions and explore your system naturally.
+
+---
+
+## CLI
+
+Ix is designed around navigation:
+
+`map` → `explore` → `trace` → `impact` → `understand`
+
+Commands:
+
+- `ix map`
+- `ix trace`
+- `ix impact`
+- `ix explain`
+- `ix ask`
+
+---
+
+## Philosophy
-## License
+Every complex system should have a map.
-This project is licensed under the [Apache License 2.0](LICENSE).
+Ix gives you yours.