Get started

Try it in five minutes

You will clone the repository, look at a bundled example graph as a tree, validate it, and cut a lens out of it. Nothing is installed globally.

You need git and uv. The project requires Python 3.11 or newer; uv fetches it if needed. The example is a small, invented tool (a validator that compares SQL functions in a database with their source files), modelled as 21 nodes and 19 links.

Get the code.

git clone https://github.com/intent-graph/intent_graph.git
cd intent_graph

Look at the example graph as a tree. The first run builds a local environment, which takes a few seconds.

uv run ig-tool tree -g src/examples/validator_graph.json --show-intent

You see the root, five capabilities and fifteen sub-capabilities, each with its intent sentence. Without --show-intent you get the bare structure:

└── ROOT: SQL Function Sync Validator
    ├── DISCOVER: Discovery
    │   ├── DISCOVER.1: Generated Cache Scanning
    │   ├── DISCOVER.2: Source Directory Scanning
    │   └── DISCOVER.3: Fallback Grep Search
    ├── PARSE: Parsing
    …

Check that the graph is well formed. This tests the invariants (tree structure, valid link endpoints) and writes a report.
```
uv run ig-tool validate -g src/examples/validator_graph.json -o report.yaml
```
The summary printed on screen ends with errors: 0 and warnings: 0.
Take a lens on one part. The target is shown in full, the rest at lower detail, within a budget.
```
uv run ig-tool lens build -g src/examples/validator_graph.json -t DISCOVER -b 30 -o lens.yaml
```
Open lens.yaml: every node carries an lod field (skeleton, lean or full), as described in the lens.
Start a graph of your own.
```
uv run ig-tool init -o graph.json --template three-level --name "My Project"
uv run ig-tool tree -g graph.json
```
This creates a root with three placeholder modules. Rename and describe them with the node and link commands; the tools primer has the syntax.

Install it for good. To get ig-tool on your path from any directory, follow the install steps in the repository README; it is the reference for installation and commands. The install is editable, so it points at your checkout: re-run it if you move the folder.

ig-tool keeps a small usage log on your own machine; ig-tool --no-telemetry turns it off (see ig-tool --help).

Then read, in this order

The primers are written for AI agents and humans alike. They are short and implementation-agnostic. Start at the primers index, or go straight in:

Philosophy: the problem, the five axioms, the invariants, the vocabulary.
Semantics: how to read nodes, fields and tree structure, and common misreadings.
Navigation: lenses, levels of detail, viewport operations.
Editing: changing a graph, decomposing nodes, propagating changes.
Tools: the ig-tool command reference.
Workflows: Improve, Distill and Project, and the roles in each.

For the full picture

Project definition: goals, philosophy and vocabulary.
Positioning summary: how IntentGraph relates to prior approaches.
Usage scenarios: starting from scratch, refining, generating code, reverse-engineering.
The worked example, including an Obsidian vault you can open and browse.
Architecture and roadmap.

Companion repository: ai_tooling

ai_tooling holds generic, reusable tooling and knowledge bases for working with AI coding agents: command-line tools for navigating and documenting codebases, a practice for thinking in levels of detail, and guideline knowledge bases an agent can consult mid-task. Several of the knowledge bases are themselves held as IntentGraphs, which makes them a good place to see real graphs.

It is open source: MIT for the code, CC BY 4.0 for the knowledge bases.

Feedback and contributions

Issues are welcome, and are the best way to influence the project: bug reports, questions, use cases, criticism of the formalism. Open an issue.

Please read CONTRIBUTING.md before opening a pull request: a pull request gives its content entirely to the owner. If you cannot agree to that, describe the change in an issue instead.