Skip to content

armgit / Ix

Public Imported from GitHub
0

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

docs(readme): simplify dividers and remove em dashes

Joseph Mikhailebf960dda18d
diff --git a/README.md b/README.md
index 2c90c0ff..2ab65c0c 100644
--- a/README.md
+++ b/README.md
@@ -6,7 +6,7 @@
<p align="center"><em>System intelligence for humans and AI.</em></p>
<p align="center">
- Ix parses your repository into a persistent system graph — symbols, calls, imports, relationships —<br/>
+ Ix parses your repository into a persistent system graph of symbols, calls, imports and relationships<br/>
so you and your coding agents can query structure instead of grepping and guessing.
</p>
@@ -24,7 +24,9 @@
<a href="https://discord.gg/ncEYVHVqZ8">Discord</a>
</p>
-## Kartr
+---
+
+### Kartr
**[Kartr](https://www.ix-infra.com)** is an agent platform built on the same memory
engine we use for Ix, extended to the sources a codebase does not contain: docs and
@@ -41,7 +43,7 @@ Kartr is in alpha and onboarding early users.
---
-## Try Ix
+### Try Ix
```bash
curl -fsSL https://ix-infra.com/install.sh | sh # macOS / Linux
@@ -64,7 +66,7 @@ from whatever fits in a prompt.
---
-## Why Ix
+### Why Ix
| | Without Ix | With Ix |
|---|---|---|
@@ -74,25 +76,29 @@ from whatever fits in a prompt.
| **Between sessions** | Context is lost | The graph persists |
| **Relationships** | Inferred from fragments | Read from real edges |
-## The model
+---
+
+### The model
**Map → Structure → Retrieve → Remember**
| Step | What happens |
|---|---|
| **Map** | `ix map .` parses the repo with tree-sitter and extracts symbols, calls and imports. |
-| **Structure** | Those become nodes and edges — a graph of what calls, contains and imports what. |
+| **Structure** | Those become nodes and edges in a graph of what calls, contains and imports what. |
| **Retrieve** | Commands return bounded answers about one symbol or flow, not whole files. |
| **Remember** | The graph is stored locally and survives between sessions and agent runs. |
-## How it works
+---
+
+### How it works
<p align="center">
<img src="./assets/arch.png" width="100%" alt="Ix architecture" />
</p>
`ix map` parses your repository with tree-sitter, extracts symbols, calls and
-imports, and persists them as a graph in a local backend — ArangoDB plus the memory
+imports, and persists them as a graph in a local backend: ArangoDB plus the memory
layer, run for you in Docker. Three clients read that graph: the `ix` CLI, the
`ix mcp` server your AI clients connect to, and Compass, the visualizer `ix view`
opens.
@@ -100,17 +106,21 @@ opens.
The backend ships as a released Docker image; it is not built from this repo. See
the [HTTP API reference](./docs/api/) for the endpoints all three clients share.
-## Results
+---
+
+### Results
Across our own development work, querying the graph instead of feeding files into
the prompt cut token use by **30–99.7%**, varying widely with the task and the size
of the repo. These are internal measurements, not a published benchmark.
The mechanism is the plain part: `ix explain AuthService` returns that symbol and
-its immediate relationships. Answering the same question by reading the file — and
-the files it imports — costs far more, and costs it again next session.
+its immediate relationships. Answering the same question by reading the file and
+the files it imports costs far more, and costs it again next session.
+
+---
-## Integrations
+### Integrations
Ix ships a stdio MCP server, so any MCP-capable client can use the same graph tools.
@@ -122,7 +132,7 @@ ix mcp doctor # check each client's registration
`install` knows **Claude Code, Codex, Cursor, VS Code, Gemini CLI, OpenClaw and
opencode**. It writes through each client's own MCP command where one exists, and
-never overwrites a server name it does not own — pass `--force` to replace one, or
+never overwrites a server name it does not own. Pass `--force` to replace one, or
`--host <id>` to limit the run. Per-client write mechanics, repair and process
isolation are in [docs/mcp.md](./docs/mcp.md).
@@ -132,7 +142,7 @@ To register one client by hand:
codex mcp add ix-memory -- ix mcp
```
-### Agent skill
+#### Agent skill
[`skills/ix/`](skills/ix/SKILL.md) teaches any LLM agent to drive the CLI. It follows the
[Claude Code skill format](https://code.claude.com/docs/en/skills) and the
@@ -145,7 +155,7 @@ bash scripts/install-skill.sh # deploy to every harness found (--dry-run to pr
Then ask your agent: *"Set up Ix and map this repo."*
-### Native plugins
+#### Native plugins
Optional per-client packages, if you prefer them to `ix mcp install`:
@@ -170,10 +180,12 @@ curl -fsSL https://raw.githubusercontent.com/ix-infrastructure/ix-opencode-plugi
curl -fsSL https://raw.githubusercontent.com/ix-infrastructure/ix-cursor-plugin/main/install.sh | bash
```
-Each also publishes a Windows PowerShell installer — swap `install.sh | bash` for
+Each also publishes a Windows PowerShell installer. Swap `install.sh | bash` for
`install.ps1 | iex` via `irm`.
-## Install
+---
+
+### Install
**macOS / Linux**
@@ -181,7 +193,7 @@ Each also publishes a Windows PowerShell installer — swap `install.sh | bash`
curl -fsSL https://ix-infra.com/install.sh | sh
```
-**Windows** — install Node.js 22+ and Docker Desktop first, then:
+**Windows**: install Node.js 22+ and Docker Desktop first, then:
```powershell
irm https://ix-infra.com/install.ps1 | iex
@@ -214,12 +226,14 @@ brew tap ix-infrastructure/ix https://github.com/ix-infrastructure/Ix
brew install ix
```
-For the full list — including the endpoints the installer reaches and the
-directories it creates — see [docs/prerequisites.md](./docs/prerequisites.md).
+For the full list, including the endpoints the installer reaches and the
+directories it creates, see [docs/prerequisites.md](./docs/prerequisites.md).
</details>
-## Commands
+---
+
+### Commands
Ix talks to a local backend, so start there if a command reports
`Ix backend not reachable`:
@@ -271,7 +285,7 @@ ix smells # detect structural issues
```
Query commands take `--format text|json|llm`. Use `llm` when an agent reads the
-output — it is token-minimal and newline-delimited
+output. It is token-minimal and newline-delimited
([spec](./docs/llm-format.md)). Use `json` when chaining commands.
Exhaustive references: **[commands](skills/ix/references/commands.md)** ·
@@ -279,7 +293,9 @@ Exhaustive references: **[commands](skills/ix/references/commands.md)** ·
**[output formats](skills/ix/references/output-formats.md)** ·
**[troubleshooting](skills/ix/references/troubleshooting.md)**
-## Supported languages
+---
+
+### Supported languages
Symbols, calls and imports are extracted across **27 languages**:
@@ -294,14 +310,18 @@ graph. Python stub files (`.pyi`) are parsed as Python.
Also recognized as config and data formats: `YAML` `JSON` `TOML` `SQL`
`Protocol Buffers` `Dockerfile` `Markdown` `LaTeX`
-## Status
+---
+
+### Status
Alpha, and moving quickly. APIs and behavior may change. If you are running Ix on a
large or unusual codebase, we want the bug report.
-## Contributing
+---
+
+### Contributing
-Issues and pull requests are welcome — see [CONTRIBUTING.md](CONTRIBUTING.md) for local
+Issues and pull requests are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for local
setup, and [SECURITY.md](SECURITY.md) to report a vulnerability.
<p align="center">