Skip to content
Back to search

visual-pass

MarketplaceWorks with Claude CodeGitHub

Claude Code plugin that makes Claude inspect the UI it just built or changed for errors and inconsistencies.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/joezhuo2--visual-pass-skill/badge.svg)](/listings/joezhuo2--visual-pass-skill)

HTML

<a href="/listings/joezhuo2--visual-pass-skill"><img src="/api/listings/joezhuo2--visual-pass-skill/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Pick one. All of them install the same plugin. Auto mode starts off, so the plugin costs nothing until you run `/visual-pass`.

- **npx:** nothing stays installed besides the plugin.

  npx visual-pass

- **npm, global:** installs the `visual-pass` command, which you then run once.

  npm i -g visual-pass
  visual-pass

- **Claude Code plugin marketplace:** run these inside Claude Code.

  /plugin marketplace add joezhuo2/visual-pass-skill
  /plugin install visual-pass@visual-pass

- **Straight from GitHub:** no npm registry needed.

  npx github:joezhuo2/visual-pass-skill

The npx and npm installers run the two marketplace commands for you through the `claude` CLI, so it has to be on your `PATH`.

A pass needs a browser tool in the session: the built-in browser of the Claude desktop app, the Chrome DevTools MCP server, or Claude in Chrome. Without one, Claude says so and stops; it does not install anything.

Updates

claude plugin marketplace update visual-pass
claude plugin update visual-pass@visual-pass

Uninstall

claude plugin uninstall visual-pass@visual-pass

Delete `~/.claude/.visual-pass.json` too if you had turned auto on.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 11 lines
  1. {
  2. "name": "visual-pass",
  3. "owner": { "name": "joezhuo2" },
  4. "plugins": [
  5. {
  6. "name": "visual-pass",
  7. "source": "./",
  8. "description": "Makes Claude visually verify UI work at the lowest token cost. Run a pass with /visual-pass light|full|ultra."
  9. }
  10. ]
  11. }
