⏳ This skill is pending AI review.

Scores will appear once the review pipeline completes.

v0.2.0

mouse-swarm-reveal

ruvnet@ruvnet⭐ 27 stars· last commit 8d ago· 0 open issues

Build a sequential website reveal with simulated cursor swarms, or add a local Ruflo agent status view. Use for a swarm-built landing page, cursor choreography, agent-themed product demo, reveal controls, or verified read-only Ruflo status integration.

Choose how to use this skill

You do not need every option. Choose the path your AI client supports. The stable page stays the same; versioned files are immutable.

1. Native installer

This listing has no registered native installer command. Use the complete package or source fallback below, depending on what your client supports.

Do not guess an installer command or replace an existing version without reviewing the diff.

2. Complete package recommended

Download the ZIP when available. It includes SKILL.md plus the references, security notes and version metadata.

No complete ProSkills package is published for this listing yet.

3. Prompt-only

Copy the prompt above when the agent can read the stable page or when you want to adopt the workflow without installing a skill.

Need only the instruction file?

Download SKILL.md only if your client requires a single file. The complete ZIP is safer for a full installation because it preserves the references and release context.

No path installs or executes anything by itself. Your agent still needs access to the project files. Before updating, compare the installed version and review the diff.

—/10

// RATINGS

⭐GitHub Stars
⭐⭐ 27 on GitHubGitHub ↗

Growing

🟢ProSkills Score
—
📍

Not yet listed on ClawHub or SkillsMP

// README

Mouse Swarm Reveal

Animated mouse swarm building a landing page

Turn a landing page into a visual build sequence. Elements appear in order while a swarm of colored cursors and agent markers moves around them.

See the live reveal · Try the interactive playground · Watch the 9:11 promo · Ruflo

Two ways to use it: the page reveal is simulated visual choreography. The optional local Ruflo view reads reported agent registrations and statuses. Neither mode controls a computer or starts agents.

Reveal quick start · Install the skill · Ruflo observation · Configuration · Troubleshooting

Animated reveal sequence

CapabilityWhat it does
Sequential revealShows page elements in document order and optionally types leaf text.
Cursor choreographyAdds configurable visual cursors, colors, labels, and selection effects.
PlaybackExposes replay, pause, resume, skip, progress, and cleanup.
Ruflo observationShows local CLI agent registrations and reported status.
Agent skillsInstalls reusable instructions and assets for Claude Code and Codex.

Find your workflow

Animated guide to Mouse Swarm workflows

I want toStart here
Build an animated page with Claude or CodexInstall the skill or use the Claude plugin.
Experiment with my own contentOpen the studio for a text outline, or capture a local page to preserve its visual appearance.
Observe Ruflo locallyFollow the Ruflo observation guide.
Replay activity or create an MP4Follow the activity and video guide.
Check a reveal in a browserUse the Playwright verification guide.
Deploy a public revealSee the Cloudflare guide.

See it in action

Landing page reveal. Watch the simulated swarm assemble the Ruflo page one element at a time.

Screenshot of the Ruflo landing page being revealed by simulated cursors

Studio. Tune the sequence or import a local HTML file as a selectable text outline.

Screenshot of Mouse Swarm Studio with its preview and settings

Playground. Try cursor counts, timing, and playback controls in the browser.

Screenshot of the interactive reveal playground

The screenshots show the public demos. Their cursors are simulated; the local Ruflo observer presents reported status separately.

Claude Code plugin and Ruflo mod

Animated Claude plugin and Ruflo mod overview

Install the plugin from the Claude Code prompt:

/plugin marketplace add ruvnet/mouse-swarm
/plugin install mouse-swarm@mouse-swarm

The plugin adds reveal, observation, Playwright verification, and video commands. Its optional Claude mod observes successful agent spawn callbacks in process and can contribute a status segment to ruflo-mods when that plugin is present. It does not infer cursor positions or task execution. See the Claude plugin guide for compatibility, commands, and Ruflo setup.

