{
"markdown": "\n\n# ๐ง understand-quickly\n\n**A public, machine-readable registry of code-knowledge graphs.**\n\nPoint AI agents at any indexed repo and they get a current, schema-validated graph โ one URL, one fetch.\n\n\n[](https://github.com/looptech-ai/understand-quickly/actions/workflows/sync.yml)\n[](https://looptech-ai.github.io/understand-quickly/)\n[](https://github.com/looptech-ai/understand-quickly/releases)\n[](LICENSE)\n[](DATA-LICENSE.md)\n[](CONTRIBUTING.md)\n[](https://github.com/looptech-ai/understand-quickly/issues)\n[](https://github.com/looptech-ai/understand-quickly/commits/main)\n[](https://scorecard.dev/viewer/?uri=github.com/looptech-ai/understand-quickly)\n\n\n[](https://registry.modelcontextprotocol.io)\n[](https://www.npmjs.com/package/@looptech-ai/understand-quickly-cli)\n[](https://www.npmjs.com/package/@looptech-ai/understand-quickly-mcp)\n[](https://pypi.org/project/understand-quickly/)\n[](https://github.com/marketplace/actions/understand-quickly-publish)\n[](https://www.npmjs.com/package/@looptech-ai/understand-quickly-cli)\n[](https://www.npmjs.com/package/@looptech-ai/understand-quickly-mcp)\n[](https://pypi.org/project/understand-quickly/)\n\n\n> **Latest:** v0.4.0 โ CLI 0.1.3, MCP 0.1.2, Python SDK 0.1.1, GH Action v0.1.0. [CHANGELOG โ](CHANGELOG.md)\n\n\n[**Browse โ**](https://looptech-ai.github.io/understand-quickly/) ยท [**Add your repo (wizard)**](https://looptech-ai.github.io/understand-quickly/add.html) ยท [**Quickstart**](#quickstart) ยท [**FAQ (plain English)**](docs/faq.md) ยท [**Alternatives**](docs/alternatives.md) ยท [**Badge**](docs/badge.md) ยท [**Contributing**](CONTRIBUTING.md)\n\n
\n\n---\n\n## New here? Read this first ๐\n\n**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.\n\nIf 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.\n\n- **No code required to be listed.** Use the [wizard](https://looptech-ai.github.io/understand-quickly/add.html) โ fill four fields, the bot opens the PR.\n- **No infrastructure, no costs.** Graphs stay in your repo; we only store pointers.\n- **Open and public.** Apache 2.0 code; permissive [Data License](DATA-LICENSE.md) for the registry.\n\n> First time? The [FAQ](docs/faq.md) answers \"what is a knowledge graph?\", \"do I need this?\", and \"what happens after I submit?\" in plain language.\n\n---\n\n## Quickstart\n\n### I'm an AI agent / SDK user\n\n```bash\ncurl -fsSL https://looptech-ai.github.io/understand-quickly/registry.json\n```\n\nPick entries with `status: \"ok\"`. Fetch `entry.graph_url`. Cache by `last_sha`. That's the whole API.\n\n### I want to register my repo\n\nPick the path that fits:\n\n- ๐ฑ๏ธ **Wizard:** [Add your repo โ](https://looptech-ai.github.io/understand-quickly/add.html). Fills the issue for you; the bot opens the PR.\n- ๐ป **CLI:** `npx @looptech-ai/understand-quickly-cli add` โ auto-detects everything. ([npm](https://www.npmjs.com/package/@looptech-ai/understand-quickly-cli))\n- โ๏ธ **Manual PR:** see [Add your repo](#add-your-repo) below.\n\n### I want to use it from Claude / Codex / Cursor (MCP)\n\nThree ways, pick whichever your MCP client likes best:\n\n```jsonc\n{\n \"mcpServers\": {\n // 1. Via the MCP Registry โ package name; client resolves it.\n \"understand-quickly\": {\n \"package\": \"io.github.looptech-ai/understand-quickly\"\n },\n\n // 2. Via npm โ install once, run the bin.\n // npm i -g @looptech-ai/understand-quickly-mcp\n \"understand-quickly-npm\": {\n \"command\": \"understand-quickly-mcp\"\n },\n\n // 3. Via tsx โ for hacking on the source in this repo.\n \"understand-quickly-dev\": {\n \"command\": \"npx\",\n \"args\": [\"tsx\", \"/path/to/understand-quickly/mcp/src/index.ts\"]\n }\n }\n}\n```\n\nTools: `list_repos`, `get_graph`, `search_concepts`. See [`mcp/README.md`](mcp/README.md).\n\n### I'm a Python developer\n\n```bash\npip install understand-quickly\n```\n\n```python\nfrom understand_quickly import Registry\nprint(Registry().list(status=\"ok\"))\n```\n\nSee [`python-sdk/README.md`](python-sdk/README.md).\n\n### I'm a developer / contributor\n\n```bash\ngit clone https://github.com/looptech-ai/understand-quickly\ncd understand-quickly\nnpm install && npm test\n```\n\nThen read [`CONTRIBUTING.md`](CONTRIBUTING.md).\n\n---\n\n## How it works\n\n```\n โโโโโโโโโโโโโโโโโโโโโโโโ\n โ looptech-ai/ โ\n โ understand-quickly โ\n โ โ\n โ registry.json โ โ canonical pointers\n โ schemas/ โ โ per-format JSON Schemas\n โ README.md โ โ auto-rendered table\n โโโโโโโโโโฌโโโโโโโโโโโโโโ\n PR / dispatch โ raw.githubusercontent.com\n โ\n โโโโโโโโโโโโโโโโโโโดโโโโโโโโโโโโโโโโโโโโ\n โผ โผ\nโโโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโโโโโ\nโ Source repo with โ โ AI agent / MCP / โ\nโ knowledge graph โ โ human reader โ\nโโโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโโโโโ\n```\n\n- **Storage:** graphs live in source repos. The registry stores only pointers.\n- **Validation:** every PR runs schema checks on `registry.json` and the graph body.\n- **Freshness:** nightly sync resyncs every entry; source repos can opt-in to instant refresh via `repository_dispatch`.\n\n## Supported formats\n\n| Format | Source tool | Tier |\n| --- | --- | --- |\n| `understand-anything@1` | [Understand-Anything](https://github.com/Lum1104/Understand-Anything) | first-class |\n| `gitnexus@1` | [GitNexus](https://github.com/abhigyanpatwari/GitNexus) | first-class |\n| `code-review-graph@1` | [code-review-graph](https://github.com/tirth8205/code-review-graph) | first-class |\n| `bundle@1` | repo-context packers ([Repomix](https://github.com/yamadashy/repomix), [gitingest](https://github.com/cyclotruc/gitingest), [codebase-digest](https://github.com/kamilstanuch/codebase-digest), โฆ) | first-class |\n| `generic@1` | any `{nodes, edges}` graph | fallback |\n\nAdding a new format: PR `schemas/@.json` + an `ok` and `bad` fixture under `schemas/__fixtures__//`. Full instructions in [CONTRIBUTING.md](CONTRIBUTING.md).\n\nUpstream tools that produce these formats can integrate via [the integration protocol](docs/integrations/protocol.md). PR templates are in `docs/integrations/`.\n\n### Integrating an upstream tool\n\nEasiest path: drop the [`looptech-ai/uq-publish-action`](https://github.com/looptech-ai/uq-publish-action) into your release/build workflow.\n\n```yaml\n- uses: looptech-ai/uq-publish-action@v0.1.0\n with:\n graph-path: '.your-tool/graph.json'\n format: 'your-format@1'\n token: ${{ secrets.UNDERSTAND_QUICKLY_TOKEN }}\n```\n\nThe 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`](docs/integrations/protocol.md) for the full producer contract.\n\n### Embed an indexed-by badge\n\nOnce 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`:\n\n```markdown\n[](https://looptech-ai.github.io/understand-quickly/?entry=OWNER/REPO)\n```\n\nThe badge auto-updates as your entry's status changes. See [`docs/badge.md`](docs/badge.md) for the full reference.\n\n### Discovery (`.well-known/code-graph`)\n\nAgents can discover this registry's contents without going through `registry.json`:\n\n```bash\ncurl -fsSL https://looptech-ai.github.io/understand-quickly/.well-known/repos.json\n# returns { schema_version, repos: [{id, format, graph_url, last_synced, status, source_sha}] }\n```\n\nTo 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](docs/spec/code-graph-protocol.md).\n\n## Distribution\n\n| Channel | Install |\n|---|---|\n| Pages browser + JSON | |\n| MCP Registry | `io.github.looptech-ai/understand-quickly` (listed in ) |\n| npm CLI | `npm i -g @looptech-ai/understand-quickly-cli` |\n| npm MCP server | `npm i -g @looptech-ai/understand-quickly-mcp` |\n| PyPI SDK | `pip install understand-quickly` |\n| GitHub Action | `looptech-ai/uq-publish-action@v0.1.0` |\n\nAll 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](DATA-LICENSE.md).\n\n## Add your repo\n\nThe fastest path is the [wizard](https://looptech-ai.github.io/understand-quickly/add.html) or `npx @looptech-ai/understand-quickly-cli add`. The manual flow:\n\n1. Run a [supported tool](#supported-formats) locally and commit its output to your repo.\n2. Fork this repo.\n3. Append an entry to `registry.json`:\n\n ```json\n {\n \"id\": \"you/yourrepo\",\n \"owner\": \"you\",\n \"repo\": \"yourrepo\",\n \"format\": \"understand-anything@1\",\n \"graph_url\": \"https://raw.githubusercontent.com/you/yourrepo/main/.understand-anything/knowledge-graph.json\",\n \"description\": \"one-liner about your project\",\n \"tags\": [\"python\", \"agents\"]\n }\n ```\n\n4. Open a PR. Validation runs automatically.\n\n### Optional: instant refresh on push\n\nDrop [`docs/publish-template.yml`](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.\n\n## Registry\n\n> Auto-generated. Do not hand-edit between the markers.\n\n\n| Repo | Format | Description | Status | Last synced |\n| --- | --- | --- | :---: | --- |\n| [understand-quickly/demo-code-review-graph](https://github.com/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 |\n| [understand-quickly/demo-gitnexus](https://github.com/understand-quickly/demo-gitnexus) | `gitnexus@1` | Demo entry: a sample GitNexus graph modeled on its own codebase. | โ
ok | 2026-06-25 |\n| [understand-quickly/demo-understand-anything](https://github.com/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 |\n\n\n## Status legend\n\nEach entry's `status` field tells consumers whether the linked graph is currently usable.\n\n| Emoji | Status | Meaning | What to do |\n| :---: | --- | --- | --- |\n| ๐ | `pending` | Registered but the registry hasn't synced it yet. | Wait for the next sync (โค24h, or fire `repository_dispatch` for instant). |\n| โ
| `ok` | Fetched, validated, current. | Use it. |\n| ๐ก | `missing` | 404 in the last sync. Will keep retrying. | Verify the file exists at the registered URL on the default branch. |\n| โ ๏ธ | `invalid` | Body failed schema validation. | Run `npm run validate` locally; fix the field that fails. |\n| ๐ฆ | `oversize` | Graph exceeds 50 MB; not fetched. | Slim the graph or split it. |\n| ๐ | `transient_error` | Network or 5xx; will retry next sync. | Usually nothing โ wait one cycle. |\n| ๐ | `dead` | 7+ consecutive misses. | Re-publish or open an issue to remove the entry. |\n| โช๏ธ | `renamed` | Superseded by `renamed_to`. | Update tooling to point at the new id. |\n| ๐ซ | `revoked` | Maintainer-retracted. | Don't consume; contact maintainers if unexpected. |\n\n## Development\n\n```bash\nnvm use # Node 20\nnpm install\nnpm test # node:test\nnpm run test:coverage\nnpm run validate # validate registry.json + graphs\nnpm run sync # resync all entries (writes registry.json)\nnpm run smoke # dry-run sync against tests/registry-smoke.json\nnpm run render # regenerate README table\n```\n\nTest suites at HEAD: 132 root + 25 CLI + 27 MCP + 54 Python SDK + 15 Playwright = **253 tests**.\n\n### Releases\n\nAutomated via [release-please](https://github.com/googleapis/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`](docs/ops/release-process.md) for the full flow, tag prefixes, and rollback recipes.\n\n## Contributing\n\n[`CONTRIBUTING.md`](CONTRIBUTING.md) walks through every contribution flow. Trusted authors can land registry-only PRs without review โ see [`docs/verified-publishers.md`](docs/verified-publishers.md). By participating you agree to the [Code of Conduct](CODE_OF_CONDUCT.md). Security issues: [`SECURITY.md`](SECURITY.md). Security model: see [threat-model](docs/threat-model.md).\n\nFor questions, ideas, or showing off your registered graph: [GitHub Discussions](https://github.com/looptech-ai/understand-quickly/discussions).\n\n## Special thanks\n\nTo the maintainers who carry this protocol upstream.\n\n### Adopters (merged)\n\n- [`abhigyanpatwari/GitNexus`](https://github.com/abhigyanpatwari/GitNexus) โ first project to ship native `gitnexus publish` integration. Thanks to [@magyargergo](https://github.com/magyargergo) for the thorough review and [@abhigyanpatwari](https://github.com/abhigyanpatwari) for the project.\n\n### Integrations in flight\n\n| Project | PR |\n|---|---|\n| [`tirth8205/code-review-graph`](https://github.com/tirth8205/code-review-graph) | [#449](https://github.com/tirth8205/code-review-graph/pull/449) |\n| [`AsyncFuncAI/deepwiki-open`](https://github.com/AsyncFuncAI/deepwiki-open) | [#517](https://github.com/AsyncFuncAI/deepwiki-open/pull/517) |\n| [`punkpeye/awesome-mcp-servers`](https://github.com/punkpeye/awesome-mcp-servers) | [#6148](https://github.com/punkpeye/awesome-mcp-servers/pull/6148) |\n| [`yamadashy/repomix`](https://github.com/yamadashy/repomix) | [#1563](https://github.com/yamadashy/repomix/pull/1563) |\n| [`coderamp-labs/gitingest`](https://github.com/coderamp-labs/gitingest) | [#577](https://github.com/coderamp-labs/gitingest/pull/577) |\n| [`kamilstanuch/codebase-digest`](https://github.com/kamilstanuch/codebase-digest) | [#7](https://github.com/kamilstanuch/codebase-digest/pull/7) |\n| [`safishamsi/graphify`](https://github.com/safishamsi/graphify) | [#802](https://github.com/safishamsi/graphify/pull/802) |\n| [`The-Pocket/PocketFlow-Tutorial-Codebase-Knowledge`](https://github.com/The-Pocket/PocketFlow-Tutorial-Codebase-Knowledge) | [#185](https://github.com/The-Pocket/PocketFlow-Tutorial-Codebase-Knowledge/pull/185) |\n| [`DeusData/codebase-memory-mcp`](https://github.com/DeusData/codebase-memory-mcp) | [#332](https://github.com/DeusData/codebase-memory-mcp/pull/332) |\n| [`AIDotNet/OpenDeepWiki`](https://github.com/AIDotNet/OpenDeepWiki) | [#361](https://github.com/AIDotNet/OpenDeepWiki/pull/361) |\n\n### Upstream tools we build on\n\n- [Understand-Anything](https://github.com/Lum1104/Understand-Anything) โ first-class graph format.\n- [GitNexus](https://github.com/abhigyanpatwari/GitNexus) โ first-class graph format + first adopter.\n- [code-review-graph](https://github.com/tirth8205/code-review-graph) โ first-class graph format.\n- [vis-network](https://github.com/visjs/vis-network) โ graph rendering on the Pages site.\n- [Ajv](https://github.com/ajv-validator/ajv) โ JSON Schema validation.\n\nPRs welcome โ see [CONTRIBUTING.md](CONTRIBUTING.md).\n\n## Star history\n\n[](https://www.star-history.com/#looptech-ai/understand-quickly&Date)\n\n## License\n\n- **Code** โ [Apache License 2.0](LICENSE) ยฉ 2026 Alex Macdonald-Smith and LoopTech.AI. Includes a patent grant and contributor terms.\n- **Registry data** โ [Understand-Quickly Data License 1.0](DATA-LICENSE.md). 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`](DATA-LICENSE.md) for the full terms.\n- **NOTICE** file: [`NOTICE`](NOTICE).\n",
"bytes": 18322,
"sha": "50938afbd491e795463f073476d6192505c62b0d13d4f1bf8ddb538b3cf5d24e",
"repo_slug": "looptech-ai/understand-quickly",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_looptech_ai_understand_quickly_e040ab61/readme"
}