Handoff user guide

For the person who does the process being documented. No technical knowledge needed.

What Handoff does

You work through a process the way you always do. Handoff watches, takes screenshots of the window you are working in when you click or switch windows, and notes which app was in front. Afterwards it turns that into a guide: the steps, with screenshots, and how long the process usually takes. You check the guide, fix any wording, remove anything private, and export it: for your wiki or process library, for training someone new, for an audit, as a starting point for automation, or for whoever takes the work over.

Nothing leaves your computer. There is no account and no upload.

First time

Install Handoff and open it. On a Mac, the Settings tab shows three permissions to grant: Screen Recording, Accessibility and Input Monitoring. Press Grant for each, then quit and reopen Handoff (macOS only applies Screen Recording after a restart). Move the mouse and check Settings again: "Input hook verified" means everything works.

On Linux, open Settings → This desktop to see what works on your desktop. On Wayland, Handoff reads the keyboard and mouse from the input devices, which needs your user in the input group: run sudo usermod -aG input $USER once, then log out and back in. Wayland limits a few things: typed text is not recorded (keys and shortcuts are), clicks have no position except on Hyprland, and on desktops that do not say which window is in front (GNOME) exclusions cannot pause a recording. X11, KDE Plasma and Hyprland do.
In Settings, under Never record these, add the apps that must stay private, for example Mail, Slack, WhatsApp, 1Password, or your banking site’s window title. For an app, choose it from Pick an app…, which lists the apps open now and the ones seen in your recordings, spelled the way Handoff sees them; then press Add. You can also type a name. While one of them is in front, recording pauses by itself and the time is not counted.
A model to write the guide, on this computer. Settings → Local model suggests one for the computer’s memory:
- On a Mac with Apple Intelligence (macOS 26 or later, Apple silicon), Apple’s on-device model is built in: nothing to install. It is suggested on Macs with less than 16 GB of memory, and used by itself when no other model is installed.
- With Ollama installed and open, Settings can download a model for you: a 4B model for 8 GB of memory, 8B for 16 GB, 14B for 32 GB or more. Larger ones write clearer steps but take longer. Without any model the guide still works, but steps get plain names like "Work in Safari: Supplier portal" that you edit yourself.
On Windows and Linux, optional: on the Review screen, press Install (30 MB) under Guide once, so Handoff can read the text on your screenshots (on a Mac this is built in). That makes the step descriptions much more specific.
Optional, for spoken notes: Settings → Voice notes. On a Mac, Apple’s speech recognition is used on the Mac itself (macOS asks once for the microphone and for speech recognition); or choose Whisper and download its model once (150 MB). Only the text is kept.

Recording a task

On the Record tab, type the task name. Use the same name every time you do that task, for example "Monthly supplier invoices". The box suggests names you have used before.
Press Record and do the task as usual. You can close the window; the menu bar icon keeps recording (see From the menu bar). The chip shows "Recording", or "Paused: Mail is excluded" while a private app is in front.
If you take a break, press Pause, then Resume.
To explain something as you go (why you check a figure, what you do when it is wrong), press Add a note… on the Record tab. Type it, or press ● Speak, talk, then press Stop and transcribe; the words appear in the box for you to check before you press Save note. The note is attached to that moment of the recording.
When the task is done press Stop, or press Cmd+Shift+R (Ctrl+Shift+R on Windows and Linux) from anywhere.
Choose Review to check the recording before it goes anywhere (recommended), Count without reviewing to count it as it is, or Discard.

The timer shows active time only: pauses and excluded apps are not counted.

Scrolling is recorded too: when you scroll down a long page to reach a button, the step says "Scroll down to “Confirm payment”" and its screenshot shows where you scrolled to.

So is dragging, which a still picture cannot show: moving a slider, a file into a folder, a column wider. While you drag, Handoff takes a quick picture five times a second (for up to four seconds), and the step gets a short looping clip under its screenshot in guide.html and guide.md. The PDF and Word file say the animation is in the web guide. Not on Wayland, which does not give the pointer’s movements.

Handoff’s icon in the menu bar (the notification area on Windows and Linux) does the same without the window in the way:

Record "…" starts the task you recorded last; Record another task lists the others with how long each usually takes; New task… opens the window to name a new one.
While recording, the icon turns red and, on a Mac, shows the time beside it. The menu has Add a note…, Pause or Resume, Stop, and Stop and review.
Control-Option-N (Ctrl+Alt+N on Windows and Linux) opens a small note window from anywhere while recording. Type or speak the note and press Save note (or Cmd-Return); Escape closes it, and you are back in the app you were using. Just after you have used the menu bar menu, macOS holds the shortcut back from Handoff for a moment: the note window still opens, and asks you to click in the box before typing. Like Handoff’s main window, it never appears in the screenshots, and clicks on Handoff’s icon and menus are not recorded.

