🧠 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.1.0 + 4 packages live (cli, mcp, pysdk, GH Action). 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

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:

[![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>)

Lower-case the owner/repo and replace / with --. The badge auto-updates as your entry's status changes.

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

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-10
understand-quickly/demo-gitnexus	`gitnexus@1`	Demo entry: a sample GitNexus graph modeled on its own codebase.	✅ ok	2026-05-10
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-10

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

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.

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.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

🧠 understand-quickly

New here? Read this first 👋

Quickstart

I'm an AI agent / SDK user

I want to register my repo

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

I'm a Python developer

I'm a developer / contributor

How it works

Supported formats

Integrating an upstream tool

Embed an indexed-by badge

Discovery (`.well-known/code-graph`)

Distribution

Add your repo

Optional: instant refresh on push

Registry

Status legend

Development

Contributing

License

About

Uh oh!

Releases 4

Packages

Uh oh!

Contributors

Uh oh!

Languages

Name		Name	Last commit message	Last commit date
Latest commit History 55 Commits
.github		.github
cli		cli
docs		docs
mcp		mcp
python-sdk		python-sdk
schemas		schemas
scripts		scripts
site		site
tests		tests
.gitignore		.gitignore
.nvmrc		.nvmrc
CHANGELOG.md		CHANGELOG.md
CODEOWNERS		CODEOWNERS
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
DATA-LICENSE.md		DATA-LICENSE.md
LICENSE		LICENSE
NOTICE		NOTICE
README.md		README.md
SECURITY.md		SECURITY.md
package-lock.json		package-lock.json
package.json		package.json
registry.json		registry.json

Folders and files

Latest commit

History

Repository files navigation

🧠 understand-quickly

New here? Read this first 👋

Quickstart

I'm an AI agent / SDK user

I want to register my repo

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

I'm a Python developer

I'm a developer / contributor

How it works

Supported formats

Integrating an upstream tool

Embed an indexed-by badge

Discovery (.well-known/code-graph)

Distribution

Add your repo

Optional: instant refresh on push

Registry

Status legend

Development

Contributing

License

About

Topics

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 4

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Discovery (`.well-known/code-graph`)

Packages