README.md · README · 245 lines
  1. <h1 align="center">visual-pass</h1>
  2. <p align="center">
  3. <a href="https://www.npmjs.com/package/visual-pass"><img src="https://img.shields.io/npm/v/visual-pass?logo=npm&color=orange" alt="npm version"></a>
  4. <a href="https://www.npmjs.com/package/visual-pass"><img src="https://img.shields.io/npm/dt/visual-pass?logo=npm&color=blue" alt="npm downloads"></a>
  5. <img src="https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-lightgrey" alt="platform: Windows | macOS | Linux">
  6. <a href="https://code.claude.com/docs/en/plugins"><img src="https://img.shields.io/badge/Claude%20Code-plugin-D97757?logo=claude&logoColor=white" alt="Claude Code plugin"></a>
  7. <a href="https://nodejs.org"><img src="https://img.shields.io/badge/Node-18%2B-5FA04E?logo=nodedotjs&logoColor=white" alt="Node 18+"></a>
  8. <a href="LICENSE"><img src="https://img.shields.io/github/license/joezhuo2/visual-pass-skill?color=green" alt="license"></a>
  9. </p>
  10. <p align="center">
  11. <a href="#install">Install</a> •
  12. <a href="#modes">Modes</a> •
  13. <a href="#usage">Usage</a> •
  14. <a href="#how-it-keeps-cost-down">Cost</a> •
  15. <a href="#files">Files</a> •
  16. <a href="#development">Development</a> •
  17. <a href="#contributing">Contributing</a> •
  18. <a href="#license">License</a>
  19. </p>
  20. > visual-pass is a Claude Code plugin that makes Claude look at the UI it
  21. > just changed, for as few tokens as possible. A screenshot costs about
  22. > 1,500 to 2,000 tokens, so Claude runs a small measuring script first. The
  23. > script returns a few lines of text per page state, and Claude screenshots
  24. > only the states it flags plus the ones your diff touched, as half-scale
  25. > crops where it can.
  26. ## Install
  27. Pick one. All of them install the same plugin. Auto mode starts off, so the
  28. plugin costs nothing until you run `/visual-pass`.
  29. - **npx:** nothing stays installed besides the plugin.
  30. ```bash
  31. npx visual-pass
  32. ```
  33. - **npm, global:** installs the `visual-pass` command, which you then run
  34. once.
  35. ```bash
  36. npm i -g visual-pass
  37. ```
  38. ```bash
  39. visual-pass
  40. ```
  41. - **Claude Code plugin marketplace:** run these inside Claude Code.
  42. ```
  43. /plugin marketplace add joezhuo2/visual-pass-skill
  44. /plugin install visual-pass@visual-pass
  45. ```
  46. - **Straight from GitHub:** no npm registry needed.
  47. ```bash
  48. npx github:joezhuo2/visual-pass-skill
  49. ```
  50. The npx and npm installers run the two marketplace commands for you through
  51. the `claude` CLI, so it has to be on your `PATH`.
  52. A pass needs a browser tool in the session: the built-in browser of the
  53. Claude desktop app, the Chrome DevTools MCP server, or Claude in Chrome.
  54. Without one, Claude says so and stops; it does not install anything.
  55. ### Updates
  56. ```bash
  57. claude plugin marketplace update visual-pass
  58. ```
  59. ```bash
  60. claude plugin update visual-pass@visual-pass
  61. ```
  62. ### Uninstall
  63. ```bash
  64. claude plugin uninstall visual-pass@visual-pass
  65. ```
  66. Delete `~/.claude/.visual-pass.json` too if you had turned auto on.
  67. ## Modes
  68. | Mode | Screenshots | Rough cost |
  69. | --- | --- | --- |
  70. | light: diff-scoped, one viewport | 3 to 6 | 5,000 to 10,000 tokens |
  71. | full: light plus transitions | +3 to 4 frames | another 5,000 |
  72. | ultra: full sweep, two viewports | 40 to 80 | 60,000 to 120,000 |
  73. ### Light
  74. Claude reads the diff (plus untracked files and files it edited this
  75. session), works out which routes, components and states it touches, and
  76. measures each one at a single viewport. It screenshots the flagged states
  77. and the diff-touched states, nothing else.
  78. ### Full
  79. Light, plus transitions. For each animation or transition the diff touches,
  80. Claude triggers it and measures four frames: start, middle, end and one
  81. frame after. If the fingerprint is the same across frames, the animation is
  82. not running. It screenshots those frames only where the motion needs a look.
  83. ### Ultra
  84. Every route and reachable state (menus, dialogs, tabs, form errors, empty
  85. and loading states) at 1280x800 and 375x812. Claude states the cost first
  86. and runs it only because you typed `ultra`; it is never picked
  87. automatically.
  88. ### Auto
  89. `/visual-pass auto light` or `auto full` makes Claude run a pass after it
  90. edits UI files (`.html .css .scss .sass .less .jsx .tsx .vue .svelte
  91. .astro`). A hook adds one line of context the first time that happens in a
  92. session and nothing after that. Auto is off by default and can never be
  93. `ultra`. The setting is saved for every session.
  94. ## Usage
  95. ```
  96. /visual-pass
  97. /visual-pass light
  98. /visual-pass full
  99. /visual-pass ultra
  100. /visual-pass auto
  101. /visual-pass auto full
  102. /visual-pass auto off
  103. ```
  104. `/visual-pass` with no argument shows the auto setting. Bare `auto` means
  105. `auto light`. The plugin registers the command as
  106. `/visual-pass:visual-pass`; typing `/visual-pass` finds it.
  107. ## How it keeps cost down
  108. - **Script first:** `scripts/measure.js` runs in the page and returns text,
  109. for example:
  110. ```
  111. visual-pass 1280x800 fp=a1bcfa64 issues=3
  112. overflow-x document scrollWidth=1600 > 1280
  113. font p.tiny 9px
  114. clipped div.clip scrollWidth=239 clientWidth=80
  115. ```
  116. It checks document overflow, elements sticking out of the viewport, text
  117. clipped without an ellipsis, overlapping text, fonts under 12px, tap
  118. targets under 24x24 on viewports 480px wide or less, and broken images.
  119. Output is capped at 3 lines per check and about 15 lines in total.
  120. `issues=0` is the whole output for a clean state.
  121. - **Screenshots only where needed:** flagged states and diff-touched states,
  122. as crops of the flagged region at about half scale (roughly a quarter of a
  123. full screenshot's cost).
  124. - **Fingerprint:** `fp` is a hash of the visible layout (rounded boxes,
  125. opacity, transform, scroll). A state whose fingerprint has not changed is
  126. never screenshotted again, and equal fingerprints across animation frames
  127. show the animation did not run.
  128. - **Text over pixels:** copy and structure are checked through the
  129. accessibility tree or page text.
  130. - **Fix loop:** after a fix Claude re-runs the script, not the screenshots,
  131. and re-shoots only the fixed region.
  132. - **Short report:** a few lines: states checked, issues found and fixed,
  133. anything not verified.
  134. - **Zero cost when idle:** with auto off, the hook prints nothing and the
  135. command text is only loaded when you run it. The command loads only the
  136. instructions for the mode you asked for.
  137. ## Files
  138. | What | Path |
  139. | --- | --- |
  140. | Saved auto setting | `~/.claude/.visual-pass.json` (absent means `off`) |
  141. | Measuring script | `scripts/measure.js` |
  142. | Pass instructions and auto hook | `hooks/visual-pass.js` |
  143. | Hook registration | `hooks/hooks.json` |
  144. | Slash command | `commands/visual-pass.md` |
  145. | Plugin and marketplace manifests | `.claude-plugin/` |
  146. | npx / npm installer | `bin/install.js` |
  147. If `CLAUDE_CONFIG_DIR` is set, the settings file lives there instead of
  148. `~/.claude`.
  149. ## Development
  150. ### How it works
  151. `/visual-pass` runs `hooks/visual-pass.js set <args>`, which prints the
  152. instructions for that mode (or saves the auto setting) into Claude's
  153. context. Claude reads `scripts/measure.js` once, evaluates it in the page
  154. with the session's browser tool, and re-measures later states with the
  155. `__vp()` function it leaves behind.
  156. A `PostToolUse` hook on `Edit|Write|MultiEdit` runs the same script. With
  157. auto off it exits without reading anything. With auto on, after an edit to
  158. a UI file it returns one `additionalContext` line, and marks the session in
  159. a small file in the system temp folder so it does not repeat.
  160. `scripts/measure.js` is one expression: evaluated in a page it returns the
  161. report, and `require`d in Node it exports its pure helpers for the tests.
  162. ### Test
  163. Requirements: Node 18+ and the Claude Code CLI.
  164. ```bash
  165. npm test # measure helpers, command and hook self-test
  166. claude plugin validate . # manifest check
  167. claude --plugin-dir . -p "/visual-pass:visual-pass" # run the command from the local copy, no install
  168. ```
  169. ### Releasing
  170. Bump the version in `package.json` and `.claude-plugin/plugin.json`, add a
  171. `CHANGELOG.md` entry, then push a matching `v*` tag. GitHub Actions runs
  172. `npm test`, checks the tag matches `package.json`, publishes to npm with
  173. provenance (skipped if that version is already on npm) and creates the
  174. GitHub release.
  175. ```bash
  176. git tag v0.1.1
  177. git push origin v0.1.1
  178. ```
  179. CI publishing needs an npm automation token saved as the `NPM_TOKEN`
  180. repository secret. Without it, publish by hand with `npm publish` before
  181. pushing the tag.
  182. ## Contributing
  183. Issues and pull requests are welcome at
  184. [joezhuo2/visual-pass-skill](https://github.com/joezhuo2/visual-pass-skill).
  185. Keep changes small and run `npm test` before you open one.
  186. ## License
  187. [MIT](LICENSE)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.