Reviewing

The Review screen walks through three steps: 1 Check, 2 Guide, 3 Export. The button at the bottom right always does the next thing.

1 Check shows everything that was captured:

Apps lists every app with screenshots, clicks or keys. Remove all next to an app deletes everything from that app. Use this when something private slipped in.
Window titles lists the titles that will appear in the guide (file names, page titles). Leave out removes a title that names a person, a customer or a private file.
Breaks lists stretches of five minutes or more with no activity. If that was a break, press Yes, don’t count it so it is removed from the duration.
Screenshots: pick a thumbnail (or use the arrow keys) to see it large. Delete removes that one screenshot. Hide an area, then drag over part of the picture and press Hide this area to blur it, for example a customer’s name.
Blurred automatically: when the guide is written, Handoff reads the words on each screenshot and blurs, in the exported pictures, any email address, card number, ID or phone number, password or code it finds. Screenshots with a blurred area have a small grey mark in the strip, and Next blurred screenshot goes to them. Under the picture each area is listed ("Blurred: email address"); Show keeps one as recorded, Blur again undoes that. The recording itself is not changed.

Buttons that delete something ask once more ("Delete this screenshot") before they act.

Handoff never records its own window or the system’s permission and password prompts, so they do not show up here.

Writing the guide

On 2 Guide, press Write the guide. Handoff reads the text on the screenshots (if text recognition is installed), splits the recording into steps and writes a title and an instruction for each. With a 4B model this takes well under a minute for a short task; a progress bar shows where it is. Steps only name things that appear in the recording; when the model names something that is not there, Handoff uses a plain title instead.

Click any title or description to change it. Your edits are kept even if you press Write again later.

Edit under a step opens more:

Move up and Move down change its place in the guide; Merge with the next step makes one step of two.
Screenshots in this step lists every screenshot taken during it. Show this puts another one in the guide; Split here starts a new step at that screenshot.
Box, Arrow and Crop: drag on the picture to draw a red box around something, point at it with an arrow, or keep only part of the picture. Remove last and Clear undo them. The recording is not changed: the drawing is added when the guide is exported.

Add the why. A screenshot shows what you did, not why. Under any step press Add context and type or speak the reason, the rule ("only approve if the PO number matches") or what to do when something is wrong. To explain several steps at once, tick their boxes and press Add context to them…. Notes appear in the guide as Why: and the model uses them the next time you press Write again.

Detours. Steps that look unrelated to the task (checking the news, a quick sum, the weather) are folded under Looks like a detour and left out of the guide. Press Include on any that belong; Leave out on a step does the opposite.

Exporting

On 3 Export, press Export guide…, choose a folder, and Handoff writes a sub-folder named after the task and the date. Inside:

guide.html: open it in any browser. Screenshots are embedded, so it can be emailed on its own.
guide.pdf: the same guide as a PDF, A4, to print or send. It has a bookmark for each step.
guide.docx: the same guide as a Word document. To put it in Confluence, use Import from Word (or create a page and import the file); in SharePoint, upload it to a site’s pages or documents; in Google Docs, open it from Drive. Headings, notes and screenshots come across.
guide-for-notion.zip: in Notion, choose Import, then Text & Markdown, and pick this zip: the page comes in with its screenshots.
guide.md: the same guide as Markdown, with the screenshots in images/.
playbook.json: the same steps in a form an AI assistant can follow.

Leave Count this run ticked so the recording counts toward how long the task usually takes; Count without exporting does that without writing a guide.

A video overview

Turn on Also make a video overview before exporting (Handoff remembers it), or press Make a video overview after. Handoff makes overview.mp4 in the guide’s folder, and guide.html shows it at the top. It walks through the steps: each screenshot, the view moving in to where you clicked, and a short caption ("Open the supplier portal"). Someone taking the task over can watch it once to see the shape of the task before following the guide.

It is made only from the exported guide: blurred and hidden areas stay blurred, and deleted screenshots are not in it.
The captions are the steps’ titles. A title longer than seven words is shortened by the local model, in a few seconds; without a model, or where its caption is not good enough, the title is used. Edit captions lets you change any of them, then Make again (the model is not asked again).
Choose its length first: Short (about 30 to 45 seconds: only the steps always done, about two seconds each), Standard (about a minute, at most a minute and a half: steps done only sometimes are left out first if it would run longer, then each step is shown a little shorter) or Full (every step at reading speed, however long). Before it is made, the panel says how long it will be and how many steps it will show; the closing card says how many were left out. Change length makes it again at another length, with the same captions.
Making it takes 10 to 40 seconds and nothing leaves the computer. A guide in the shared library gets its video from the Video button in the Library.

