🧠 understand-quickly

A public, machine-readable registry of code-knowledge graphs.

Point AI agents at any indexed repo and they get a current, schema-validated graph — one URL, one fetch.

Browse → · Add your repo (wizard) · Quickstart · Contributing

Quickstart

I'm an AI agent / SDK user

curl -fsSL https://looptech-ai.github.io/understand-quickly/registry.json

Pick entries with status: "ok". Fetch entry.graph_url. Cache by last_sha. That's the whole API.

I want to register my repo

Pick the path that fits:

🖱️ Wizard: Add your repo →. Fills the issue for you; the bot opens the PR.
💻 CLI: npx @understand-quickly/cli add — auto-detects everything.
✍️ Manual PR: see Add your repo below.

I want to use it from Claude / Codex / Cursor (MCP)

{
  "mcpServers": {
    "understand-quickly": {
      "command": "npx",
      "args": ["tsx", "/path/to/understand-quickly/mcp/src/index.ts"]
    }
  }
}

Tools: list_repos, get_graph, search_concepts. See mcp/README.md.

I'm a developer / contributor

git clone https://github.com/looptech-ai/understand-quickly
cd understand-quickly
npm install && npm test

Then read CONTRIBUTING.md.

How it works

                 ┌──────────────────────┐
                 │   looptech-ai/       │
                 │  understand-quickly  │
                 │                      │
                 │  registry.json       │ ← canonical pointers
                 │  schemas/            │ ← per-format JSON Schemas
                 │  README.md           │ ← auto-rendered table
                 └────────┬─────────────┘
            PR / dispatch │ raw.githubusercontent.com
                          │
        ┌─────────────────┴───────────────────┐
        ▼                                     ▼
┌──────────────────┐                  ┌─────────────────────┐
│ Source repo with │                  │ AI agent / MCP /    │
│ knowledge graph  │                  │ human reader        │
└──────────────────┘                  └─────────────────────┘

Storage: graphs live in source repos. The registry stores only pointers.
Validation: every PR runs schema checks on registry.json and the graph body.
Freshness: nightly sync resyncs every entry; source repos can opt-in to instant refresh via repository_dispatch.

Supported formats

Format	Source tool	Tier
`understand-anything@1`	Understand-Anything	first-class
`gitnexus@1`	GitNexus	first-class
`code-review-graph@1`	code-review-graph	first-class
`generic@1`	any `{nodes, edges}` graph	fallback

Adding a new format: PR schemas/<name>@<int>.json + an ok and bad fixture under schemas/__fixtures__/<name>/. Full instructions in CONTRIBUTING.md.

Add your repo

The fastest path is the wizard or npx @understand-quickly/cli add. The manual flow:

Run a supported tool locally and commit its output to your repo.
Fork this repo.

Append an entry to registry.json:

{
  "id": "you/yourrepo",
  "owner": "you",
  "repo": "yourrepo",
  "format": "understand-anything@1",
  "graph_url": "https://raw.githubusercontent.com/you/yourrepo/main/.understand-anything/knowledge-graph.json",
  "description": "one-liner about your project",
  "tags": ["python", "agents"]
}

Open a PR. Validation runs automatically.

Optional: instant refresh on push

Drop docs/publish-template.yml into your repo as .github/workflows/understand-quickly-publish.yml. Add a fine-grained UNDERSTAND_QUICKLY_TOKEN PAT (scoped to repository_dispatch on this registry) to your repo secrets. Every push that touches your graph file triggers an immediate registry sync.

Registry

Auto-generated. Do not hand-edit between the markers.

Repo	Format	Description	Status	Last synced
understand-quickly/demo-code-review-graph	`code-review-graph@1`	Demo entry: a sample code-review-graph export covering files, classes, and tests.	✅ ok	2026-05-07
understand-quickly/demo-gitnexus	`gitnexus@1`	Demo entry: a sample GitNexus graph modeled on its own codebase.	✅ ok	2026-05-07
understand-quickly/demo-understand-anything	`understand-anything@1`	Demo entry: a hand-built sample knowledge graph in the understand-anything@1 shape.	✅ ok	2026-05-07

Status legend

Emoji	Status	Meaning
🆕	`pending`	registered but not yet synced
✅	`ok`	fetched, validated, current
🟡	`missing`	404 in last sync (will retry)
⚠️	`invalid`	body failed schema validation
📦	`oversize`	graph > 50 MB; not fetched
🔁	`transient_error`	network / 5xx; retried
💀	`dead`	7+ consecutive misses
↪️	`renamed`	superseded by `renamed_to`

Development

nvm use            # Node 20
npm install
npm test           # node:test
npm run test:coverage
npm run validate   # validate registry.json + graphs
npm run sync       # resync all entries (writes registry.json)
npm run smoke      # dry-run sync against tests/registry-smoke.json
npm run render     # regenerate README table

Contributing

CONTRIBUTING.md walks through every contribution flow. By participating you agree to the Code of Conduct. Security issues: SECURITY.md.