https://github.com/usamaijazmughal/code-diagram
An AI skill that reads your actual source code and generates Mermaid diagrams.
https://github.com/usamaijazmughal/code-diagram
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
Last synced: 2 months ago
JSON representation
An AI skill that reads your actual source code and generates Mermaid diagrams.
- Host: GitHub
- URL: https://github.com/usamaijazmughal/code-diagram
- Owner: usamaijazmughal
- License: mit
- Created: 2026-04-14T18:54:58.000Z (2 months ago)
- Default Branch: main
- Last Pushed: 2026-04-15T15:42:30.000Z (2 months ago)
- Last Synced: 2026-04-15T16:35:23.092Z (2 months ago)
- 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
- Homepage:
- Size: 98.6 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# code-diagram
**v1.2.0** | [Changelog](#changelog)
> An AI skill that reads your actual source code and generates Mermaid diagrams.
> Point it at any directory, file, line range, or multiple targets. It detects the language, paradigm, and produces class, sequence, component, and architecture diagrams.
Works with **Claude Code** | **Cursor** | **Gemini CLI** | ChatGPT (experimental)
---
## Quick Start
Claude Code
```
/plugin marketplace add usamaijazmughal/code-diagram
/plugin install code-diagram
```
Then: `/code-diagram lib/features/payments`
Cursor
```bash
curl -o .cursorrules https://raw.githubusercontent.com/usamaijazmughal/code-diagram/main/cursor/.cursorrules
```
Then ask: *"Analyze lib/features/payments and generate diagrams"*
Gemini CLI
```bash
mkdir -p .gemini/commands && curl -o .gemini/commands/code-diagram.md https://raw.githubusercontent.com/usamaijazmughal/code-diagram/main/gemini/.gemini/commands/code-diagram.md
```
Then: `/code-diagram lib/features/payments`
Restart your tool after installing. For Claude Code, type `/code-diagram` and it will autocomplete.
---
## Input Modes & Flags
```bash
/code-diagram lib/features/payments # directory
/code-diagram lib/auth/bloc.dart # single file
/code-diagram @auth_bloc.dart # @ reference
/code-diagram lib/auth/bloc.dart:10-50 class # line range
/code-diagram [lib/auth, lib/payments] sequence # multiple targets
/code-diagram lib/app sequence rich # show endpoints + operations
/code-diagram lib/app sequence max # shorthand
/code-diagram lib/app sequence effort=max # explicit (self-documenting)
/code-diagram lib/app sequence effort=max rich # exhaustive + endpoints
/code-diagram [lib/auth, lib/payments] effort=max # unlimited per target
```
| Input mode | When to use |
|---|---|
| **Directory** | Analyze a full feature or module |
| **Single file** | Focus on one file's internals |
| **Line range** `path:10-50` | Diagram a specific method or class block |
| **Multi-path** `[a, b, c]` | Compare or connect multiple features |
| **Pasted code** | Quick diagram from code in your clipboard |
| Flag | What it does | Default |
|---|---|---|
| `rich` | Show endpoints, DB entities, operations in diagram labels | Off (method-names only, secure) |
| `low` | Quick — 10 reads, 5-hop trace | — |
| `medium` | Default — 20 reads, 12-hop trace | Default |
| `max` | Exhaustive — no read cap, unlimited trace, no auto-decompose split | — |
Abstract resolution and mixin tracking are **always active** at all effort levels — they are correctness steps, not depth options.
---
## Diagram Types
| Type | Command | What it shows |
|---|---|---|
| **Class** | `class` | Classes, interfaces, inheritance, composition, dependency |
| **Sequence** | `sequence` | Execution flow: entry point through layers to external API |
| **Component** | `component` | External dependencies: HTTP endpoints, packages, services |
| **Architecture** | `arch` | Layer boundaries and cross-layer relationships |
| **All** | `all` (default) | All four diagrams |
Each diagram adapts to the detected paradigm:
| Paradigm | `class` becomes | `sequence` becomes |
|---|---|---|
| OOP | Class diagram | Method call chain |
| Component (React/Vue) | Component tree | Data flow |
| Functional (Go/Express) | Module map | Call graph |
---
## Flow Modes
| Mode | Behavior | Best for |
|---|---|---|
| `full` (default) | One unified diagram per type | Documentation, onboarding |
| `split` | Multiple focused diagrams | Large features, presentations |
```bash
/code-diagram lib/app class split # one diagram per layer
/code-diagram lib/app sequence split # one diagram per flow
```
---
## Supported Languages
| Language | Status | Paradigms |
|---|---|---|
| Dart / Flutter | Tested | OOP |
| TypeScript / JavaScript | Tested | OOP, Component, Functional |
| Java / Kotlin | Tested | OOP |
| Python | Covered | OOP, Functional |
| Go | Covered | Functional, Structural |
| Swift | Covered | OOP |
| Rust | Covered | Structural, Trait-based |
| Vue / Angular / Svelte | Covered | Component, Mixed |
**Tested** = validated on production codebases. **Covered** = patterns implemented, community validation welcome.
---
## Scale Handling
| Size | Strategy |
|---|---|
| **1 file** | Read directly, focused diagram |
| **2-49 files** | Full analysis, up to 20 reads (medium effort) |
| **50-99 files** | Grep-first, happy-path sequence only |
| **100+ files** | Auto-decompose by subdirectory + integration diagram |
| **Multi-path** | Per-item budget from effort level, cross-path relationship detection |
Use effort levels to control depth. Default is `medium` (cheap, good for most cases):
```bash
/code-diagram lib/features/payments max # unlimited reads, no auto-decompose split
/code-diagram lib/features/payments effort=max rich # exhaustive + show endpoints
/code-diagram [lib/auth, lib/payments] effort=max # exhaustive per target
```
---
## How It Works
```
Discovery -> Paradigm -> Grep Scan -> Scoring -> Reading -> Diagrams -> Insights
(Glob) (3 probes) (2 passes) (Tier 1/2/3) (effort) (dark theme) (hotspots)
```
1. **Glob** all source files, exclude noise (tests, generated, i18n)
2. **3 grep probes** classify paradigm: OOP / Component / Functional / Mixed
3. **2 batched grep passes** per language extract classes, relationships, HTTP calls, imports, DI
4. **Tier scoring** identifies foundational files using structural signals (not naming)
5. **Selective reading** — only files that grep can't explain (10–20 reads at low/medium, unlimited at `max`). Component + arch diagrams need **zero reads**
6. **Mermaid output** with dark theme, 30-node cap, `rect` flow separation
7. **Insights** — hotspots, violations, external deps, budget usage
---
## Cost Benchmarking
The skill is designed to minimize token usage. You can verify this yourself.
### Test matrix
Run these on the same directory, from cheapest to most expensive:
```bash
/code-diagram lib/features/payments component # zero reads (grep only)
/code-diagram lib/features/payments arch # zero reads (grep only)
/code-diagram lib/features/payments class # 3-8 reads
/code-diagram lib/features/payments sequence # 5-12 reads
/code-diagram lib/features/payments all # 8-18 reads
/code-diagram lib/features/payments all rich # same reads, richer labels
/code-diagram lib/features/payments all effort=max # exhaustive
/code-diagram lib/features/payments all max rich # exhaustive + endpoints
```
### Expected read counts
| Diagram type | Expected reads | If higher, investigate |
|---|---|---|
| `component` | **0** | Any reads = wasted |
| `arch` | **0** | Any reads = wasted |
| `class` | 3–8 | Above 10 = over-reading |
| `sequence` | 5–12 | Above 15 = reading sideways |
| `all` (medium) | 10–18 | Above 20 = budget pressure at medium effort |
### Where to find cost data
Every run reports read budget usage in the **Insights** section at the end:
```
Read budget usage: 14 of 20 reads used (medium effort)
```
### Red flags
- `component` or `arch` triggering file reads (should be zero)
- Sequence chain reading sibling files not in the call chain
- Hitting the budget cap (20 at medium) on a feature under 30 files
- `rich` flag increasing read count (it shouldn't — `rich` only changes labels, not reads)
- `medium` effort using more than 20 reads
- Abstract classes not being resolved to concrete (DI binding should be checked at all levels)
---
## Updating
### Claude Code (marketplace)
```
/plugin update code-diagram
```
### Claude Code (manual install)
```bash
curl -o ~/.claude/skills/code-diagram/SKILL.md \
https://raw.githubusercontent.com/usamaijazmughal/code-diagram/main/skills/code-diagram/SKILL.md
```
Restart Claude Code after updating.
### Cursor
```bash
curl -o .cursorrules \
https://raw.githubusercontent.com/usamaijazmughal/code-diagram/main/cursor/.cursorrules
```
### Gemini CLI
```bash
curl -o .gemini/commands/code-diagram.md \
https://raw.githubusercontent.com/usamaijazmughal/code-diagram/main/gemini/.gemini/commands/code-diagram.md
```
### Check version
The version is in the plugin metadata:
- **Claude Code:** Check `plugins/code-diagram/.claude-plugin/plugin.json` or `.claude-plugin/marketplace.json`
- **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)
Current version: **1.2.0**
---
## Where to Render Diagrams
| Renderer | How |
|---|---|
| [mermaid.live](https://mermaid.live) | Paste and render instantly |
| **GitHub** | Paste in any `.md` file, PR, or issue |
| **GitLab** | Native Mermaid in markdown |
| **Notion** | Code block with `mermaid` language |
| **VS Code** | Install Mermaid preview extension |
---
## FAQ
Does it read every file?
No. 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.
What if my base classes aren't named "Base"?
The skill uses structural signals, not naming conventions. A class named Payments that 12 files extend outranks BaseHelper that nothing extends.
Can I use it on a monorepo?
Yes, but point at a specific feature directory. Or use multi-path: [packages/auth, packages/billing]
What Mermaid version?
Standard syntax. rect blocks need Mermaid 9.3+. Dark theme needs 9+. Avoids namespace (10.3+ only).
Wrong diagram output?
Open an issue with: language, paradigm, feature size, and what was wrong.
---
## Repository Structure
```
code-diagram/
skills/code-diagram/SKILL.md # Claude Code (manual install)
plugins/code-diagram/ # Claude Code (marketplace install)
.claude-plugin/plugin.json
skills/code-diagram/SKILL.md
cursor/.cursorrules # Cursor
gemini/.gemini/commands/code-diagram.md # Gemini CLI
chatgpt/SYSTEM_PROMPT.md # ChatGPT (experimental)
.claude-plugin/marketplace.json # Marketplace registry
```
---
## Changelog
### v1.2.0
- **Simplified effort levels:** `low` (10 reads), `medium` (20 reads, default), `max` (unlimited). Removed `high`.
- **Abstract resolution + mixin tracking now UNCONDITIONAL** — active at ALL effort levels including default `medium`. No longer gated behind `high`/`max`.
- **5-step unconditional chain trace:** read → follow → resolve abstracts → resolve mixins → repeat. No conditions, no "if effort=high" gates. LLM follows reliably.
- Effort only controls budget and hop count — quality is always maximum.
- `high` and `deep` kept as aliases for `max` (backward compatibility).
- Skill reduced from ~994 to ~920 lines with cleaner, simpler logic.
### v1.1.0
- **Effort levels:** `low`, `medium` (default), `high`, `max` — replaces `deep` flag
- `high`/`max`: DI registry resolution (GetIt, Hilt, Spring, NestJS) to follow abstract→concrete
- `high`/`max`: inheritance search fallback (grep `extends AbstractClass`) when no DI binding found
- `high`/`max`: mixin/composition tracking (Dart `with`, Kotlin `by`, Python multiple inheritance)
- `max`: no read cap, unlimited chain trace, no auto-decompose split, full DI graph traversal
- Unresolvable boundaries explicitly noted in diagrams
- Universal across all languages (Dart, Java, Kotlin, TypeScript, Python, Go, Swift, Rust)
- `deep` kept as alias for `high` (backward compatibility)
### v1.0.2
- Detail level prompt: method names (recommended, secure) vs rich details (opt-in)
- 9 external operation categories: DB, cache, storage, queue, WebSocket, push, auth, analytics, gRPC
- Rich mode: full endpoint paths, `READ/WRITE entity` for DB, compact operations for all others
- Applies to ALL diagram types: sequence, class, component, architecture
- DB security: never shows query text, columns, or schema in any mode
- Reference table for sequence diagrams with 15+ steps (rich mode only)
- 3 batched composite greps (not 9 separate) for cost-effectiveness
### v1.0.1
- Added 5 input modes: line range, multi-path, pasted code, file validation, @ reference docs
- Multi-path supports mixed types: `[directory, file, @ref, path:10-50]`
- Balanced/deep budget prompt for auto-decompose and multi-path
- Cross-path relationship detection in multi-path mode
- Phase applicability matrix for all input modes
- 8 critical/high audit fixes (budget conflicts, regex, parsing, platform sync)
- Synced all platforms: Cursor, Gemini CLI, ChatGPT
### v1.0.0
- Initial release: 5-phase pipeline, 4 diagram types, 8 languages, 3 paradigms
- Dark theme, grep-first strategy, structural scoring, auto-decompose
- Ported to Claude Code, Cursor, Gemini CLI, ChatGPT
---
## Contributing
1. **Test it** on your codebase (especially Python, Go, Swift, Rust)
2. **Report issues** with language, paradigm, and feature size
3. **PRs welcome** for new languages, paradigm patterns, or tool ports
---
## License
MIT
---
Built by [Muhammad Usama Ijaz](https://github.com/usamaijazmughal)