Mouse Driver
Human-shaped pointer control for the trinity desktop. It moves the real X11 pointer the way a hand would: a curved approach, variable speed, a small overshoot on long moves, tremor, and deliberate pauses.
The overlay
The overlay rides on the browser window the driver is working with — it follows that window as it moves, resizes or goes fullscreen, and is click-through so it never blocks the page. It always shows its shortcut legend: pause/resume, disarm, stop/lock and unlock, with the relevant keycaps highlighted for the current state.
The overlay is the only thing a person sees while the driver works. It reports state and the last action; it is not a control surface and it does not sit on a bare desktop.
Take it back
| Keys | What happens |
|---|---|
| Ctrl+Alt+Shift+P | Pause: freeze the pointer where it is and refuse new actions. Press again to resume and finish the interrupted move. |
| Ctrl+Alt+Shift+Esc | Panic: stop the pointer, disarm, lock the driver against further arms. |
| Ctrl+Alt+Shift+Enter | Clear the lock. The driver stays disarmed until a new arm. |
| Esc ×2 | Quick disarm without locking, for a small correction. |
| mouse-driver panic | Same as the panic key from a terminal. |
Why it does not look like a script
Travel time grows with distance and shrinks with target width. A short hop to a large button is quick; a long throw to a small link is slow and careful. This is what makes timing look like a person rather than a step.
The path is a cubic curve between the start and the target with a control point offset to the side, so the pointer arcs instead of sliding along a straight line. Points are emitted at roughly 120 Hz with jitter.
Long moves land slightly past the target and correct back, the way a hand does. Short moves do not overshoot. The correction is a second, shorter curve, not a snap.
A bounded, low-amplitude noise on both axes, strongest at rest and during slow segments. It never moves the pointer more than a couple of pixels from the intended path.
Tools
| Tool | What it does |
|---|---|
| mouse_arm | Arm pointer control for a bounded session and return the expiry. Every action tool refuses to move the pointer while disarmed. |
| mouse_disarm | Disarm immediately and stop any motion in flight. Equivalent to the Esc double-press kill switch. |
| mouse_status | Armed state, remaining TTL, cursor position, screen geometry and the current session counters. |
| mouse_move | Move to a screen coordinate with human motion: curved approach, speed profile, overshoot correction and tremor. Returns the path actually taken. |
| mouse_click | Move to the target, settle, then click. Button and click count are explicit; the settle delay prevents drags being read as clicks. |
| mouse_drag | Press, move along a curve with deliberate speed, then release. Used for selection and scrollbar drags. |
| mouse_scroll | Scroll by a number of notches at the current pointer, with the same easing as movement. |
| mouse_trace | Return the recorded path of the last action, downsampled, for verification and the HUD trail. |
| mouse_session | Start, inspect or end a named session. Sessions carry the telemetry record the console replays. |
Install
{
"mcpServers": {
"mouse-driver": {
"command": "python",
"args": ["-m", "mouse_driver.mcp_server"],
"env": {"MOUSE_DRIVER_TELEMETRY": "http://127.0.0.1:8340"}
}
}
}
Point command at the project virtualenv's python on the trinity desktop. The server is local and stdio-only, so it never appears in a remote config.