Catalog/Mouse Driver
Desktop · stdio · local only

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.

Connected v1.0.0 9 tools stdio · local
Replay · pointer path live recording · session 1
160 points · replay history window only · no screen contents recorded

The overlay

public HUD · click-through

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

physical keys · works without the model
Cancel and recover control
KeysWhat happens
Ctrl+Alt+Shift+PPause: freeze the pointer where it is and refuse new actions. Press again to resume and finish the interrupted move.
Ctrl+Alt+Shift+EscPanic: stop the pointer, disarm, lock the driver against further arms.
Ctrl+Alt+Shift+EnterClear the lock. The driver stays disarmed until a new arm.
Esc ×2Quick disarm without locking, for a small correction.
mouse-driver panicSame as the panic key from a terminal.
The motion model

Why it does not look like a script

Fitts' law

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.

Bezier approach

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.

Overshoot correction

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.

Tremor

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

9 documented
Mouse Driver tool surface
ToolWhat it does
mouse_armArm pointer control for a bounded session and return the expiry. Every action tool refuses to move the pointer while disarmed.
mouse_disarmDisarm immediately and stop any motion in flight. Equivalent to the Esc double-press kill switch.
mouse_statusArmed state, remaining TTL, cursor position, screen geometry and the current session counters.
mouse_moveMove to a screen coordinate with human motion: curved approach, speed profile, overshoot correction and tremor. Returns the path actually taken.
mouse_clickMove to the target, settle, then click. Button and click count are explicit; the settle delay prevents drags being read as clicks.
mouse_dragPress, move along a curve with deliberate speed, then release. Used for selection and scrollbar drags.
mouse_scrollScroll by a number of notches at the current pointer, with the same easing as movement.
mouse_traceReturn the recorded path of the last action, downsampled, for verification and the HUD trail.
mouse_sessionStart, 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.