Install the skill

From your project directory, run:

npx skills add ruvnet/mouse-swarm --skill mouse-swarm-reveal -a claude-code -a codex -y --copy

This installs the skill and its bundled browser modules for both Claude Code and Codex. Use -a claude-code or -a codex to target one agent. Omit -y to review the installer prompts, or add -g to install globally. The current skills CLI requires Node.js 22.20 or later; check your installed CLI version for its requirements.

Then ask your agent:

Use the mouse swarm reveal skill to make this landing page build itself in sequence. Include replay and skip controls.

What is installed

  • A portable SKILL.md with the integration and validation workflow.
  • A dependency-free browser module in assets/mouse-swarm.js.
  • A standalone example in assets/demo.html.
  • Ruflo adapter and view modules in assets/ruflo.js and assets/ruflo-view.js.

The installer is a separate tool. Review the skill before use, and use --copy when you want independent copies instead of symlinks.

Quick start: build a reveal

Requirements: Node.js 18 or later for the package. The skills installer can have a newer Node requirement; check its output if installation fails.

  1. Create a project directory and install the package from GitHub. The npm registry release is pending.
mkdir swarm-example
cd swarm-example
npm install github:ruvnet/mouse-swarm
cp node_modules/@ruvector/mouse-swarm/src/index.js ./mouse-swarm.js
  1. Save the following as index.html. The order of the data-swarm-item elements is the order in which they appear. Keep controls outside the reveal targets so they remain available.
<!doctype html>
<html lang="en">
<head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>Swarm reveal</title></head>
<body>
  <main>
    <h1 data-swarm-item data-swarm-type>Build something together.</h1>
    <p data-swarm-item data-swarm-type>Give ideas room to grow.</p>
    <a data-swarm-item href="https://github.com/ruvnet/ruflo">Explore Ruflo</a>
  </main>
  <nav aria-label="Animation controls">
    <button id="replay">Replay</button>
    <button id="pause">Pause</button>
    <button id="resume">Resume</button>
    <button id="skip">Skip animation</button>
  </nav>
  <script type="module">
    import { createSwarmReveal } from './mouse-swarm.js';
    const reveal = createSwarmReveal({ cursors: 20, interval: 280 });
    document.querySelector('#replay').addEventListener('click', reveal.replay);
    document.querySelector('#pause').addEventListener('click', reveal.pause);
    document.querySelector('#resume').addEventListener('click', reveal.resume);
    document.querySelector('#skip').addEventListener('click', reveal.skip);
    reveal.start();
  </script>
</body>
</html>
  1. Serve the folder over HTTP, then open http://localhost:8000:
python3 -m http.server 8000

The complete page remains readable without JavaScript. To use an existing bundler, import the package directly instead of copying the browser module:

import { createSwarmReveal } from '@ruvector/mouse-swarm';

Animated playback controls

Use the browser module

For an existing project, install from GitHub:

npm install github:ruvnet/mouse-swarm

Mark elements in the order they appear in the document. Add data-swarm-type to a leaf element when its text should appear in chunks.

<h1 data-swarm-item data-swarm-type>Build something together.</h1>
<p data-swarm-item data-swarm-type>Give ideas room to grow.</p>
<button id="skip">Skip animation</button>
import { createSwarmReveal } fro

// HOW IT'S BUILT

// FILES