Nothing you record leaves the computer. Handoff goes online only to download a model you ask for; Offline mode in Settings stops even that. It reads the mouse and keyboard only while recording (and for 20 seconds after Settings opens, to check they work). network.md lists every connection and how to check.

Screenshots show only the window you were working in (and the area around a click outside it), so your desktop and other apps are not in the guide. To keep whole screens, for a task that uses several windows side by side, turn on Keep the whole screen in Settings before recording.

Nothing typed into a password field is kept, whatever the settings: not the text, not even how many keys. Handoff notices the field has the cursor (on a Mac) and keeps recording the clicks and screenshots, which show only dots, so signing in is still a step in the guide.

Typed text is only included when Record what I type was on. Even then, card numbers, ID numbers, email addresses, phone numbers and anything typed after a password prompt are replaced with [redacted], in the typed text and in anything the model wrote about it. Your own notes are exported exactly as you wrote them.

The same applies to the text read from screenshots and to window titles (a webmail tab’s title carries the account’s address). Web addresses keep their site and path, but anything after ? or #, where sign-in links, session ids and search terms go, is replaced, as are long codes of mixed letters and digits. The screenshots themselves still show what was on screen: use Hide area on the Check screen for an address bar or anything else private.

Your organisation’s look

Settings → Branding makes exports look like your organisation’s own documents: an accent colour (headings, step numbers, the note box), text colours, the click marker’s colour, fonts for headings and text, a logo, your organisation’s name ("Recorded 3 Nov by Acme Ltd") and a footer line. Press New brand…, fill in what you want (anything left as Handoff’s stays as it is), check the preview and Export a sample PDF, then Save. Settings warns when a colour will be hard to read.

Brands are saved, so you can keep one per client. The ticked one is used for every export; the Brand menu next to Export picks another for one export.
It applies to the web page, the PDF and the Word file, the Markdown (the logo), the video overview, the screenshots’ click marker, procedures and handover packs, and the Follow window (the logo and accent of the guide being followed). Handoff’s own window keeps its look.
Fonts: four are built in (Noto Sans, Noto Serif, Inter and Source Serif 4), or Import a font… for your own .ttf or .otf. Imported fonts are embedded in the PDF and the web page, so make sure their licence allows that (Handoff refuses fonts marked as not embeddable). Word files name the font, and Word uses it where it is installed.
To use one brand across a team: Share… saves it as a .handoff-brand file (with its logo and fonts inside). Saved in the shared library folder, it appears in everyone’s Settings under In the shared library, ready to Import; or send the file and use Import a brand file….
"Made with Handoff" stays at the end of every export.

Getting "usually takes"

Record the same task name on several days. The Library tab then shows, for each task, "usually takes 14 min (9 to 22), 5 runs". With one recording it shows "took 14 min (1 run)". Only counted recordings count; the Library marks the others "not counted yet". Export from the most recent recording and the guide carries that statistic.

One procedure from several recordings

A task is rarely done the same way twice. Once a task has two or more recordings with a written guide, its Procedure button in the Library puts them together:

the steps every recording shares;
steps only some recordings have, marked sometimes, with how often ("1 of 3 runs") and when, if your notes say;
places where recordings went different ways ("One of these: download the remittance from the portal, or save it from the email");
how long each step usually takes.

Press Build the procedure (and Rebuild after recording again). The local model words each step from all the recordings, naming what changes in general terms ("the invoice", not "invoice 1042"); it states when a step is done only if a note of yours says so, never by guessing.

Questions ask about what nobody has explained yet, the most useful first:

what your latest recording did differently: "In your latest recording (30 Oct) you did not "Ask Finance for a second approval", which every other recording has. Was that on purpose?", or a step that is new;
where recordings went different ways, and steps only some recordings have: "In 1 of 3 runs you did "Request second approval". When do you do it, and when not?";
long waits: "During "Approve each invoice" you waited about 3 min on "Approvals". What were you waiting for or checking?";
steps whose purpose the screen does not show: "Why is "Export the CSV" done?".

Answer by typing or speaking; the answer becomes a note on that step, and the next Rebuild uses it. Skip a question you cannot or need not answer; it is not asked again.

After you record a task that already has a procedure, the recording’s Export step offers Compare with the procedure: the procedure is rebuilt with the new recording and asks about what it did differently.

What changed compares the procedure with an earlier version of it ("Since 30 Sep, 3 recordings"): steps that are new, no longer done, now only sometimes, now every time, or now one of several ways. A version is kept each time the steps change; the twenty most recent are kept.

Correct a step when Handoff put things together wrongly. It lists the recordings the step was put together from; Move to… moves one recording’s step to another step, or makes it a step of its own when it was something else. Same step as joins two steps that are the same thing done differently. Under Recordings, Leave out keeps an unusual recording (a one-off fix, a training run) from shaping the procedure; Include again brings it back. Your corrections are listed with Undo, and stay when the procedure is rebuilt with new recordings. Only the steps a correction changes are written again, so it takes seconds.

Export procedure… writes a folder like a guide’s, with sometimes steps and "one of these" choices, and a playbook.json that tells an agent how often each step occurs and when.

Following a guide

Handoff can walk someone through a guide step by step, in a small window beside their work. It opens any guide, procedure or handover pack Handoff exported, on any computer with Handoff: the recordings are not needed.

Follow a guide… in the Library: pick the exported folder. After exporting, Follow this guide (Review), Follow (Procedure) and Follow (a handover pack) do the same.
The window shows the step, its why notes, the screenshot with the click marked (click it to see it larger) and any scrolling needed. A step done only sometimes says when; where recordings went different ways it shows "One of these". Next and Back (or the arrow keys) move through it, and bring the app the step is done in to the front.
Move on by itself: while it is on, Handoff watches which window is in front and what you click (the name of the button, never your typing) and turns the page when you start the next step. It keeps none of it, and stops when you turn it off or close the window.
The window is left out of screen captures, so it never appears in a recording.

Check a guide by following it. In the follow window, Record while I follow records you (or a colleague, or anyone who has never done the task) doing the task from the guide. Stop there opens the recording’s Review; once its guide is written, the Export step shows what following the guide turned up, for the person who wrote it: steps not done (could not be found, or not needed), steps done that the guide does not have, and steps that took much longer than it says. Save the report… writes it as Markdown and PDF to send to them. Such a recording is a test of the guide, so it is never used to build the task’s procedure.

A shared library

Settings → Shared library points Handoff at a folder your team already shares: a synced SharePoint, OneDrive or Dropbox folder, or a network drive. The guides, procedures and handover packs exported there appear in the Library under Shared library, with Follow and Show in Finder, and the search box looks through them too. Exports start in that folder, so publishing a guide to the team is exporting it there. Handoff only reads and writes files in it; nothing goes through a server, because there is none.

Finding a task

The search box at the top of the Library looks through task names, step titles and descriptions, your notes and the text read off screenshots: "remittance" finds every recording where a remittance was mentioned or on screen. Every word you type must be there. Pick a result to open that recording.

Handing over several tasks

Handover pack… in the Library puts the tasks someone is taking over into one folder. Tick the tasks, give the pack a title if you like ("Handover to Sam"), and press Export. The pack starts with an overview: for each task, how long it usually takes, how often it is done (from the dates you recorded it: "Monthly, last done 3 Oct 2026"), the apps it uses and what is needed before starting. Then comes each task’s procedure, or its guide when it has one recording, in its own folder. index.html opens the overview with links to every guide; handover.pdf has the overview and every guide in one document to print or send. A task without a written guide is listed as not included.

If something looks wrong

"In front: unknown on this desktop" while recording: the computer is not telling Handoff which window is active. On a Mac this means Screen Recording is not granted yet; on Linux it happens on Wayland desktops.
No screenshots or zero clicks: on a Mac, check the three permissions in Settings and restart Handoff after granting them.
Ollama not running: open the Ollama app or run ollama serve. On a Mac with Apple Intelligence, Apple’s on-device model writes the guides meanwhile; without either, guides still work with plain step names.
Apple’s on-device model is not offered: it needs macOS 26 or later on Apple silicon, with Apple Intelligence turned on in System Settings; Settings → Local model says which is missing.
Something else: in Settings, under Problems, press Report a problem…. Describe what happened; the screen shows exactly what will be sent (version, system, permissions and the recent log, which you can leave out). Email report opens your own email app with the message ready to send to the developer; nothing is sent until you press Send there. If Handoff closed unexpectedly, the Record tab offers this the next time it opens.
Storage: Settings shows how much space recordings use and where they are kept. To keep them on an external drive, press the drive’s name (or Choose folder…) under Storage, then Move and restart. Handoff copies everything into a Handoff folder there, restarts, and then removes the old copy. If that drive is not connected when Handoff starts, recording is off until you connect it and reopen Handoff. Delete old recordings from the Library; exported guides are copies and are never affected.