# nexind/cursorswarm architecture

> Architecture diagram of the GitHub repository nexind/cursorswarm, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nexind/cursorswarm
- Repository: https://github.com/nexind/cursorswarm

## Overview

CursorSwarm is a local Windows desktop app for customizing the visible cursor and rendering animated cursor effects. The user configures effects in the control panel or Cursor Lab; the app combines those settings with mouse position in its animation loop and draws overlays. Separate workflows cover themes and presets, startup and performance settings, and cursor restoration and stability checks. These capabilities are documented in the README, but v13.12 is a single-file program and the excerpts are partial, so internal links are limited to behavior supported by the excerpts or documentation.

Main entry points: [`src/cursor_swarm_v13_12.py`](https://github.com/nexind/cursorswarm/blob/main/src/cursor_swarm_v13_12.py) (Animation loop)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User interface"]
  node_panel["Control panel"]
  node_cursor_lab["Cursor Lab"]
end

subgraph group_effects["Cursor effects"]
  node_overlay["Cursor overlays"]
  node_swarm["Fake cursor swarm"]
  node_movement["Movement effects"]
  node_click["Click effects"]
  node_idle["Idle effects"]
  node_shapes["Cursor shapes"]
end

subgraph group_customization["Customization state"]
  node_themes["Themes"]
  node_presets["Presets"]
  node_settings["App settings"]
  node_local_data[("Local app data")]
end

subgraph group_runtime["Runtime and safety"]
  node_animation_loop["Animation loop"]
  node_performance["Performance controls"]
  node_stability["Stability check"]
  node_restore["Safe cursor restore"]
end

node_user(("User"))
node_windows(("Windows desktop"))
node_mouse(("Mouse position"))

node_user -->|"configures"| node_panel
node_user -->|"customizes"| node_cursor_lab
node_panel -->|"manages"| node_themes
node_panel -->|"manages"| node_presets
node_panel -->|"sets"| node_settings
node_panel -->|"configures"| node_performance
node_panel -->|"runs"| node_stability
node_cursor_lab -->|"customizes"| node_shapes
node_cursor_lab -->|"configures"| node_overlay
node_themes -->|"reads/writes"| node_local_data
node_presets -->|"reads/writes"| node_local_data
node_settings -->|"reads/writes"| node_local_data
node_animation_loop -->|"reads position"| node_mouse
node_animation_loop -->|"updates"| node_swarm
node_animation_loop -->|"renders"| node_movement
node_animation_loop -->|"renders"| node_click
node_animation_loop -->|"renders"| node_idle
node_animation_loop -->|"draws"| node_overlay
node_animation_loop -->|"uses limits"| node_performance
node_windows -->|"provides position"| node_mouse
node_overlay -->|"draws on"| node_windows
node_shapes -->|"uses cursor assets"| node_windows
node_restore -->|"restores cursor"| node_windows
node_stability -->|"checks storage"| node_local_data

click node_panel "https://github.com/nexind/cursorswarm/blob/main/src/cursor_swarm_v13_12.py"
click node_cursor_lab "https://github.com/nexind/cursorswarm/blob/main/src/cursor_swarm_v13_12.py"
click node_animation_loop "https://github.com/nexind/cursorswarm/blob/main/src/cursor_swarm_v13_12.py"
click node_overlay "https://github.com/nexind/cursorswarm/blob/main/src/cursor_swarm_v13_12.py"
click node_swarm "https://github.com/nexind/cursorswarm/blob/main/src/cursor_swarm_v13_12.py"
click node_movement "https://github.com/nexind/cursorswarm/blob/main/src/cursor_swarm_v13_12.py"
click node_click "https://github.com/nexind/cursorswarm/blob/main/src/cursor_swarm_v13_12.py"
click node_idle "https://github.com/nexind/cursorswarm/blob/main/src/cursor_swarm_v13_12.py"
click node_shapes "https://github.com/nexind/cursorswarm/blob/main/src/cursor_swarm_v13_12.py"
click node_themes "https://github.com/nexind/cursorswarm/blob/main/src/cursor_swarm_v13_12.py"
click node_presets "https://github.com/nexind/cursorswarm/blob/main/src/cursor_swarm_v13_12.py"
click node_settings "https://github.com/nexind/cursorswarm/blob/main/src/cursor_swarm_v13_12.py"
click node_local_data "https://github.com/nexind/cursorswarm/blob/main/src/cursor_swarm_v13_12.py"
click node_performance "https://github.com/nexind/cursorswarm/blob/main/src/cursor_swarm_v13_12.py"
click node_stability "https://github.com/nexind/cursorswarm/blob/main/src/cursor_swarm_v13_12.py"
click node_restore "https://github.com/nexind/cursorswarm/blob/main/src/cursor_swarm_v13_12.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_panel,node_cursor_lab,node_user toneBlue
class node_overlay,node_swarm,node_movement,node_click,node_idle,node_shapes toneAmber
class node_themes,node_presets,node_settings,node_local_data toneMint
class node_animation_loop,node_performance,node_stability,node_restore toneRose
class node_windows,node_mouse toneIndigo
```

## Components

### User interface

- [Control panel](https://github.com/nexind/cursorswarm/blob/main/src/cursor_swarm_v13_12.py): `src/cursor_swarm_v13_12.py`
- [Cursor Lab](https://github.com/nexind/cursorswarm/blob/main/src/cursor_swarm_v13_12.py): `src/cursor_swarm_v13_12.py`

### Cursor effects

- [Cursor overlays](https://github.com/nexind/cursorswarm/blob/main/src/cursor_swarm_v13_12.py): `src/cursor_swarm_v13_12.py`
- [Fake cursor swarm](https://github.com/nexind/cursorswarm/blob/main/src/cursor_swarm_v13_12.py): `src/cursor_swarm_v13_12.py`
- [Movement effects](https://github.com/nexind/cursorswarm/blob/main/src/cursor_swarm_v13_12.py): `src/cursor_swarm_v13_12.py`
- [Click effects](https://github.com/nexind/cursorswarm/blob/main/src/cursor_swarm_v13_12.py): `src/cursor_swarm_v13_12.py`
- [Idle effects](https://github.com/nexind/cursorswarm/blob/main/src/cursor_swarm_v13_12.py): `src/cursor_swarm_v13_12.py`
- [Cursor shapes](https://github.com/nexind/cursorswarm/blob/main/src/cursor_swarm_v13_12.py): `src/cursor_swarm_v13_12.py`

### Customization state

- [Themes](https://github.com/nexind/cursorswarm/blob/main/src/cursor_swarm_v13_12.py): `src/cursor_swarm_v13_12.py`
- [Presets](https://github.com/nexind/cursorswarm/blob/main/src/cursor_swarm_v13_12.py): `src/cursor_swarm_v13_12.py`
- [App settings](https://github.com/nexind/cursorswarm/blob/main/src/cursor_swarm_v13_12.py): `src/cursor_swarm_v13_12.py`
- [Local app data](https://github.com/nexind/cursorswarm/blob/main/src/cursor_swarm_v13_12.py): `src/cursor_swarm_v13_12.py`

### Runtime and safety

- [Animation loop](https://github.com/nexind/cursorswarm/blob/main/src/cursor_swarm_v13_12.py): `src/cursor_swarm_v13_12.py`
- [Performance controls](https://github.com/nexind/cursorswarm/blob/main/src/cursor_swarm_v13_12.py): `src/cursor_swarm_v13_12.py`
- [Stability check](https://github.com/nexind/cursorswarm/blob/main/src/cursor_swarm_v13_12.py): `src/cursor_swarm_v13_12.py`
- [Safe cursor restore](https://github.com/nexind/cursorswarm/blob/main/src/cursor_swarm_v13_12.py): `src/cursor_swarm_v13_12.py`

### Other components

- **User**
- **Windows desktop**
- **Mouse position**

## Connections

- User → Control panel: configures
- User → Cursor Lab: customizes
- Control panel → Themes: manages
- Control panel → Presets: manages
- Control panel → App settings: sets
- Control panel → Performance controls: configures
- Control panel → Stability check: runs
- Cursor Lab → Cursor shapes: customizes
- Cursor Lab → Cursor overlays: configures
- Themes → Local app data: reads/writes
- Presets → Local app data: reads/writes
- App settings → Local app data: reads/writes
- Animation loop → Mouse position: reads position
- Animation loop → Fake cursor swarm: updates
- Animation loop → Movement effects: renders
- Animation loop → Click effects: renders
- Animation loop → Idle effects: renders
- Animation loop → Cursor overlays: draws
- Animation loop → Performance controls: uses limits
- Windows desktop → Mouse position: provides position
- Cursor overlays → Windows desktop: draws on
- Cursor shapes → Windows desktop: uses cursor assets
- Safe cursor restore → Windows desktop: restores cursor
- Stability check → Local app data: checks storage