{"id":51714990,"url":"https://github.com/frowningdev/django-orm-lens","last_synced_at":"2026-07-19T04:00:59.091Z","repository":{"id":371028930,"uuid":"1298571736","full_name":"FROWNINGdev/django-orm-lens","owner":"FROWNINGdev","description":"Live sidebar, ER diagrams, CLI, and MCP server for Django models. VS Code + PyPI + MCP Registry + Glama. Zero-dep parser, no DB required.","archived":false,"fork":false,"pushed_at":"2026-07-15T23:21:40.000Z","size":1487,"stargazers_count":3,"open_issues_count":2,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-16T01:28:47.546Z","etag":null,"topics":["ai-agents","aider","code-navigation","cursor","database","developer-tools","django","django-tools","er-diagram","mcp","mcp-server","mermaid","model-context-protocol","orm","python","python-cli","schema-diagram","schema-visualization","static-analysis","vscode-extension"],"latest_commit_sha":null,"homepage":"https://marketplace.visualstudio.com/items?itemName=frowningdev.django-orm-lens","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/FROWNINGdev.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":".github/CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":".github/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":["FROWNINGdev"],"custom":[]}},"created_at":"2026-07-12T19:37:45.000Z","updated_at":"2026-07-15T23:21:41.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/FROWNINGdev/django-orm-lens","commit_stats":null,"previous_names":["frowningdev/django-orm-lens"],"tags_count":28,"template":false,"template_full_name":null,"purl":"pkg:github/FROWNINGdev/django-orm-lens","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FROWNINGdev%2Fdjango-orm-lens","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FROWNINGdev%2Fdjango-orm-lens/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FROWNINGdev%2Fdjango-orm-lens/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FROWNINGdev%2Fdjango-orm-lens/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/FROWNINGdev","download_url":"https://codeload.github.com/FROWNINGdev/django-orm-lens/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FROWNINGdev%2Fdjango-orm-lens/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35563615,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-17T02:00:06.162Z","response_time":116,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","aider","code-navigation","cursor","database","developer-tools","django","django-tools","er-diagram","mcp","mcp-server","mermaid","model-context-protocol","orm","python","python-cli","schema-diagram","schema-visualization","static-analysis","vscode-extension"],"created_at":"2026-07-17T02:00:40.874Z","updated_at":"2026-07-17T02:01:23.491Z","avatar_url":"https://github.com/FROWNINGdev.png","language":"Python","funding_links":["https://github.com/sponsors/FROWNINGdev"],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n\u003cimg src=\"media/hero.png\" alt=\"Django ORM Lens — live sidebar and ER diagram for your Django models\" width=\"100%\"/\u003e\n\n\u003cbr/\u003e\n\u003cbr/\u003e\n\n# Django ORM Lens\n\n### See your entire Django schema — in your editor, in your terminal, and from your AI agent.\n\nEvery app. Every model. Every field. Every relationship. Grouped, navigable, and one keystroke away from a live ER diagram.\n\n\u003cbr/\u003e\n\n[![Install from Marketplace](https://img.shields.io/badge/VS_Code-Install-0c4b33?style=for-the-badge\u0026logo=visualstudiocode\u0026logoColor=white)](https://marketplace.visualstudio.com/items?itemName=frowningdev.django-orm-lens)\n[![PyPI](https://img.shields.io/badge/PyPI-pip_install-3775a9?style=for-the-badge\u0026logo=pypi\u0026logoColor=white)](https://pypi.org/project/django-orm-lens/)\n[![MCP Registry](https://img.shields.io/badge/MCP_Registry-listed-6f42c1?style=for-the-badge)](https://registry.modelcontextprotocol.io/)\n[![Glama](https://img.shields.io/badge/Glama-listed-0f172a?style=for-the-badge)](https://glama.ai/mcp/servers/FROWNINGdev/django-orm-lens)\n[![mcp.so](https://img.shields.io/badge/mcp.so-listed-1f2937?style=for-the-badge)](https://mcp.so/servers/django-orm-lens)\n[![Star on GitHub](https://img.shields.io/badge/★-Star_on_GitHub-24292f?style=for-the-badge\u0026logo=github\u0026logoColor=white)](https://github.com/FROWNINGdev/django-orm-lens)\n[![Sponsor](https://img.shields.io/badge/♥-Sponsor-db61a2?style=for-the-badge\u0026logo=githubsponsors\u0026logoColor=white)](https://github.com/sponsors/FROWNINGdev)\n\n\u003cbr/\u003e\n\n[![Version](https://img.shields.io/visual-studio-marketplace/v/frowningdev.django-orm-lens?color=0c4b33\u0026label=extension\u0026logo=visualstudiocode)](https://marketplace.visualstudio.com/items?itemName=frowningdev.django-orm-lens)\n[![Installs](https://img.shields.io/visual-studio-marketplace/i/frowningdev.django-orm-lens?color=0c4b33\u0026label=installs)](https://marketplace.visualstudio.com/items?itemName=frowningdev.django-orm-lens)\n[![Rating](https://img.shields.io/visual-studio-marketplace/r/frowningdev.django-orm-lens?color=0c4b33\u0026label=rating)](https://marketplace.visualstudio.com/items?itemName=frowningdev.django-orm-lens\u0026ssr=false#review-details)\n[![PyPI version](https://img.shields.io/pypi/v/django-orm-lens?color=3775a9\u0026label=pypi)](https://pypi.org/project/django-orm-lens/)\n[![Python](https://img.shields.io/pypi/pyversions/django-orm-lens?color=3775a9)](https://pypi.org/project/django-orm-lens/)\n[![License MIT](https://img.shields.io/badge/license-MIT-0c4b33?style=flat)](LICENSE)\n[![CI](https://github.com/FROWNINGdev/django-orm-lens/actions/workflows/ci.yml/badge.svg)](https://github.com/FROWNINGdev/django-orm-lens/actions/workflows/ci.yml)\n\n\u003c/div\u003e\n\n---\n\n## 🎯 Pick your path\n\nDjango ORM Lens ships as **three distributions on one core** — pick the one that matches your workflow. Each takes under 60 seconds.\n\n**Editor user (VS Code / Cursor / Windsurf):** install the extension → open any Django project → sidebar tree + ER diagram appear.\n\n```bash\ncode --install-extension frowningdev.django-orm-lens\n```\n\n**Terminal / CI user:** install from PyPI → run `django-orm-lens` in any directory that contains Django apps.\n\n```bash\npip install django-orm-lens\ndjango-orm-lens               # welcome + commands\ndjango-orm-lens scan          # scan cwd for apps and models\n```\n\n**AI coding agent user (Cursor / Aider / Continue / Zed):** install with MCP extras → add one JSON block to your client config.\n\n```bash\npip install \"django-orm-lens[mcp]\"\n```\n\nThen the MCP config snippet in the [Integrations](#-integrations) section below. Point `DJANGO_ORM_LENS_ROOT` at your Django project's absolute path.\n\n---\n\n## 📊 Traction\n\n\u003cdiv align=\"center\"\u003e\n\n\u003c!-- Headline split-badges (dark label · colored value) --\u003e\n\n[![First-week installs](https://img.shields.io/badge/first--week_installs-1082%2B-3775a9?style=for-the-badge\u0026logo=pypi\u0026logoColor=white\u0026labelColor=1e293b)](https://pypi.org/project/django-orm-lens/)\n[![Peak day](https://img.shields.io/badge/peak_day_installs-441-f97316?style=for-the-badge\u0026logo=rocket\u0026logoColor=white\u0026labelColor=1e293b)](https://pypi.org/project/django-orm-lens/)\n[![Unique cloners](https://img.shields.io/badge/unique_cloners_14d-171-24292f?style=for-the-badge\u0026logo=github\u0026logoColor=white\u0026labelColor=1e293b)](https://github.com/FROWNINGdev/django-orm-lens)\n[![VS Code rating](https://img.shields.io/badge/VS_Code_rating-5.0_%E2%98%85-eab308?style=for-the-badge\u0026logo=visualstudiocode\u0026logoColor=white\u0026labelColor=1e293b)](https://marketplace.visualstudio.com/items?itemName=frowningdev.django-orm-lens)\n\n\u003cbr/\u003e\n\n\u003c!-- Cross-platform reach snapshot --\u003e\n\n[![VS Code downloads](https://img.shields.io/badge/VS_Code_downloads-113-0c4b33?style=for-the-badge\u0026logo=visualstudiocode\u0026logoColor=white\u0026labelColor=1e293b)](https://marketplace.visualstudio.com/items?itemName=frowningdev.django-orm-lens)\n[![GitHub views](https://img.shields.io/badge/GitHub_views_14d-256-24292f?style=for-the-badge\u0026logo=github\u0026logoColor=white\u0026labelColor=1e293b)](https://github.com/FROWNINGdev/django-orm-lens)\n[![LinkedIn posts](https://img.shields.io/badge/LinkedIn_posts_live-4-0a66c2?style=for-the-badge\u0026logo=linkedin\u0026logoColor=white\u0026labelColor=1e293b)](https://linkedin.com/company/django-orm-lens)\n[![Awesome-list PRs](https://img.shields.io/badge/awesome--list_PRs-2_pending-16a34a?style=for-the-badge\u0026logo=awesomelists\u0026logoColor=white\u0026labelColor=1e293b)](https://github.com/FROWNINGdev)\n\n\u003cbr/\u003e\n\n\u003c!-- Live counters + directories --\u003e\n\n[![PyPI weekly](https://img.shields.io/pypi/dw/django-orm-lens?style=for-the-badge\u0026logo=pypi\u0026logoColor=white\u0026label=weekly%20downloads\u0026labelColor=1e293b\u0026color=3775a9)](https://pypi.org/project/django-orm-lens/)\n[![PyPI monthly](https://img.shields.io/pypi/dm/django-orm-lens?style=for-the-badge\u0026logo=pypi\u0026logoColor=white\u0026label=monthly%20downloads\u0026labelColor=1e293b\u0026color=3775a9)](https://pypi.org/project/django-orm-lens/)\n[![GitHub stars](https://img.shields.io/github/stars/FROWNINGdev/django-orm-lens?style=for-the-badge\u0026logo=github\u0026logoColor=white\u0026label=stars\u0026labelColor=1e293b\u0026color=eab308)](https://github.com/FROWNINGdev/django-orm-lens/stargazers)\n[![GitHub forks](https://img.shields.io/github/forks/FROWNINGdev/django-orm-lens?style=for-the-badge\u0026logo=github\u0026logoColor=white\u0026label=forks\u0026labelColor=1e293b\u0026color=64748b)](https://github.com/FROWNINGdev/django-orm-lens/network/members)\n\n\u003cbr/\u003e\n\n\u003c!-- MCP directories --\u003e\n\n[![MCP Registry](https://img.shields.io/badge/MCP_Registry-official_listing-6f42c1?style=for-the-badge\u0026labelColor=1e293b)](https://registry.modelcontextprotocol.io/)\n[![Glama.ai](https://img.shields.io/badge/Glama.ai-listed-0f172a?style=for-the-badge\u0026labelColor=1e293b)](https://glama.ai/mcp/servers/FROWNINGdev/django-orm-lens)\n[![mcp.so](https://img.shields.io/badge/mcp.so-listed-1f2937?style=for-the-badge\u0026labelColor=1e293b)](https://mcp.so/servers/django-orm-lens)\n\n\u003cbr/\u003e\n\n\u003c!-- Tech stack + license --\u003e\n\n[![VS Code Marketplace](https://img.shields.io/visual-studio-marketplace/v/frowningdev.django-orm-lens?style=for-the-badge\u0026logo=visualstudiocode\u0026logoColor=white\u0026label=VS%20Code\u0026labelColor=1e293b\u0026color=0c4b33)](https://marketplace.visualstudio.com/items?itemName=frowningdev.django-orm-lens)\n[![PyPI version](https://img.shields.io/pypi/v/django-orm-lens?style=for-the-badge\u0026logo=pypi\u0026logoColor=white\u0026label=PyPI\u0026labelColor=1e293b\u0026color=3775a9)](https://pypi.org/project/django-orm-lens/)\n[![Python](https://img.shields.io/pypi/pyversions/django-orm-lens?style=for-the-badge\u0026logo=python\u0026logoColor=white\u0026label=Python\u0026labelColor=1e293b\u0026color=3775a9)](https://pypi.org/project/django-orm-lens/)\n[![Django](https://img.shields.io/badge/Django-4.0_%E2%80%93_5.1-092e20?style=for-the-badge\u0026logo=django\u0026logoColor=white\u0026labelColor=1e293b)](https://www.djangoproject.com/)\n[![License MIT](https://img.shields.io/badge/license-MIT-16a34a?style=for-the-badge\u0026labelColor=1e293b)](LICENSE)\n\n\u003c/div\u003e\n\n\u003csub\u003e\u003ci\u003eUpdated 2026-07-15. PyPI weekly / monthly, GitHub stars / forks, and PyPI / VS Code version badges auto-refresh live.\u003c/i\u003e\u003c/sub\u003e\n\n\u003e If the tool saves you a `grep` next time you touch a strange Django project — **[star helps others find it](https://github.com/FROWNINGdev/django-orm-lens/stargazers)**.\n\n---\n\n## ⚡ Install\n\n**VS Code / Cursor / Windsurf / any Code fork:**\n\n```bash\ncode --install-extension frowningdev.django-orm-lens\n```\n\nOr search **`Django ORM Lens`** in the Extensions view.\n\n**Terminal \u0026 AI coding agents:**\n\n```bash\npip install django-orm-lens              # CLI only\npip install \"django-orm-lens[mcp]\"       # + MCP server for AI agents\n```\n\nRequires Python 3.9+. Zero runtime dependencies for the CLI.\n\n\u003cbr/\u003e\n\n## 🎯 The problem\n\n\u003e **Works offline. Works on a broken venv. Works on someone else's laptop. Works in CI.**\n\nYou open a Django project. It has 20 apps. You need to answer a simple question:\n\n\u003e _\"Which app owns the `Order` model, and how is it connected to `User`?\"_\n\nToday, that means: `Ctrl+P`, \"models\", scroll through 30 hits, open five files, `Ctrl+F` for `class Order`, read through 400 lines of `ForeignKey('otherapp.Something')` strings, try to remember what you learned two files ago.\n\n**Half a day gone. Every time. On every project.**\n\n\u003cbr/\u003e\n\n## ✨ With Django ORM Lens\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003ctd width=\"50%\" valign=\"top\"\u003e\n\n### 📚 A tree of everything\n\nEvery app → every model → every field → every `Meta` option. Grouped by application, sorted alphabetically, expandable.\n\nIcons distinguish `CharField` from `ForeignKey` from `ManyToManyField` at a glance.\n\n\u003c/td\u003e\n\u003ctd width=\"50%\" valign=\"top\"\u003e\n\n### 🕸️ A live ER diagram\n\nOne command opens a Mermaid entity-relationship diagram of your entire schema. Watch it redraw as you edit. Export to SVG.\n\n`ForeignKey`, `OneToOneField`, and `ManyToManyField` become proper cardinality arrows.\n\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd width=\"50%\" valign=\"top\"\u003e\n\n### 🔎 Hover for relations\n\nHover over `ForeignKey('app.Model')` in any Python file → a card pops up with the target model's fields, relations, and a \"Jump to\" link. No `Ctrl+F`, no file dialog.\n\n\u003c/td\u003e\n\u003ctd width=\"50%\" valign=\"top\"\u003e\n\n### 🧭 Jump-to-definition\n\nClick any field in the tree → cursor lands on the exact line. Filter the tree by app or model name. Split `models/` packages are fully supported.\n\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd width=\"50%\" valign=\"top\"\u003e\n\n### ⚡ Zero configuration\n\nNo `DJANGO_SETTINGS_MODULE`. No `runserver`. Parses `models.py` statically. Works with a broken venv, a missing dependency, or on someone else's laptop.\n\n\u003c/td\u003e\n\u003ctd width=\"50%\" valign=\"top\"\u003e\n\n### 🎨 Native VS Code UI\n\nDark theme. Light theme. Your theme. Follows your icon theme, your font, your key bindings. Nothing garish, nothing branded.\n\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\n\u003cbr/\u003e\n\n## 📸 What it looks like\n\n\u003cdiv align=\"center\"\u003e\n\u003cimg src=\"media/hero.png\" alt=\"Django ORM Lens sidebar showing an app's models with fields, relations, and Meta options\" width=\"90%\"/\u003e\n\u003c/div\u003e\n\n**Also included in the extension:**\n\n- 🕸️ **Live ER diagram** — Mermaid cardinality arrows, edge labels (`CASCADE`, `through Model`, `as related_name`), theme-aware, one-click SVG export\n- 🔎 **Hover cards** — over any `ForeignKey('app.Model')` or `ManyToManyField(...)`, with a one-click jump link\n- 🧭 **CodeLens** — above every `class Model` line: field count, relation count, and an **Open ER diagram** action\n- 🎨 **Named themes** — `auto` / `default` / `dark` / `forest` / `neutral` for the diagram webview\n\n\u003cbr/\u003e\n\n## 🤖 For terminals and AI coding agents\n\nThe same parser that powers the VS Code extension ships as a standalone Python package — with an optional **MCP (Model Context Protocol) server** so any MCP-compatible AI agent can navigate your Django schema without importing Django or booting your app.\n\n### CLI\n\n```bash\ndjango-orm-lens scan -f json          # every app, every model, every field\ndjango-orm-lens describe blog.Post    # one model in Markdown\ndjango-orm-lens hover blog.Post       # compact hover card\ndjango-orm-lens list | fzf            # flat app.Model — pipes anywhere\ndjango-orm-lens er \u003e schema.mmd       # Mermaid ER diagram\n```\n\nEvery command accepts `--path \u003cdir\u003e` and `--exclude \u003cglob\u003e`.\n\n### MCP server\n\nRegister it once with your agent and it exposes five read-only tools:\n\n| Tool | Purpose |\n| --- | --- |\n| `list_apps` | Every Django app in the workspace with model counts |\n| `list_models` | Flat `app.Model` list, optional app filter |\n| `describe_model` | Full field / relation / Meta detail for one model |\n| `find_relations` | Inbound + outbound relations for one model |\n| `er_diagram` | Mermaid `erDiagram` for the whole workspace |\n\n```bash\n# Start it directly\ndjango-orm-lens-mcp\n\n# Or via the CLI subcommand\ndjango-orm-lens mcp\n```\n\nSet `DJANGO_ORM_LENS_ROOT=/abs/path/to/project` to point it anywhere.\n\n\u003cbr/\u003e\n\n## 🔌 Integrations\n\n| Client | How to enable | Status |\n|---|---|:-:|\n| **VS Code** | `code --install-extension frowningdev.django-orm-lens` | ✅ |\n| **Cursor** | same VSIX + optional MCP entry in `~/.cursor/mcp.json` | ✅ |\n| **Windsurf / VSCodium / any Code fork** | install the VSIX from the [Marketplace](https://marketplace.visualstudio.com/items?itemName=frowningdev.django-orm-lens) or [GitHub Releases](https://github.com/FROWNINGdev/django-orm-lens/releases) | ✅ |\n| **Aider** | add `django-orm-lens-mcp` to your `mcp.json` | ✅ (via MCP) |\n| **Continue.dev** | register the MCP server in `~/.continue/config.json` | ✅ (via MCP) |\n| **Zed** | register the MCP server in Zed settings | ✅ (via MCP) |\n| **Any MCP-compatible client** | point `command` at `django-orm-lens-mcp`, set `DJANGO_ORM_LENS_ROOT` | ✅ |\n| **Discoverable via [MCP Registry](https://registry.modelcontextprotocol.io/)** | official Model Context Protocol server directory | ✅ |\n| **Plain terminal / CI** | `pip install django-orm-lens \u0026\u0026 django-orm-lens scan` | ✅ |\n\n### Example: Cursor / any MCP client\n\n```jsonc\n{\n  \"mcpServers\": {\n    \"django-orm-lens\": {\n      \"command\": \"django-orm-lens-mcp\",\n      \"env\": { \"DJANGO_ORM_LENS_ROOT\": \"/abs/path/to/your/project\" }\n    }\n  }\n}\n```\n\n\u003cbr/\u003e\n\n## 🚀 Get started (30 seconds)\n\n**In VS Code:**\n\n1. `code --install-extension frowningdev.django-orm-lens`\n2. Open a folder with a `manage.py` or `models.py`\n3. Click the **Django ORM Lens** icon in the activity bar\n4. Expand apps → models → fields\n5. Click the **type-hierarchy** icon at the top of the panel → ER diagram opens beside your code\n\n**In a terminal:**\n\n```bash\npip install django-orm-lens\ncd my-django-project\ndjango-orm-lens scan -f table\n```\n\n**As an AI agent tool:**\n\n```bash\npip install \"django-orm-lens[mcp]\"\n```\n\n…then register `django-orm-lens-mcp` in your agent's MCP config (see the [Integrations](#-integrations) table above).\n\nNo settings screen. No sign-in. No telemetry.\n\n\u003cbr/\u003e\n\n## 🎯 Who this is for\n\n- **Django developers** joining a codebase with 10+ apps and getting lost in `models.py` sprawl.\n- **Contract / freelance engineers** who need to grasp an unfamiliar Django project in the first hour, not the first week.\n- **Teams onboarding new hires** who want a one-glance schema view without spinning up documentation infrastructure.\n- **AI-agent power users** (Cursor / Aider / Zed / Continue / any MCP-compatible client) who need the agent to answer schema questions accurately — without giving it database credentials or booting Django.\n- **CI pipelines** that verify schema shape (e.g. \"did we accidentally break a `related_name`?\") without importing the project.\n- **Solo indie devs** on a broken venv or someone else's laptop — no `runserver`, no `manage.py migrate`, still works.\n\n\u003cbr/\u003e\n\n## 🗺️ Market position\n\nDjango ORM Lens sits at the intersection of **editor tooling** and **AI-agent tooling** — a slot no existing package covers:\n\n| Segment | Existing option | What it costs you |\n|---|---|---|\n| Boot-and-graph | `django-extensions graph_models` | Requires Graphviz + Django settings + a working DB URL |\n| Web-based viewer | `django-schema-graph` | Requires a running Django server; hosts one more thing to break |\n| Admin panel | Django Admin | Requires runserver + auth + database — great for data, not for architecture |\n| Editor plugin | PyCharm's Django Structure | Locked to PyCharm; no CLI, no AI-agent story |\n| MCP server | (none until now) | AI agents guess your schema from source, imperfectly |\n\n**Django ORM Lens is the only tool that ships three surfaces from one parser:** a VS Code extension (any Code fork), a zero-dep CLI (terminals + CI), and an MCP server (AI agents). All static. All free. All MIT.\n\n\u003cbr/\u003e\n\n## 🤔 How is this different?\n\n| | **Django ORM Lens** | `django-extensions graph_models` | `django-schema-graph` | Django Admin | PyCharm Django Structure |\n|---|:-:|:-:|:-:|:-:|:-:|\n| Works without a bootable Django project | ✅ | ❌ | ❌ | ❌ | ⚠️ |\n| Zero-install (no graphviz, no server) | ✅ | ❌ | ❌ | ❌ | ❌ (needs PyCharm) |\n| Works in VS Code / Cursor / any Code fork | ✅ | ❌ | ❌ | ❌ | ❌ |\n| Sidebar tree inside the editor | ✅ | ❌ | ❌ | ❌ | ✅ |\n| Live ER diagram | ✅ | ✅ | ✅ | ❌ | ❌ |\n| Hover cards on `ForeignKey` | ✅ | ❌ | ❌ | ❌ | ⚠️ |\n| CodeLens on model classes | ✅ | ❌ | ❌ | ❌ | ❌ |\n| Split `models/` package support | ✅ | ⚠️ | ⚠️ | ✅ | ✅ |\n| CLI for terminal / CI | ✅ | ⚠️ | ❌ | ❌ | ❌ |\n| MCP server for AI agents | ✅ | ❌ | ❌ | ❌ | ❌ |\n| Discoverable in the [MCP Registry](https://registry.modelcontextprotocol.io/) | ✅ | ❌ | ❌ | ❌ | ❌ |\n| Free \u0026 open-source (MIT) | ✅ | ✅ | ✅ | ✅ | ❌ (paid IDE) |\n| Django version support | **4.0 – 5.2** | latest | 3.2 – 4.1 (stale since 2023) | latest | latest |\n\n\u003e *`django-schema-graph` has not been updated since 2023-05 and does not test Django 5.x.*\n\n\u003cbr/\u003e\n\n## ⚙️ Configuration\n\nThe defaults are opinionated and sensible. If you need to tweak:\n\n```jsonc\n// .vscode/settings.json\n{\n  \"djangoOrmLens.excludeGlobs\": [\n    \"**/migrations/**\",\n    \"**/node_modules/**\",\n    \"**/venv/**\",\n    \"**/.venv/**\",\n    \"**/env/**\"\n  ],\n  \"djangoOrmLens.autoRefresh\": true\n}\n```\n\n| Setting | Type | Default | What it does |\n|---|---|---|---|\n| `djangoOrmLens.excludeGlobs` | `string[]` | See above | Glob patterns to skip when scanning |\n| `djangoOrmLens.autoRefresh` | `boolean` | `true` | Rescan on `models.py` changes |\n\n\u003cbr/\u003e\n\n## 🧭 Commands\n\nOpen the command palette (`Ctrl+Shift+P` / `Cmd+Shift+P`) and type \"Django ORM Lens\":\n\n| Command | What it does |\n|---|---|\n| `Django ORM Lens: Refresh` | Force-rescan the workspace |\n| `Django ORM Lens: Show ER Diagram` | Open the Mermaid ER diagram side-by-side |\n| `Django ORM Lens: Filter Models` | Filter the tree by app / model / field name |\n| `Django ORM Lens: Clear Filter` | Restore the full tree |\n| `Django ORM Lens: Jump to Model` | Programmatic — triggered by tree clicks and hover cards |\n\n\u003cbr/\u003e\n\n## 🗺️ Roadmap\n\n**Shipped**\n\n- [x] Sidebar tree grouped by app\n- [x] Live Mermaid ER diagram\n- [x] Hover cards over `ForeignKey('app.Model')`\n- [x] Filter tree by name\n- [x] Split `models/` package support\n- [x] Export ER diagram as SVG\n- [x] Python CLI + MCP server for terminals and AI agents\n- [x] Welcome view for empty workspaces\n- [x] Path-safe jump-to-definition and sanitized hover markdown\n- [x] **v0.3.0** — CodeLens above each model class (`N fields · N relations · Open ER diagram`)\n- [x] **v0.3.0** — Edge labels on the diagram (`CASCADE`, `SET_NULL`, `PROTECT`, `related_name`)\n- [x] **v0.3.0** — Named color themes (`auto` / `default` / `dark` / `forest` / `neutral`)\n- [x] **v0.3.1** — `through_model` on M2M edges (contributed by [@kingrubic](https://github.com/kingrubic))\n- [x] **v0.3.1** — Listed in the [official MCP Registry](https://registry.modelcontextprotocol.io/) + [Glama.ai](https://glama.ai/mcp/servers/FROWNINGdev/django-orm-lens)\n\n**Next**\n\n- [ ] Zoom + minimap + auto-layout inside the webview ([#4](https://github.com/FROWNINGdev/django-orm-lens/issues/4))\n- [ ] ORM query autocomplete inside `.filter()` / `.exclude()` / `.annotate()` ([#3](https://github.com/FROWNINGdev/django-orm-lens/issues/3))\n- [ ] App / model toggle checkboxes to declutter huge schemas\n\n**Later**\n\n- [ ] Migration dependency graph\n- [ ] Third-party field support (`django-mptt`, `django-taggit`, `django-model-utils`)\n- [ ] JetBrains / PyCharm plugin (if there is demand)\n\nVote by 👍-ing the corresponding [issue](https://github.com/FROWNINGdev/django-orm-lens/issues).\n\n\u003cbr/\u003e\n\n## ❓ FAQ\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eDo you send any of my code to a server?\u003c/b\u003e\u003c/summary\u003e\n\u003cbr/\u003e\nNo. Every byte stays on your machine. The parser is pure TypeScript (extension) or pure Python (CLI). No LLM calls, no telemetry, no analytics, no error reporting. The Mermaid renderer runs inside VS Code's webview sandbox.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eDoes it work with Poetry / uv / conda / no venv at all?\u003c/b\u003e\u003c/summary\u003e\n\u003cbr/\u003e\nYes. The extension reads Python source directly — it does not import Django and does not care what package manager you use. The CLI requires Python 3.9+, but that is it.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eMy models are split across multiple files inside a \u003ccode\u003emodels/\u003c/code\u003e package. Does that work?\u003c/b\u003e\u003c/summary\u003e\n\u003cbr/\u003e\nYes, since v0.2.0. Both the extension and the CLI walk \u003ccode\u003emodels/*.py\u003c/code\u003e alongside classic \u003ccode\u003emodels.py\u003c/code\u003e.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eCan I use it with DRF serializers, Wagtail, Oscar, or third-party base models?\u003c/b\u003e\u003c/summary\u003e\n\u003cbr/\u003e\nAny class that looks like a Django model is picked up: subclasses of \u003ccode\u003emodels.Model\u003c/code\u003e, abstract bases starting with \u003ccode\u003eAbstract\u003c/code\u003e, common mixins ending in \u003ccode\u003eMixin\u003c/code\u003e, and known base names like \u003ccode\u003eTimeStampedModel\u003c/code\u003e or \u003ccode\u003ePolymorphicModel\u003c/code\u003e. Non-model classes (\u003ccode\u003eModelAdmin\u003c/code\u003e, \u003ccode\u003eModelSerializer\u003c/code\u003e, \u003ccode\u003eForm\u003c/code\u003e, \u003ccode\u003eView\u003c/code\u003e, \u003ccode\u003eManager\u003c/code\u003e, …) are filtered out.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eWhich AI agents can use the MCP server?\u003c/b\u003e\u003c/summary\u003e\n\u003cbr/\u003e\nAny MCP-compatible client — Cursor, Aider, Continue.dev, Zed, and any other tool that speaks the protocol. Just point \u003ccode\u003ecommand\u003c/code\u003e at the installed \u003ccode\u003edjango-orm-lens-mcp\u003c/code\u003e binary. See the \u003ca href=\"#-integrations\"\u003eIntegrations\u003c/a\u003e section.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eIs there a JetBrains / PyCharm version?\u003c/b\u003e\u003c/summary\u003e\n\u003cbr/\u003e\nNot yet. PyCharm's Django Structure tool window is already good, so the value delta is smaller. If enough people ask, it becomes worth doing.\n\u003c/details\u003e\n\n\u003cbr/\u003e\n\n## 🆘 Support\n\n- 🐛 **Bug reports** — [GitHub Issues](https://github.com/FROWNINGdev/django-orm-lens/issues) (please include a minimal `models.py` snippet)\n- 💡 **Feature requests / ideas** — [GitHub Discussions](https://github.com/FROWNINGdev/django-orm-lens/discussions)\n- 📝 **Marketplace reviews** — [rate the extension](https://marketplace.visualstudio.com/items?itemName=frowningdev.django-orm-lens\u0026ssr=false#review-details) (the fastest signal that keeps this project moving)\n- 🐍 **PyPI page** — [pypi.org/project/django-orm-lens](https://pypi.org/project/django-orm-lens/)\n- 💚 **Sponsor** — [github.com/sponsors/FROWNINGdev](https://github.com/sponsors/FROWNINGdev)\n\n\u003cbr/\u003e\n\n## 📜 License\n\nMIT © [FROWNINGdev](https://github.com/FROWNINGdev)\n\n\u003cbr/\u003e\n\n\u003cdiv align=\"center\"\u003e\n\n**Made for developers who care about their codebase.**\n\n[Marketplace](https://marketplace.visualstudio.com/items?itemName=frowningdev.django-orm-lens) · [PyPI](https://pypi.org/project/django-orm-lens/) · [GitHub](https://github.com/FROWNINGdev/django-orm-lens) · [Issues](https://github.com/FROWNINGdev/django-orm-lens/issues) · [Discussions](https://github.com/FROWNINGdev/django-orm-lens/discussions) · [Sponsor](https://github.com/sponsors/FROWNINGdev)\n\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffrowningdev%2Fdjango-orm-lens","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffrowningdev%2Fdjango-orm-lens","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffrowningdev%2Fdjango-orm-lens/lists"}