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

Latest: v0.4.0 — CLI 0.1.3, MCP 0.1.2, Python SDK 0.1.1, GH Action v0.1.0. CHANGELOG →

Browse → · Add your repo (wizard) · Quickstart · FAQ (plain English) · Alternatives · Badge · Contributing

New here? Read this first 👋

It's a public directory of "map files" for codebases. Each entry points at a JSON file (a knowledge graph or context bundle) that describes a project's structure — files, functions, modules, how they connect — in a shape that AI tools can read in one network request.

If you're a project maintainer, you can add your repo so AI assistants can understand it instantly. If you're an AI agent or tooling developer, you can fetch any indexed graph by URL with no auth and no SDK.

• No code required to be listed. Use the wizard — fill four fields, the bot opens the PR.
• No infrastructure, no costs. Graphs stay in your repo; we only store pointers.
• Open and public. Apache 2.0 code; permissive Data License for the registry.

First time? The FAQ answers "what is a knowledge graph?", "do I need this?", and "what happens after I submit?" in plain language.

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 @looptech-ai/understand-quickly-cli add — auto-detects everything. (npm)
• ✍️ Manual PR: see Add your repo below.

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

Three ways, pick whichever your MCP client likes best:

{
  "mcpServers": {
    // 1. Via the MCP Registry — package name; client resolves it.
    "understand-quickly": {
      "package": "io.github.looptech-ai/understand-quickly"
    },

    // 2. Via npm — install once, run the bin.
    //    npm i -g @looptech-ai/understand-quickly-mcp
    "understand-quickly-npm": {
      "command": "understand-quickly-mcp"
    },

    // 3. Via tsx — for hacking on the source in this repo.
    "understand-quickly-dev": {
      "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 Python developer

pip install understand-quickly

from understand_quickly import Registry
print(Registry().list(status="ok"))

See python-sdk/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

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

Upstream tools that produce these formats can integrate via the integration protocol. PR templates are in docs/integrations/.

Integrating an upstream tool

Easiest path: drop the looptech-ai/uq-publish-action into your release/build workflow.

- uses: looptech-ai/uq-publish-action@v0.1.0
  with:
    graph-path: '.your-tool/graph.json'
    format: 'your-format@1'
    token: ${{ secrets.UNDERSTAND_QUICKLY_TOKEN }}

The Action stamps metadata.{tool, tool_version, generated_at, commit} into the graph and fires a repository_dispatch (event_type=sync-entry) at this registry. See docs/integrations/protocol.md for the full producer contract.

Embed an indexed-by badge

Once registered, link a status badge in your repo's README. Lower-case the owner/repo and replace / with -- — for example looptech-ai/uq-publish-action becomes looptech-ai--uq-publish-action:

[![indexed by understand-quickly](https://looptech-ai.github.io/understand-quickly/badges/OWNER--REPO.svg)](https://looptech-ai.github.io/understand-quickly/?entry=OWNER/REPO)

The badge auto-updates as your entry's status changes. See docs/badge.md for the full reference.

Discovery (.well-known/code-graph)

Agents can discover this registry's contents without going through registry.json:

curl -fsSL https://looptech-ai.github.io/understand-quickly/.well-known/repos.json
# returns { schema_version, repos: [{id, format, graph_url, last_synced, status, source_sha}] }

To make YOUR repo discoverable without registering here, publish a .well-known/code-graph.json at the root of your repo. See the Code-Knowledge-Graph Protocol (CKGP v1) spec.

Distribution

All MIT-or-Apache-2.0 source-licensed. All free to use. The registry data itself is covered by the Understand-Quickly Data License 1.0.

Add your repo

The fastest path is the wizard or npx @looptech-ai/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:

   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.

Status legend

Each entry's status field tells consumers whether the linked graph is currently usable.

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

Test suites at HEAD: 132 root + 25 CLI + 27 MCP + 54 Python SDK + 15 Playwright = 253 tests.

Releases

Automated via release-please. Conventional Commits (feat: / fix:) on main → release-please opens a per-component Release PR → merging the PR tags and publishes the affected component (CLI, MCP, Python SDK). See docs/ops/release-process.md for the full flow, tag prefixes, and rollback recipes.

Contributing

CONTRIBUTING.md walks through every contribution flow. Trusted authors can land registry-only PRs without review — see docs/verified-publishers.md. By participating you agree to the Code of Conduct. Security issues: SECURITY.md. Security model: see threat-model.

For questions, ideas, or showing off your registered graph: GitHub Discussions.

Special thanks

To the maintainers who carry this protocol upstream.

Adopters (merged)

• abhigyanpatwari/GitNexus — first project to ship native gitnexus publish integration. Thanks to @magyargergo for the thorough review and @abhigyanpatwari for the project.

Integrations in flight

Upstream tools we build on

• Understand-Anything — first-class graph format.
• GitNexus — first-class graph format + first adopter.
• code-review-graph — first-class graph format.
• vis-network — graph rendering on the Pages site.
• Ajv — JSON Schema validation.

PRs welcome — see CONTRIBUTING.md.

Star history

License

• Code — Apache License 2.0 © 2026 Alex Macdonald-Smith and LoopTech.AI. Includes a patent grant and contributor terms.
• Registry data — Understand-Quickly Data License 1.0. Anyone can use the registry, including for AI/ML training; in exchange, contributions and submissions grant Alex Macdonald-Smith and LoopTech.AI a perpetual, sublicensable data-use right that travels with any fork or extension. See DATA-LICENSE.md for the full terms.
• NOTICE file: NOTICE.