Understand Quickly

---

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

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
bundle@1	repo-context packers (Repomix, gitingest, codebase-digest, …)	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.

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

Channel	Install
Pages browser + JSON	https://looptech-ai.github.io/understand-quickly/
MCP Registry	io.github.looptech-ai/understand-quickly (listed in https://registry.modelcontextprotocol.io)
npm CLI	npm i -g @looptech-ai/understand-quickly-cli
npm MCP server	npm i -g @looptech-ai/understand-quickly-mcp
PyPI SDK	pip install understand-quickly
GitHub Action	looptech-ai/uq-publish-action@v0.1.0

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:

   {
     "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-06-25
understand-quickly/demo-gitnexus	gitnexus@1	Demo entry: a sample GitNexus graph modeled on its own codebase.	✅ ok	2026-06-25
understand-quickly/demo-understand-anything	understand-anything@1	Demo entry: a hand-built sample knowledge graph in the understand-anything@1 shape.	✅ ok	2026-06-25

Status legend

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

Emoji	Status	Meaning	What to do
🆕	pending	Registered but the registry hasn't synced it yet.	Wait for the next sync (≤24h, or fire repository_dispatch for instant).
✅	ok	Fetched, validated, current.	Use it.
🟡	missing	404 in the last sync. Will keep retrying.	Verify the file exists at the registered URL on the default branch.
⚠️	invalid	Body failed schema validation.	Run npm run validate locally; fix the field that fails.
📦	oversize	Graph exceeds 50 MB; not fetched.	Slim the graph or split it.
🔁	transient_error	Network or 5xx; will retry next sync.	Usually nothing — wait one cycle.
💀	dead	7+ consecutive misses.	Re-publish or open an issue to remove the entry.
↪️	renamed	Superseded by renamed_to.	Update tooling to point at the new id.
🚫	revoked	Maintainer-retracted.	Don't consume; contact maintainers if unexpected.

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

Project	PR
tirth8205/code-review-graph	#449
AsyncFuncAI/deepwiki-open	#517
punkpeye/awesome-mcp-servers	#6148
yamadashy/repomix	#1563
coderamp-labs/gitingest	#577
kamilstanuch/codebase-digest	#7
safishamsi/graphify	#802
The-Pocket/PocketFlow-Tutorial-Codebase-Knowledge	#185
DeusData/codebase-memory-mcp	#332
AIDotNet/OpenDeepWiki	#361

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.