tinycomputer is a decision model (Jev) based harness for desktop and browser automation: Jev decides what to click, and the harness reads the screen, acts, and verifies. This crate is a purely visual part of that harness. It draws the little arrow that follows the agent around the screen, arriving where the harness is about to act, but it does not decide what to click; that decision is made elsewhere, by Jev.
It is the part of tinycomputer that a person actually watches: when the agent is about to click something, this cursor glides over to it first, the same way a person's own pointer would.
It is worth saying plainly, because it is easy to assume otherwise: this cursor sends no input. It never moves your mouse, never sends a click, and never touches a web page's DOM. The engine performs every action exactly as it would if this crate did not exist. All this crate does is put a picture on screen that happens to arrive at the same place, at the same moment.
- Anyone watching a run, in a demo, a support call, or just curiosity about what the agent is doing. Without a cursor, buttons just change with no visible cause, which is confusing to watch.
- Host applications that embed tinycomputer and want their own look for the cursor, or want to draw it inside their own window instead of a system-level overlay. See Using your own sink.
- Anyone debugging the "it looks robotic" kind of complaint, since the motion this crate produces is deliberately human-shaped: a curved path, overshoot, a little wobble, a small tremor.
If you are trying to understand why the agent clicked the wrong thing, this is not the crate to read: it never decides what to click, only how the on-screen arrow gets there. For that, see how it decides.
tinycomputer-desktop ─┐
├─► ScreenCursor::arrive(target) ─► OverlaySink ─► pixels on screen
tinycomputer-browser ─┘
Desktop and browser are two different surfaces, but there is only one cursor
for the whole screen. Both hand their target to the same ScreenCursor, in
global screen points, so the cursor can glide out of a Mail window and into a
browser tab without jumping. ScreenCursor::arrive plans the glide, sends it
to a sink to draw, and only returns once the cursor has actually landed, so
the click that follows happens right as the cursor's landing pulse shows on
screen.
By default the sink is a small helper process,
tinycomputer-cursor-overlay, that this crate also builds. It is a separate
process on purpose: a crash while drawing a pixel can never take the agent
down, and the helper can keep drawing on top of whichever application or
browser tab currently has focus.
| Folder | What lives there |
|---|---|
src/glide/ |
VirtualCursor and the human-shaped path it plans: where inside an element to aim, and how to get there. See How a glide is planned. |
src/screen/ |
ScreenCursor, the one shared cursor, and ProcessOverlay, which starts and feeds the helper. |
src/protocol/ |
OverlayCommand, the tiny JSON message that tells a sink to glide or hide. |
src/animate/ |
Animator, which turns those commands plus a clock into "what to draw right now": fades, the landing pulse, hiding when idle. |
src/sprite/ |
Sprite, the cursor's actual look, drawn once in Rust as pixels so it is identical on every platform. |
src/pace/ |
CursorPace: off, brisk, natural, calm. See Paces and configuration. |
src/bin/tinycomputer-cursor-overlay/ |
the helper binary itself, built with the overlay feature. See The overlay helper. |
- Why a cursor at all: the problem this crate solves and why it has to be cosmetic.
- How a glide is planned: the actual numbers behind the aim point, the overshoot, the bow, the wobble, and the timing.
- Paces and configuration:
off/brisk/natural/calm, and the module'scursorconfig key. - The overlay helper: the separate process that puts pixels on screen, and the protocol it speaks.
- Using your own sink: how a host with its own UI can draw the cursor itself instead of using the helper.
docs/technical/specs/virtual-cursor.md: the technical specification, with the plan and status.- How tinycomputer works: the bigger picture this crate is one small, purely visual part of.
- Watching a run: other ways to see what a task is doing besides the cursor.
- Glossary: short definitions of terms used across these pages.