Skip to content

About

Record and replay mouse and trackpad input on macOS with a compact native Swift terminal app.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

7 Commits

Folders and files

Repository files navigation

Cursor Replay CLI

Record your mouse. Replay your workflow.

Repeat clicks, drags, and scrolling in your macOS apps.
A native terminal app. Local recordings. No cloud service.

macOS 15+ Swift 6+ MIT license

Install · Open the app · Usage guide · Release notes · Developer guide

Playback preview showing elapsed time, progress, and keyboard controls

Rendered from the app with an example take. Runs in your terminal, not a separate desktop window.

Repeat a product walkthrough, revisit a scrolling interaction, or reproduce a mouse-driven UI issue without performing every gesture again.

From gestures to another take

flowchart LR
    record["1. Record your actions"] --> save["2. Save locally"]
    save --> reset["3. Reset your workspace"]
    reset --> play["4. Replay the take"]
    play -.->|"Try it again"| reset
Loading

Capture movement, clicks, drags, and mouse or trackpad scrolling with their recorded timing and pauses. Replay a take, change its speed, or loop it until stopped. Recordings are local JSON files. No third-party runtime dependencies.

Where it works

Environment Scope
System macOS 15+ in your logged-in desktop session. Not Windows or Linux.
Interface Terminal or a local integrated terminal. A CLI, not a desktop .app.
Target Mouse-driven interactions in macOS apps and browser windows, not one specific editor.
Not included Typing capture, video recording, UI-element recognition, or automatic app launching.

Important

Replay sends real mouse input at recorded screen coordinates. Restore the app state and display layout yourself, and start with a disposable document. The same event stream does not guarantee identical app behavior.

Install

Requires Swift 6+ through Apple's Command Line Tools or Xcode 16+. If needed, install the tools with xcode-select --install.

Install the stable release through this project's Homebrew tap:

brew tap Just-Jan/cursor-replay-cli https://github.com/Just-Jan/cursor-replay-cli
brew install Just-Jan/cursor-replay-cli/cursor-replay
cursor-replay doctor

Homebrew makes cursor-replay available on its normal PATH. Prefer a local build? See installation from source.

In System Settings > Privacy & Security, grant Accessibility and Input Monitoring to the app hosting your terminal. If macOS lists the executable itself, enable that entry as appropriate. Restart the terminal if needed and rerun doctor. Permission details.

Open the app

From any folder, open Terminal and run:

cursor-replay

Use a hyphen, not cursor replay. The interactive menu opens in that terminal; installation does not add an Applications or Spotlight icon.

  1. Press R and switch to your app during the three-second countdown.
  2. Perform your actions, then press Esc to stop and save.
  3. Wait for the save confirmation, then reset your app to its starting state.
  4. Press P in the terminal and switch back during the countdown.

Use Up/Down arrows to browse saved recordings; the selected take is marked >. The list shows two takes at a time. Backspace/Delete asks before removing the selected take: Y deletes it permanently; N or Esc keeps it. Press P to play it once, or L to loop it until S or Esc. The countdown runs only once; the target app is not reset between repetitions.

S also stops, but needs terminal focus. Q or Ctrl+C quits, saving an active recording first. Esc is listen-only: the target app receives it too.

Menu recordings live in ~/Library/Application Support/Cursor Replay CLI/recordings. Treat captures as private interaction data, not public fixtures.

Beyond the menu

Use record, play, info, and verify in scripts. For example, cursor-replay play demo.json --speed 0.5 --loop 3 replays a take at half speed three times. Command reference.

Upgrade or uninstall · Troubleshooting · Report an issue

About

Record and replay mouse and trackpad input on macOS with a compact native Swift terminal app.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages