qgraphflow

Turn complex code into diagrams you can explore.

Follow the path. Inspect the evidence. Share one offline file.

💡 Inspired by Cocoon-AI/architecture-diagram-generator — thanks to the original author for the idea.

English · 中文 · Русский · Português · 日本語 · Deutsch · Español

Live demo · Client installation · Report an issue · MIT

Nine diagram types: architecture, flowchart, sequence, ER, deployment, class, state, use case and data flow.

QGraphFlow turns source code, schemas, configuration and requirements into interactive software diagrams, with evidence you can inspect and an offline HTML file you can share.

What sets it apart: nine diagram types from one skill, an evidence kind on every relationship and the source line behind each code-backed one, automatic layout, editing in the page, and no network requests from the plugin scripts or the Viewer itself.

npx skills add supermax92/qgraphflow

One command installs the skill for Claude Code, Codex, Cursor and Qoder; the installation guide covers the plugin installations and the other clients.

• Explore: search, zoom and pan; inspect responsibilities and upstream/downstream relationships.

  

• Verify: inspect nodes and edges for source files, lines, symbols and explicitly marked uncertainty.

  

• Edit: unlock the layout, change text and move elements; reset when needed.

  

• Share: open offline HTML or export the complete diagram as SVG / PNG.

  

The top animation shows the architecture, sequence and ER views for 1.5 seconds each (4.5 seconds per loop); the four feature animations run 6.5–8.5 seconds. All of them are recorded from the source-built Viewer on the agent-desk example — fictional business, real code — with English graph and interface text. They are hosted as showcase-v2 Release assets and kept out of Git history and the plugin package, so viewing them needs network access; the generated diagram HTML itself works offline.

Installation guide

You need Node.js 22 or later and a plugin-capable client with model access configured.

Quick install

npx skills add supermax92/qgraphflow

Tested with skills 1.7.0 for Claude Code, Codex, Cursor and Qoder. It asks which clients to install to; -a claude-code names one, and -g installs for your user instead of the current project. The skill installs as q-flow, without the qgraphflow: prefix of the plugin installations below.

To install it as a plugin instead, follow the steps below. Qoder Desktop users can install from the marketplace and skip step 1.

1. Download the plugin

Get the plugin from npmjs.com; no account, login or token is needed. Create a separate directory outside your application project:

mkdir qgraphflow-install
cd qgraphflow-install
npm install qgraphflow --ignore-scripts
cd node_modules/qgraphflow

You are now in the plugin root. Downloading through npm does not automatically install the plugin in your client; continue with step 2. The package also provides the qgraphflow command used in Keep diagrams in sync with code.

Run the following terminal commands from the plugin root containing skills/.

2. Install in your client

Codex App / CLI

Codex CLI must be installed and available in your terminal:

codex plugin marketplace add .
codex plugin add qgraphflow@supermax92

Start a new session, type $, and select qgraphflow:q-flow.

Claude Code

claude plugin marketplace add ./
claude plugin install qgraphflow@supermax92 --scope user

Start a new session and enter /q-flow (or the fully qualified /qgraphflow:q-flow).

Qoder CLI

qodercli plugins install .

Start a new session and select q-flow.

Qoder Desktop

Recommended: Open Settings → Plugins → Marketplace, search for QGraphFlow or 代码图谱可视化, and install the plugin. Start a new session and select q-flow.

For local installation, complete step 1, then open Settings → Plugins → Custom → Import and import the complete plugin root directory. Start a new session and select q-flow.

Cursor

Copy everything in the plugin root, including hidden files, into:

~/.cursor/plugins/local/qgraphflow/

Confirm that .cursor-plugin/plugin.json exists there, reload the window, and find q-flow in Customize. Back up any previous version first; do not mix old and new files.

3. Start using it

Open your project in the client, start a new session, and select the skill. Describe your task using the Quick start examples below. Open the generated HTML in your browser.

Building it yourself? See the source build instructions.

Quick start

These examples use $qgraphflow:q-flow in Codex. If your client shows $q-flow, select that entry instead. For other clients, use the skill entry described above.

Not sure where to begin? Invoke the skill and choose the subject and question when prompted.

$qgraphflow:q-flow

Already have a goal? Say which part to draw and what you want to understand. You do not need to choose a diagram type first.

Example 1: Understand the architecture

$qgraphflow:q-flow Analyze this project and create an architecture diagram in English showing module responsibilities, dependencies and system boundaries.

Useful when joining a project and learning its overall structure.

Example 2: Trace a business flow

$qgraphflow:q-flow Analyze order creation and create a sequence diagram in English showing pricing, stock reservation, payment and order persistence, including failure branches.

Replace order creation and its steps with your project's actual flow. Continue in the same conversation:

$qgraphflow:q-flow Expand stock reservation from the previous diagram into a separate flowchart in English, showing success and failure handling.

Results go under docs/qgraphflow/ by default. Open index.html to explore, edit and export; graph.json retains the graph data. Each view is also written as an SVG (diagram.svg, or diagram-<n>-<type>.svg for several views) that you can embed as an image in a README, pull request or wiki.

After editing in the page, More → Save changes in Chrome or Edge rewrites the page, graph.json and the SVGs in place once you pick the diagram's folder. Other browsers save graph.json only: put it in the folder and regenerate the page and SVGs with npx -y qgraphflow generate docs/qgraphflow/<name>/graph.json docs/qgraphflow/<name> --layout preserve --force.

These commands run the repository example. An installed plugin does not require cloning this repository. With Node.js 22 or later:

git clone https://github.com/supermax92/qgraphflow.git
cd qgraphflow
node skills/q-flow/scripts/validate-graph.mjs examples/showcase/ecommerce.en.graph.json
node skills/q-flow/scripts/generate-viewer.mjs examples/showcase/ecommerce.en.graph.json output/ecommerce-en

Open output/ecommerce-en/index.html in a browser; the nine SVGs sit next to it. Switch views with Diagram types in the top toolbar; saved text and positions survive switching. More → Save changes saves all views as described above. The same pages are online in the live demo.

The prebuilt Viewer needs no dependency installation, API key or backend service. AI-assisted evidence gathering and graph authoring use your chosen client's model service.

Keep diagrams in sync with code

A diagram generated with a repository root records where each component is defined and the line behind each code-backed relationship (a call, a foreign key). Validating it with --repo-root fails when a recorded file is gone, a line range no longer fits, or a recorded symbol has left its lines, and the error names the lines where the symbol is now. Add this job to your CI; it needs no build, login or token: