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 @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)

{
  "mcpServers": {
    "understand-quickly": {
      "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 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.

Add your repo

The fastest path is the wizard or npx @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.

Status legend

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.

License

MIT © 2026 Alex Macdonald-Smith. See LICENSE.