arch-diagram — Claude Code plugin: diagrams and installation
arch-diagram is a Claude Code plugin that turns a repository, article, PDF, or local project into an animated architecture diagram. Export it as HTML, PNG, MP4, GIF, or Mermaid.
MIT ★ 145 updated 2026-11-08
/plugin marketplace add bassnova42/arch-diagram-skill
/plugin install arch-diagram@arch-diagramWhat arch-diagram does
arch-diagram reads a GitHub repository, article, PDF, or local project and builds an architecture diagram from its structure. The layout can follow layers, a pipeline, a loop, or a tree. Choose from eight visual themes, and watch the trace log record data moving between modules.
A headless Chrome check looks for overlapping elements, text overflow, and obstructed connections, then fixes issues it finds. Export formats include HTML, PNG, and Mermaid. Video and GIF export require ffmpeg; the plugin also needs Node 18 or later and Chrome, Chromium, or Edge.
Install it in Claude Code with the two marketplace commands. In Codex, invoke it with $arch-diagram; the repository also describes npm and manual installation options.
What it helps with
- map a GitHub repository's architecture
- turn a technical article or PDF into a diagram
- export a project diagram as PNG or video
- represent module relationships in Mermaid
Example prompts for the agent
- Create an architecture diagram from
https://github.com/plausible/analyticswith/arch-diagram. - Turn this article into a diagram and export a 30-second video.
- Export the current diagram as Mermaid.
How to install arch-diagram
Plugin marketplace
/plugin marketplace add bassnova42/arch-diagram-skill/plugin install arch-diagram@arch-diagramStep by step, with commands for each platform: Claude Code plugins: marketplaces, installing, and building your own
Questions about arch-diagram
How do I install arch-diagram in Claude Code?
Run /plugin marketplace add bassnova42/arch-diagram-skill, then run /plugin install arch-diagram@arch-diagram.
What does arch-diagram do?
It builds an architecture diagram from a GitHub repository, article, PDF, or local project. Export options include HTML, PNG, MP4, GIF, and Mermaid.
What does arch-diagram need to run?
It requires Node 18 or later and Chrome, Chromium, or Edge. MP4 and GIF export also require ffmpeg.
Source text
SKILL.md · MIT
<p align="center"> <b>简体中文</b> · <a href="docs/README.en.md">English</a> · <a href="docs/README.es.md">Español</a> · <a href="docs/README.ja.md">日本語</a> · <a href="docs/README.ko.md">한국어</a> · <a href="docs/README.th.md">ไทย</a> </p> # RokoAI arch-diagram 架构图 Skill 适用于 **Claude Code** 和 **Codex**。 给它一个 GitHub 仓库、一篇技术文章、一份 PDF 或本地项目,Claude Code 或 Codex 会读懂结构,画出一张架构图。默认是深色"终端蓝图"风格,另有 7 种风格可选(见 [风格](#风格))。连线上有流动的光点,底部的 log 会在模块之间交换数据时实时加一行。 **下面是开源项目 [morluto/rea](https://github.com/morluto/rea) 的架构图,由这个 Skill 读取它的 GitHub 仓库自动生成:**  更多例子(文章、GitHub 仓库、需求文档)见文末的 [示例](#示例)。 ## 能做什么 - **按内容选结构**:分层系统、流水线、带循环的流程、中心辐射、泳道、层级树,不套固定模板。 - **颜色有含义**:元素按种类上色;连线按流向类型(请求、写入、回传、异步……)区分颜色和虚实;分组框表示包含关系。 - **实时 trace log**:光点到达终点时,底部追加一行 `时间 · 类型 · A → B · 说明`。 - **自检**:用无头 Chrome 检查元素重叠、文字溢出、连线穿过方框、标签被遮挡,有问题就改到干净为止。 - **8 种风格**:暗夜终端、晒图蓝图、牛皮纸制图、白板手绘、粗野撞色、荧光终端、柔光卡片、等距沙盘,说一句就能切换。 - **多种输出**: - 可交互的单文件 HTML - PNG(2 倍分辨率) - MP4:默认 20 秒,可指定任意秒数,4 秒一个周期无缝循环 - GIF:一个周期 - Mermaid 流程图 ## 图的语言跟着提示词走 用什么语言提要求,图就是什么语言: - 用**中文**写提示词,图里的标题、说明、标签、log 都是中文 - 用**英文**写,整张图就是英文 - 用**日语**写,内容就都是日文 即使原文或源码是另一种语言也一样。代码里的标识符、路径、命令保持原样。图例、状态标签等界面文字内置了中文、英语、日语、韩语、西班牙语、泰语;其他语言由 Claude 按你的语言写出来。 ## 安装 需要 Node ≥ 18 和 Chrome、Chromium 或 Edge。输出视频和 GIF 还需要 `ffmpeg`(`brew install ffmpeg`)。 **方式一:npm**(最简单) ```bash npx @rokoai/arch-diagram install ``` 会装到 `~/.claude/skills/arch-diagram`。加 `--project` 则装到当前项目的 `.claude/skills/`。更新时再跑一次;卸载用 `npx @rokoai/arch-diagram uninstall`。 装了 Codex 的话(存在 `~/.codex`),会同时装到 `~/.codex/skills/arch-diagram`。只装其中一个,可以加 `--claude` 或 `--codex`。 > 在本仓库的 clone 目录里运行 `npx @rokoai/arch-diagram …` 会报 `arch-diagram: command not found`:npm 会把当前目录当成这个包本身,不会把它的命令加进 PATH。请到仓库外的目录运行,或在仓库里直接用 `node bin/cli.mjs install`(参数相同,如 `--codex`)。 **方式二:插件**。Claude Code 里依次执行: ``` /plugin marketplace add bassnova42/arch-diagram-skill /plugin install arch-diagram@arch-diagram ``` Codex CLI 里: ```bash codex plugin marketplace add bassnova42/arch-diagram-skill codex plugin add arch-diagram@arch-diagram ``` **方式三:手动拷贝** ```bash git clone https://github.com/bassnova42/arch-diagram-skill cp -R arch-diagram-skill/skills/arch-diagram ~/.claude/skills/ cp -R arch-diagram-skill/skills/arch-diagram ~/.codex/skills/ # Codex ``` 装好后重启 Claude Code 或 Codex。 ## 用法 在 Claude Code 或 Codex 里直接说,比如: - `把 https://github.com/plausible/analytics 画成架构图` - `这篇文章画成流程图:<URL>,输出成视频,30 秒` - `把刚才的图输出成图片` / `输出成 mermaid` - 想明确指定用这个 Skill:Claude Code 里输入 `/arch-diagram <仓库或文章地址>`,Codex 里输入 `$arch-diagram <仓库或文章地址>` 图的源文件是 `<slug>.spec.json`,要修改就让 Claude Code 或 Codex 改 spec,再重新生成。也可以用命令行直接操作: ```bash npx @rokoai/arch-diagram build my.spec.json my.html npx @rokoai/arch-diagram check my.html npx @rokoai/arch-diagram export my.html my.png my.mp4 --seconds 30 ``` ## 风格 默认是 **暗夜终端**(`terminal`)风格,另外还有 7 种风格。提要求时说出风格就行,比如 `画成蓝图风格`、`用手绘白板风格`、`换成 3D 等距`;不说就用默认风格。 - **只换外观,不改内容**:同一份 spec,换风格不用动结构、文字和坐标,自检规则也一样。已有的图说一句"换成柔光卡片风格"就能重画。 - **颜色含义不变**:每种风格都有自己的配色,但蓝、青、绿、琥珀、紫这些颜色名在每种风格里都对应同一类元素,图例照样能看懂。 - **所有输出都支持**:HTML、PNG、MP4、GIF 在每种风格下都能导出(Mermaid 由 Mermaid 自己排版,不带风格)。 同一张图(Elephant-Goldfish 示例)的 8 种风格一览: | | | |---|---| | <img src="docs/themes/terminal.jpg" width="420"><br>**暗夜终端(默认)** · `terminal` | <img src="docs/themes/blueprint.jpg" width="420"><br>**晒图蓝图** · `blueprint` | | <img src="docs/themes/drafting.jpg" width="420"><br>**牛皮纸制图** · `drafting` | <img src="docs/themes/whiteboard.jpg" width="420"><br>**白板手绘** · `whiteboard` | | <img src="docs/themes/brutalism.jpg" width="420"><br>**粗野撞色** · `brutalism` | <img src="docs/themes/crt.jpg" width="420"><br>**荧光终端** · `crt` | | <img src="docs/themes/saas.jpg" width="420"><br>**柔光卡片** · `saas` | <img src="docs/themes/isometric.jpg" width="420"><br>**等距沙盘** · `isometric` | 命令行里用 `--theme` 指定,或者在 spec 里写 `"theme": "blueprint"`: ```bash npx @rokoai/arch-diagram build my.spec.json my.html --theme whiteboard ``` 下面逐个介绍新增的 7 种风格,示例都是 [morluto/rea](https://github.com/morluto/rea) 的架构图(和本页顶部那张同一份 spec)。 ### 晒图蓝图 · `blueprint`  - **外观**:深蓝底上画白色墨线,铺着 20px / 100px 两层网格,四周有双线图框。方框四角带对位十字,连线标签用斜体,异步连线是长虚线。颜色换成了浅色调,在蓝底上依然分得清。 - **适合**:系统设计评审、技术方案文档、想要"工程图纸"仪式感的场合。 - **这样说**:`画成蓝图风格` · `蓝图` · `blueprint` [▶ 20 秒视频(MP4)](docs/themes/blueprint.mp4) ### 牛皮纸制图 · `drafting`  - **外观**:米黄色纸张带纸纹,衬线字体,深色墨水线条,四周双线图框。每个组件左上角有编号气泡,方便按编号讲解;连线起点有实心圆点,异步连线是点划线。 - **适合**:打印、导出 PDF、技术手册和论文插图,或者需要"①②③"逐项讲解的场合。 - **这样说**:`工程制图风格` · `技术手册风格` · `图纸风格` [▶ 20 秒视频(MP4)](docs/themes/drafting.mp4) ### 白板手绘 · `whiteboard`  - **外观**:白底,马克笔一样微微抖动的线条,方框用斜线填色,箭头是开口的笔画,标题下面像被荧光笔划过。抖动用固定随机种子生成,每次渲染完全一样,视频也能无缝循环。 - **适合**:头脑风暴、方案早期讨论、给非技术同事讲解、博客配图。 - **这样说**:`手绘风格` · `白板风格` · `画成草图` - **注意**:装了手写字体(霞鹜文楷、手札体、翩翩体等)会更像手写;没装时中文会用系统字体,线条仍然是手绘的。 [▶ 20 秒视频(MP4)](docs/themes/whiteboard.mp4) ### 粗野撞色 · `brutalism`  - **外观**:奶油色底,2px 黑色粗边框加 6px 硬投影,方框用元素颜色大面积填充,粗体字。连线又粗又黑白分明,标签是白底黑框的小牌子,标题压在黑色色块上。 - **适合**:README 首图、社交媒体、演讲幻灯片、海报,需要第一眼就抓住注意力的地方。 - **这样说**:`粗野风格` · `醒目一点` · `海报感` · `撞色` [▶ 20 秒视频(MP4)](docs/themes/brutalism.mp4) ### 荧光终端 · `crt`  - **外观**:黑绿色显像管屏幕,文字和连线带荧光辉光,方框是双线框,整页叠加扫描线和四角暗角,标题前带 `>` 提示符。 - **适合**:安全、逆向、基础设施类主题,复古风分享,视频封面。 - **这样说**:`复古终端` · `CRT 风格` · `荧光绿` [▶ 20 秒视频(MP4)](docs/themes/crt.mp4) ### 柔光卡片 · `saas`  - **外观**:浅灰点阵背景,白色圆角卡片,顶部一条元素颜色的细条,柔和阴影。连线拐角是圆角,标签是胶囊形,异步连线是圆点线。 - **适合**:产品文档、官网、对外介绍,以及浅色文档站(Notion、飞书、语雀等)。 - **这样说**:`简洁浅色风格` · `产品文档风格` · `SaaS 风格` · `卡片风格` [▶ 20 秒视频(MP4)](docs/themes/saas.mp4) ### 等距沙盘 · `isometric`  - **外观**:排好版、自检通过的图整张铺到等距网格地面上,每个方框变成有厚度和投影的立体块;标题、图例和日志保持正立。画布会加宽(约 1.5 倍),而不是把字缩小。 - **适合**:封面图、宣传图、节点不多的系统总览。 - **这样说**:`3D 风格` · `等距` · `立体一点` - **注意**:文字也跟着地面倾斜,节点在 12 个以内效果最好;节点很多时建议换其他风格。 [▶ 20 秒视频(MP4)](docs/themes/isometric.mp4) ## 目录 ``` skills/arch-diagram/ SKILL.md 工作流程:读源 → 选结构 → 布局 → 自检 → 导出 assets/ 渲染引擎、样式、模板;themes/ 下是各风格的样式 scripts/ build / check / export references/ spec 字段说明、视觉风格 examples/ rea(仓库)、plausible(仓库)、elephant-goldfish(文章) bin/cli.mjs npm 命令:install / uninstall / build / check / export ``` ## 示例 ### 1. 对一篇文章做的架构图 来源:Dave Rensin 的文章《Elephants, Goldfish, and the New Golden Age of Software Engineering》 <https://drensin.medium.com/elephants-goldfish-and-the-new-golden-age-of-software-engineering-c33641a48874>  [▶ 完整视频(MP4,30 秒)](docs/examples/elephant-goldfish.mp4) ### 2. 对一个 GitHub 仓库做的架构图 来源:<https://github.com/morluto/rea>  [▶ 完整视频(MP4,20 秒)](docs/examples/rea.mp4) ### 3. 对一份需求文档做的架构图 来源:Ballet 芭蕾动作评分小程序的需求文档(PRD)和代码。这是私有项目,没有公开链接。  [▶ 完整视频(MP4,20 秒)](docs/examples/ballet.mp4) ## License MIT
© bassnova42 · MIT · bassnova42/arch-diagram-skill