🧠 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:

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

2. Fork this repo.

3. 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"]
   }

4. 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.

License

MIT © 2026 Alex Macdonald-Smith. See LICENSE.