{"id":48963695,"url":"https://github.com/usamaijazmughal/code-diagram","last_synced_at":"2026-04-18T03:02:27.410Z","repository":{"id":351382136,"uuid":"1210786991","full_name":"usamaijazmughal/code-diagram","owner":"usamaijazmughal","description":"An AI skill that reads your actual source code and generates Mermaid diagrams.","archived":false,"fork":false,"pushed_at":"2026-04-15T15:42:30.000Z","size":101,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-15T16:35:23.092Z","etag":null,"topics":["ai-skills","architecture","class-diagram","claude-code","code-analysis","cursor","dart","diagram","flutter","gemini-cli","go","java","kotlin","mermaid","python","rust","sequence-diagram","swift","typescript"],"latest_commit_sha":null,"homepage":"","language":null,"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/usamaijazmughal.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"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}},"created_at":"2026-04-14T18:54:58.000Z","updated_at":"2026-04-15T15:42:34.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/usamaijazmughal/code-diagram","commit_stats":null,"previous_names":["usamaijazmughal/code-diagram-skill","usamaijazmughal/code-diagram"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/usamaijazmughal/code-diagram","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/usamaijazmughal%2Fcode-diagram","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/usamaijazmughal%2Fcode-diagram/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/usamaijazmughal%2Fcode-diagram/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/usamaijazmughal%2Fcode-diagram/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/usamaijazmughal","download_url":"https://codeload.github.com/usamaijazmughal/code-diagram/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/usamaijazmughal%2Fcode-diagram/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31954736,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-18T00:39:45.007Z","status":"online","status_checked_at":"2026-04-18T02:00:07.018Z","response_time":103,"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-skills","architecture","class-diagram","claude-code","code-analysis","cursor","dart","diagram","flutter","gemini-cli","go","java","kotlin","mermaid","python","rust","sequence-diagram","swift","typescript"],"created_at":"2026-04-18T03:02:23.205Z","updated_at":"2026-04-18T03:02:27.403Z","avatar_url":"https://github.com/usamaijazmughal.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# code-diagram\n\n**v1.2.0** | [Changelog](#changelog)\n\n\u003e An AI skill that reads your actual source code and generates Mermaid diagrams.\n\u003e Point it at any directory, file, line range, or multiple targets. It detects the language, paradigm, and produces class, sequence, component, and architecture diagrams.\n\nWorks with **Claude Code** | **Cursor** | **Gemini CLI** | ChatGPT (experimental)\n\n---\n\n## Quick Start\n\n\u003ctable\u003e\n\u003ctr\u003e\u003ctd\u003e\u003cb\u003eClaude Code\u003c/b\u003e\u003c/td\u003e\u003ctd\u003e\n\n```\n/plugin marketplace add usamaijazmughal/code-diagram\n/plugin install code-diagram\n```\nThen: `/code-diagram lib/features/payments`\n\n\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd\u003e\u003cb\u003eCursor\u003c/b\u003e\u003c/td\u003e\u003ctd\u003e\n\n```bash\ncurl -o .cursorrules https://raw.githubusercontent.com/usamaijazmughal/code-diagram/main/cursor/.cursorrules\n```\nThen ask: *\"Analyze lib/features/payments and generate diagrams\"*\n\n\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd\u003e\u003cb\u003eGemini CLI\u003c/b\u003e\u003c/td\u003e\u003ctd\u003e\n\n```bash\nmkdir -p .gemini/commands \u0026\u0026 curl -o .gemini/commands/code-diagram.md https://raw.githubusercontent.com/usamaijazmughal/code-diagram/main/gemini/.gemini/commands/code-diagram.md\n```\nThen: `/code-diagram lib/features/payments`\n\n\u003c/td\u003e\u003c/tr\u003e\n\u003c/table\u003e\n\nRestart your tool after installing. For Claude Code, type `/code-diagram` and it will autocomplete.\n\n---\n\n## Input Modes \u0026 Flags\n\n```bash\n/code-diagram lib/features/payments                      # directory\n/code-diagram lib/auth/bloc.dart                         # single file\n/code-diagram @auth_bloc.dart                            # @ reference\n/code-diagram lib/auth/bloc.dart:10-50 class             # line range\n/code-diagram [lib/auth, lib/payments] sequence           # multiple targets\n/code-diagram lib/app sequence rich                      # show endpoints + operations\n/code-diagram lib/app sequence max                       # shorthand\n/code-diagram lib/app sequence effort=max                # explicit (self-documenting)\n/code-diagram lib/app sequence effort=max rich           # exhaustive + endpoints\n/code-diagram [lib/auth, lib/payments] effort=max        # unlimited per target\n```\n\n| Input mode | When to use |\n|---|---|\n| **Directory** | Analyze a full feature or module |\n| **Single file** | Focus on one file's internals |\n| **Line range** `path:10-50` | Diagram a specific method or class block |\n| **Multi-path** `[a, b, c]` | Compare or connect multiple features |\n| **Pasted code** | Quick diagram from code in your clipboard |\n\n| Flag | What it does | Default |\n|---|---|---|\n| `rich` | Show endpoints, DB entities, operations in diagram labels | Off (method-names only, secure) |\n| `low` | Quick — 10 reads, 5-hop trace | — |\n| `medium` | Default — 20 reads, 12-hop trace | Default |\n| `max` | Exhaustive — no read cap, unlimited trace, no auto-decompose split | — |\n\nAbstract resolution and mixin tracking are **always active** at all effort levels — they are correctness steps, not depth options.\n\n---\n\n## Diagram Types\n\n| Type | Command | What it shows |\n|---|---|---|\n| **Class** | `class` | Classes, interfaces, inheritance, composition, dependency |\n| **Sequence** | `sequence` | Execution flow: entry point through layers to external API |\n| **Component** | `component` | External dependencies: HTTP endpoints, packages, services |\n| **Architecture** | `arch` | Layer boundaries and cross-layer relationships |\n| **All** | `all` (default) | All four diagrams |\n\nEach diagram adapts to the detected paradigm:\n\n| Paradigm | `class` becomes | `sequence` becomes |\n|---|---|---|\n| OOP | Class diagram | Method call chain |\n| Component (React/Vue) | Component tree | Data flow |\n| Functional (Go/Express) | Module map | Call graph |\n\n---\n\n## Flow Modes\n\n| Mode | Behavior | Best for |\n|---|---|---|\n| `full` (default) | One unified diagram per type | Documentation, onboarding |\n| `split` | Multiple focused diagrams | Large features, presentations |\n\n```bash\n/code-diagram lib/app class split    # one diagram per layer\n/code-diagram lib/app sequence split # one diagram per flow\n```\n\n---\n\n## Supported Languages\n\n| Language | Status | Paradigms |\n|---|---|---|\n| Dart / Flutter | Tested | OOP |\n| TypeScript / JavaScript | Tested | OOP, Component, Functional |\n| Java / Kotlin | Tested | OOP |\n| Python | Covered | OOP, Functional |\n| Go | Covered | Functional, Structural |\n| Swift | Covered | OOP |\n| Rust | Covered | Structural, Trait-based |\n| Vue / Angular / Svelte | Covered | Component, Mixed |\n\n**Tested** = validated on production codebases. **Covered** = patterns implemented, community validation welcome.\n\n---\n\n## Scale Handling\n\n| Size | Strategy |\n|---|---|\n| **1 file** | Read directly, focused diagram |\n| **2-49 files** | Full analysis, up to 20 reads (medium effort) |\n| **50-99 files** | Grep-first, happy-path sequence only |\n| **100+ files** | Auto-decompose by subdirectory + integration diagram |\n| **Multi-path** | Per-item budget from effort level, cross-path relationship detection |\n\nUse effort levels to control depth. Default is `medium` (cheap, good for most cases):\n\n```bash\n/code-diagram lib/features/payments max                # unlimited reads, no auto-decompose split\n/code-diagram lib/features/payments effort=max rich    # exhaustive + show endpoints\n/code-diagram [lib/auth, lib/payments] effort=max      # exhaustive per target\n```\n\n---\n\n## How It Works\n\n```\nDiscovery  -\u003e  Paradigm  -\u003e  Grep Scan  -\u003e  Scoring  -\u003e  Reading  -\u003e  Diagrams  -\u003e  Insights\n (Glob)       (3 probes)    (2 passes)    (Tier 1/2/3)  (effort)    (dark theme)   (hotspots)\n```\n\n1. **Glob** all source files, exclude noise (tests, generated, i18n)\n2. **3 grep probes** classify paradigm: OOP / Component / Functional / Mixed\n3. **2 batched grep passes** per language extract classes, relationships, HTTP calls, imports, DI\n4. **Tier scoring** identifies foundational files using structural signals (not naming)\n5. **Selective reading** — only files that grep can't explain (10–20 reads at low/medium, unlimited at `max`). Component + arch diagrams need **zero reads**\n6. **Mermaid output** with dark theme, 30-node cap, `rect` flow separation\n7. **Insights** — hotspots, violations, external deps, budget usage\n\n---\n\n## Cost Benchmarking\n\nThe skill is designed to minimize token usage. You can verify this yourself.\n\n### Test matrix\n\nRun these on the same directory, from cheapest to most expensive:\n\n```bash\n/code-diagram lib/features/payments component          # zero reads (grep only)\n/code-diagram lib/features/payments arch               # zero reads (grep only)\n/code-diagram lib/features/payments class              # 3-8 reads\n/code-diagram lib/features/payments sequence           # 5-12 reads\n/code-diagram lib/features/payments all                # 8-18 reads\n/code-diagram lib/features/payments all rich           # same reads, richer labels\n/code-diagram lib/features/payments all effort=max     # exhaustive\n/code-diagram lib/features/payments all max rich       # exhaustive + endpoints\n```\n\n### Expected read counts\n\n| Diagram type | Expected reads | If higher, investigate |\n|---|---|---|\n| `component` | **0** | Any reads = wasted |\n| `arch` | **0** | Any reads = wasted |\n| `class` | 3–8 | Above 10 = over-reading |\n| `sequence` | 5–12 | Above 15 = reading sideways |\n| `all` (medium) | 10–18 | Above 20 = budget pressure at medium effort |\n\n### Where to find cost data\n\nEvery run reports read budget usage in the **Insights** section at the end:\n```\nRead budget usage: 14 of 20 reads used (medium effort)\n```\n\n### Red flags\n\n- `component` or `arch` triggering file reads (should be zero)\n- Sequence chain reading sibling files not in the call chain\n- Hitting the budget cap (20 at medium) on a feature under 30 files\n- `rich` flag increasing read count (it shouldn't — `rich` only changes labels, not reads)\n- `medium` effort using more than 20 reads\n- Abstract classes not being resolved to concrete (DI binding should be checked at all levels)\n\n---\n\n## Updating\n\n### Claude Code (marketplace)\n\n```\n/plugin update code-diagram\n```\n\n### Claude Code (manual install)\n\n```bash\ncurl -o ~/.claude/skills/code-diagram/SKILL.md \\\n  https://raw.githubusercontent.com/usamaijazmughal/code-diagram/main/skills/code-diagram/SKILL.md\n```\nRestart Claude Code after updating.\n\n### Cursor\n\n```bash\ncurl -o .cursorrules \\\n  https://raw.githubusercontent.com/usamaijazmughal/code-diagram/main/cursor/.cursorrules\n```\n\n### Gemini CLI\n\n```bash\ncurl -o .gemini/commands/code-diagram.md \\\n  https://raw.githubusercontent.com/usamaijazmughal/code-diagram/main/gemini/.gemini/commands/code-diagram.md\n```\n\n### Check version\n\nThe version is in the plugin metadata:\n- **Claude Code:** Check `plugins/code-diagram/.claude-plugin/plugin.json` or `.claude-plugin/marketplace.json`\n- **All tools:** Compare your local file with the [latest on GitHub](https://github.com/usamaijazmughal/code-diagram/blob/main/plugins/code-diagram/.claude-plugin/plugin.json)\n\nCurrent version: **1.2.0**\n\n---\n\n## Where to Render Diagrams\n\n| Renderer | How |\n|---|---|\n| [mermaid.live](https://mermaid.live) | Paste and render instantly |\n| **GitHub** | Paste in any `.md` file, PR, or issue |\n| **GitLab** | Native Mermaid in markdown |\n| **Notion** | Code block with `mermaid` language |\n| **VS Code** | Install Mermaid preview extension |\n\n---\n\n## FAQ\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eDoes it read every file?\u003c/b\u003e\u003c/summary\u003e\nNo. It greps all files (cheap) and only reads the most important files. At default (`medium`): up to 20 reads. At `max`: unlimited but traces only what's in the call chain. Component and architecture diagrams need zero reads.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eWhat if my base classes aren't named \"Base\"?\u003c/b\u003e\u003c/summary\u003e\nThe skill uses structural signals, not naming conventions. A class named \u003ccode\u003ePayments\u003c/code\u003e that 12 files extend outranks \u003ccode\u003eBaseHelper\u003c/code\u003e that nothing extends.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eCan I use it on a monorepo?\u003c/b\u003e\u003c/summary\u003e\nYes, but point at a specific feature directory. Or use multi-path: \u003ccode\u003e[packages/auth, packages/billing]\u003c/code\u003e\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eWhat Mermaid version?\u003c/b\u003e\u003c/summary\u003e\nStandard syntax. \u003ccode\u003erect\u003c/code\u003e blocks need Mermaid 9.3+. Dark theme needs 9+. Avoids \u003ccode\u003enamespace\u003c/code\u003e (10.3+ only).\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eWrong diagram output?\u003c/b\u003e\u003c/summary\u003e\nOpen an issue with: language, paradigm, feature size, and what was wrong.\n\u003c/details\u003e\n\n---\n\n## Repository Structure\n\n```\ncode-diagram/\n  skills/code-diagram/SKILL.md             # Claude Code (manual install)\n  plugins/code-diagram/                     # Claude Code (marketplace install)\n    .claude-plugin/plugin.json\n    skills/code-diagram/SKILL.md\n  cursor/.cursorrules                       # Cursor\n  gemini/.gemini/commands/code-diagram.md   # Gemini CLI\n  chatgpt/SYSTEM_PROMPT.md                  # ChatGPT (experimental)\n  .claude-plugin/marketplace.json           # Marketplace registry\n```\n\n---\n\n## Changelog\n\n### v1.2.0\n- **Simplified effort levels:** `low` (10 reads), `medium` (20 reads, default), `max` (unlimited). Removed `high`.\n- **Abstract resolution + mixin tracking now UNCONDITIONAL** — active at ALL effort levels including default `medium`. No longer gated behind `high`/`max`.\n- **5-step unconditional chain trace:** read → follow → resolve abstracts → resolve mixins → repeat. No conditions, no \"if effort=high\" gates. LLM follows reliably.\n- Effort only controls budget and hop count — quality is always maximum.\n- `high` and `deep` kept as aliases for `max` (backward compatibility).\n- Skill reduced from ~994 to ~920 lines with cleaner, simpler logic.\n\n### v1.1.0\n- **Effort levels:** `low`, `medium` (default), `high`, `max` — replaces `deep` flag\n- `high`/`max`: DI registry resolution (GetIt, Hilt, Spring, NestJS) to follow abstract→concrete\n- `high`/`max`: inheritance search fallback (grep `extends AbstractClass`) when no DI binding found\n- `high`/`max`: mixin/composition tracking (Dart `with`, Kotlin `by`, Python multiple inheritance)\n- `max`: no read cap, unlimited chain trace, no auto-decompose split, full DI graph traversal\n- Unresolvable boundaries explicitly noted in diagrams\n- Universal across all languages (Dart, Java, Kotlin, TypeScript, Python, Go, Swift, Rust)\n- `deep` kept as alias for `high` (backward compatibility)\n\n### v1.0.2\n- Detail level prompt: method names (recommended, secure) vs rich details (opt-in)\n- 9 external operation categories: DB, cache, storage, queue, WebSocket, push, auth, analytics, gRPC\n- Rich mode: full endpoint paths, `READ/WRITE entity` for DB, compact operations for all others\n- Applies to ALL diagram types: sequence, class, component, architecture\n- DB security: never shows query text, columns, or schema in any mode\n- Reference table for sequence diagrams with 15+ steps (rich mode only)\n- 3 batched composite greps (not 9 separate) for cost-effectiveness\n\n### v1.0.1\n- Added 5 input modes: line range, multi-path, pasted code, file validation, @ reference docs\n- Multi-path supports mixed types: `[directory, file, @ref, path:10-50]`\n- Balanced/deep budget prompt for auto-decompose and multi-path\n- Cross-path relationship detection in multi-path mode\n- Phase applicability matrix for all input modes\n- 8 critical/high audit fixes (budget conflicts, regex, parsing, platform sync)\n- Synced all platforms: Cursor, Gemini CLI, ChatGPT\n\n### v1.0.0\n- Initial release: 5-phase pipeline, 4 diagram types, 8 languages, 3 paradigms\n- Dark theme, grep-first strategy, structural scoring, auto-decompose\n- Ported to Claude Code, Cursor, Gemini CLI, ChatGPT\n\n---\n\n## Contributing\n\n1. **Test it** on your codebase (especially Python, Go, Swift, Rust)\n2. **Report issues** with language, paradigm, and feature size\n3. **PRs welcome** for new languages, paradigm patterns, or tool ports\n\n---\n\n## License\n\nMIT\n\n---\n\nBuilt by [Muhammad Usama Ijaz](https://github.com/usamaijazmughal)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fusamaijazmughal%2Fcode-diagram","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fusamaijazmughal%2Fcode-diagram","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fusamaijazmughal%2Fcode-diagram/lists"}