6 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.

  • skills/mouse-swarm-reveal/SKILL.md9.8 KB4eadf26ed2f4upstream ↗
    ---
    name: mouse-swarm-reveal
    description: Build a sequential website reveal with simulated cursor swarms, or add a local Ruflo agent status view. Use for a swarm-built landing page, cursor choreography, agent-themed product demo, reveal controls, or verified read-only Ruflo status integration.
    ---
    
    # Mouse Swarm Reveal
    
    Create the complete, usable page first. Choose the mode explicitly:
    
    - **Reveal:** simulated cursors choreograph a sequential presentation. They are not agents, computer input, or telemetry.
    - **Ruflo observation:** the local bridge reports agent registrations and statuses from the CLI. It does not start agents, prove task execution, or supply cursor coordinates.
    - **Both:** keep the visual reveal and observed status clearly labeled and separate. Only show a live marker when the trusted source actually supplies its coordinates.
    
    Use `assets/demo.html` for the existing working reference. The bundled browser modules are self-contained and have no runtime dependencies.
    
    ## Workflow
    
    1. Inspect the project instructions, framework, entry point, existing styles, and available assets. Identify the content, brand, links, and intended reveal sequence. Reuse assets only when authorized. If given a URL, work from authorized content and available source; do not assume the site permits cross-origin fetching or reproduce third-party assets without permission.
    2. Add `data-swarm-item` to meaningful elements in document order. Keep targets at one hierarchy level: marking a parent and its descendants can hide content unexpectedly. Add `data-swarm-type` only to leaf elements with plain text; the module replaces their text temporarily during the animation.
    3. Integrate the bundled `assets/mouse-swarm.js`. For a static site, copy it into a public assets directory and import it as a browser ES module. For a bundled app, install the repository package with `npm install github:ruvnet/mouse-swarm` and import from `@ruvector/mouse-swarm`.
    4. Initialize after the target DOM exists. The module captures targets at initialization, so recreate the instance after a material target list change. Configure cursor count, colors, labels, size, motion speed, bot frequency, selection outline, typing cadence, and optional scrolling to suit the project. Expose keyboard-accessible replay, pause, resume, and skip controls that stay visible throughout the reveal. In component frameworks, call `destroy()` on unmount.
    
    ```js
    import { createSwarmReveal } from '@ruvector/mouse-swarm';
    
    const reveal = createSwarmReveal({
      root: document, cursors: 24, interval: 200,
      colors: ['#c8f578', '#70c9f9', '#c9acff'],
      labels: ['Scout', 'Builder', 'Reviewer'], botEvery: 4,
      cursorSize: 18, cursorSpeed: 600, selection: true,
      typeText: true, typeWords: 2, autoScroll: false,
      onStep: ({ current, total }) => { /* update progress */ },
      onError: (error) => { /* report the failure */ }
    });
    reveal.start();
    // Connect controls to reveal.replay(), reveal.pause(), reveal.resume(), and reveal.skip().
    // Read reveal.getState() for status and progress.
    // Call reveal.destroy() during cleanup.
    ```
    
    For static sites, copy `assets/mouse-swarm.js` into a served project directory and replace the import path with that served module path. Serve the site over HTTP; browsers do not resolve bare package names without a bundler or import map. `assets/demo.html` is an interactive configuration reference; use the project's own content and design. Targets cannot be shared by simultaneous instances from the same module. An animation or callback error restores content and reports through `onError`.
    
    ## Capture a local page
    
    When the user wants a visual reconstruction, use the optional `mouse-swarm-capture` command on trusted, authorized local HTML. Choose viewport dimensions and verify the resulting sequence editor and output before video export. The result uses static screenshots for one viewport: do not claim that original links or controls work, that the full page was captured, or that external resources were preserved. Scripts are disabled by default; allow them only for explicitly trusted content. See `docs/page-capture.md` in the repository for prerequisites and limitations.
    
    ## Sequencing and interaction
    
    - Mark individual visual units rather than an entire section. Use DOM order for header, headline, supporting copy, cards, and final action; use short leaf text for typed steps. Do not mark nested targets. Set `data-swarm-order` (0 to 100000) to change reveal order without changing DOM semantics, `data-swarm-delay` (0 to 10000 ms) for a per-element delay, and `data-swarm-role` for an illustrative label. Use `data-swarm-group` on adjacent targets for a simultaneous reveal and `data-swarm-effect="drag"` for an illustrative drag ghost. Grouped text typing proceeds sequentially after items appear.
    - Keep replay, pause, resume, and skip outside the selected content. Do not cover interactive elements or hijack scrolling. Use `onStep` for progress and `onComplete` to restore UI state; inspect `getState()` for status and counts.
    - Use `destroy()` before recreating an instance or unmounting a component. Preserve the page's semantics and no-JavaScript content. Respect reduced motion and let the module restore content on errors.
    - For MP4 capture, use the optional local `mouse-swarm-video` command with trusted HTML, or `mouse-swarm-activity-video` with a saved observation recording. Both require Playwright, Chromium, and FFmpeg; a video from observations shows source labels and rescales timing. Specify dimensions and duration; verify the resulting file. Do not present a prerecorded demonstration as a live swarm.
    
    ## Ruflo integration
    
    For observed state, prefer the opt in loopback example: run `npx --yes --package=github:ruvnet/mouse-swarm mouse-swarm observe` from the intended Ruflo project and open the printed local URL. It reads agent registrations and status using the local Ruflo CLI; it does not start agents, control a computer, or report cursor positions. Do not expose that server publicly.
    
    For a custom host, use `@ruvector/mouse-swarm/ruflo` and `@ruvector/mouse-swarm/ruflo-view`, or copy the corresponding bundled assets into the project. The host must authenticate, authorize, minimize, and normalize events. Supply coordinates only when they were actually observed. Do not put secrets, raw task descriptions, or private agent data into a public landing page. Display status provenance and stale or error state; do not infer execution from registration. The adapter does not perform network calls or execute tasks. For opt-in snapshot capture and replay, install the package and use `@ruvector/mouse-swarm/activity`; source timestamps are observation times, and changes between snapshots are not proof of execution. The `@ruvector/mouse-swarm/metaharness` adapter requires an explicit host mapping of MetaHarness session envelopes and does not discover or authenticate sessions. In Node, `@ruvector/mouse-swarm/metaharness-file` can import a bounded, explicitly selected complete session JSONL file; it validates structure but not state hashes or authenticity.
    
    For a complete authenticated snapshot, validate and map source records to `agent.upsert` events and use `adapter.replaceAgents(events)` once per successful poll. For incremental updates use `adapter.ingest(event)` with monotonically increasing per-agent revisions when the source supports them. The view supports `unverified`, `connected`, `stale`, `error`, and `disconnected`: report connected only after the source succeeds, and mark a failed poll stale or error. Equal snapshot revisions retain prior data. Removal revision history is bounded to twice `maxAgents`, so the source must also prevent delayed events after eviction. Destroy the view and dispose the adapter during teardown.
    
    The local bridge polls only the agent list and excludes task bodies, prompts, and credentials. Custom adapters may accept `task.update` events, but task titles are hidden by default and must not be published without authorization. Do not label illustrative events as native Ruflo wire events.
    
    ## Playwright verification
    
    For browser checks, install Playwright and a matching browser in the target project and use `@ruvector/mouse-swarm/playwright` with a host-owned Page. Configure selectors for actual controls and test pause, resume, skip, reduced motion, and pointer transparency. A target with no hidden marker is not proof that text typing or callbacks have completed; check the application completion indicator as well. See the repository `examples/playwright-check.mjs` for a runnable offline example. Choose the browser and video settings according to the request, then validate actual output on the available platform.
    
    ## Validation
    
    - Check the initial sequence, final page, replay, pause, resume, skip, and teardown. Confirm the controls remain usable during the reveal and no target is owned by a second active instance. Validate custom values and progress callbacks. Confirm that links and controls remain usable and the overlay does not intercept clicks.
    - Check narrow and wide viewports, reduced motion changes during playback, callback failures, and keyboard focus while targets are hidden. Keep content readable without JavaScript and avoid forcing the user's scroll position.
    - Preserve the original text, HTML semantics, and destination links. Never collect visitor data or send content elsewhere as part of the effect.
    - For observation, verify the CLI responds in the intended project, source failure is visible, and an empty list is shown honestly. Test with actual events when available; never claim a live swarm was verified using a fabricated fixture.
    - If video is requested, use the optional MP4 exporter or another recording workflow and verify the requested format and dimensions. The reveal browser module itself does not create MP4 files.
    
    Do not copy third-party websites or assets without permission. Describe animated cursors as simulated unless they are backed by verified live agent events.
    
  • skills/mouse-swarm-reveal/assets/demo.html6.2 KB26edc8bb4452upstream ↗
    <!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><meta name="color-scheme" content="dark"><title>Mouse Swarm Playground</title><style>
    :root{color-scheme:dark;font:15px/1.5 system-ui,sans-serif;background:#0a100e;color:#eef4e9}*{box-sizing:border-box}body{margin:0}a{color:#c9f578}header{display:flex;justify-content:space-between;align-items:center;border-bottom:1px solid #28362b;padding:18px clamp(20px,4vw,60px);gap:14px}.brand{font-weight:800;font-size:18px;letter-spacing:-.5px}.brand span{color:#c9f578}.sub{color:#92a396;font-size:12px}main{padding:36px clamp(20px,4vw,60px) 80px;display:grid;grid-template-columns:minmax(230px,320px) minmax(0,1fr);gap:20px;max-width:1500px;margin:auto}.panel{border:1px solid #2c3e2e;background:#101b14;border-radius:12px;padding:23px}.panel h2{margin:0 0 4px;font-size:18px}.intro{font-size:12px;color:#91a597;margin:0 0 25px}label{display:block;font-size:12px;color:#c9d7c9;margin:16px 0 7px}label output{float:right;color:#c9f578}input[type=range]{width:100%;accent-color:#c9f578}input[type=checkbox]{accent-color:#c9f578}.check{display:flex;gap:8px;align-items:center;margin:18px 0}.check input{margin:0}button{font:inherit;border:1px solid #435d46;background:#203424;color:#e9f4e4;padding:10px 14px;border-radius:6px;cursor:pointer}button:hover{border-color:#c9f578}button:focus-visible{outline:2px solid #c9f578;outline-offset:3px}.primary{background:#c9f578;border-color:#c9f578;color:#14200e;font-weight:700;width:100%}.buttons{display:flex;flex-wrap:wrap;gap:6px;margin-top:14px}.buttons button{flex:1;padding:8px;font-size:12px}.status{font-size:12px;color:#add494;margin-top:15px;min-height:24px}.canvas{position:relative;min-height:610px;overflow:hidden;background:radial-gradient(circle at 70% 15%,#2c492530,transparent 40%),#0c1410}.canvashead{display:flex;justify-content:space-between;color:#83958a;font:11px ui-monospace,monospace;letter-spacing:1px;border-bottom:1px solid #26372b;padding-bottom:16px}.content{max-width:660px;margin:70px auto 30px}.eyebrow{font:11px ui-monospace,monospace;letter-spacing:2px;color:#bde987}.hero{font-size:clamp(42px,6vw,78px);letter-spacing:-.055em;line-height:1.02;margin:24px 0}.desc{max-width:540px;color:#a8b8aa;font-size:16px;line-height:1.7}.cards{display:grid;grid-template-columns:repeat(3,1fr);gap:10px;margin-top:45px}.card{border:1px solid #344c36;background:#15241a;border-radius:8px;padding:17px;min-height:125px}.card b{display:block;color:#d9f3bd}.card small{display:block;color:#94a996;margin-top:9px}.note{font-size:11px;color:#7f9483;margin-top:28px}@media(max-width:800px){main{grid-template-columns:1fr}.canvas{min-height:500px}.content{margin-top:45px}.cards{grid-template-columns:1fr}.card{min-height:75px}}@media(prefers-reduced-motion:reduce){*{scroll-behavior:auto!important}}
    </style></head><body><header><div class="brand"><span>✳</span> Mouse Swarm</div><a href="https://github.com/ruvnet/mouse-swarm">View source ↗</a></header><main><section class="panel" aria-labelledby="settingsTitle"><h2 id="settingsTitle">Reveal controls</h2><p class="intro">Adjust the choreography, then build the page again.</p><label for="cursors">Cursors <output id="cursorsValue">20</output></label><input id="cursors" type="range" min="0" max="80" value="20"><label for="interval">Step interval <output id="intervalValue">220 ms</output></label><input id="interval" type="range" min="20" max="800" step="20" value="220"><label for="words">Words per step <output id="wordsValue">2</output></label><input id="words" type="range" min="1" max="10" value="2"><label for="bots">Bot frequency <output id="botsValue">Every 5</output></label><input id="bots" type="range" min="0" max="10" value="5"><label class="check"><input id="selection" type="checkbox" checked>Show selection outline</label><button id="apply" class="primary">Apply and replay</button><div class="buttons"><button id="pause">Pause</button><button id="resume">Resume</button><button id="skip">Skip</button></div><div class="status" id="progress" role="status" aria-live="polite">Ready</div><p class="note">Cursors are simulated. No visitor data or agent activity is collected.</p></section><section class="panel canvas" aria-label="Reveal preview"><div class="canvashead"><span>LIVE PREVIEW</span><span>SIMULATION</span></div><div class="content" id="reveal"><div class="eyebrow" data-swarm-item>ONE IDEA · MANY MOVING PARTS</div><h1 class="hero" data-swarm-item data-swarm-type>Build something together.</h1><p class="desc" data-swarm-item data-swarm-type>Give your landing page a reveal that feels collaborative, one element at a time.</p><div class="cards"><div class="card" data-swarm-item><b>Coordinate</b><small>Set the rhythm.</small></div><div class="card" data-swarm-item><b>Compose</b><small>Reveal each idea.</small></div><div class="card" data-swarm-item><b>Replay</b><small>Share the result.</small></div></div></div></section></main><script type="module">
    import { createSwarmReveal } from './mouse-swarm.js';
    const $=id=>document.getElementById(id);let reveal;
    for(const id of ['cursors','interval','words','bots']) $(id).addEventListener('input',()=>{$(id+'Value').textContent=id==='interval'?$(id).value+' ms':id==='bots'?($(id).value==='0'?'None':'Every '+$(id).value):$(id).value});
    function run(){if(reveal)reveal.destroy();reveal=createSwarmReveal({root:$('reveal'),cursors:Number($('cursors').value),interval:Number($('interval').value),typeWords:Number($('words').value),botEvery:Number($('bots').value),selection:$('selection').checked,labels:['Scout','Builder','Reviewer'],onStep:({current,total})=>{$('progress').textContent=`Building ${current} of ${total}`},onComplete:({reason})=>{$('progress').textContent=`Finished: ${reason}`},onError:()=>{$('progress').textContent='Reveal failed. Content has been restored.'}});reveal.start()}
    $('apply').onclick=run;$('pause').onclick=()=>{reveal.pause();const s=reveal.getState();$('progress').textContent=s.status==='paused'?`Paused at ${s.current} of ${s.total}`:`Status: ${s.status}`};$('resume').onclick=()=>{reveal.resume();const s=reveal.getState();$('progress').textContent=s.status==='running'?`Building ${s.current} of ${s.total}`:`Status: ${s.status}`};$('skip').onclick=()=>reveal.skip();run();
    </script></body></html>
    
  • skills/mouse-swarm-reveal/assets/mouse-swarm.js15 KBc56fc8986510upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • skills/mouse-swarm-reveal/assets/ruflo-view.js6.2 KBcdfc34d964beupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • skills/mouse-swarm-reveal/assets/ruflo.js7.7 KB62fda34561e7upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • README.mdupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

Plain-text copy, no login: /skill-bundles/ruvnet-mouse-swarm-skills-mouse-swarm-reveal.md

// REPO STATS

27 stars
0 open issues
Last commit: 8d ago