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}] }