Scrawl

Show an agent a problem instead of describing it.

Press a shortcut (⌥⇧S) and Scrawl starts recording the screen. Talk, click around, draw on it, and press ⌥⇧S again to finish. Scrawl records the screen, your voice, and your marks, then packs them into a compact bundle: a contact sheet of annotated keyframes (contact-sheet.png), individual full-resolution keyframes (frames/frame-XX.png), a time-aligned transcript and interaction timeline (summary.md), and a structured manifest (scrawl.json).

Install

Scrawl needs an Apple silicon Mac on macOS 26 or later. Download the DMG from scrawl.kitlangton.com, or use Homebrew:

brew install --cask kitlangton/tap/scrawl

The app updates itself (Sparkle), so Homebrew leaves updates to it.

Agents

Install the agent skill for Claude Code, OpenCode, Codex and other agents:

bunx skills add kitlangton/scrawl

The scrawl command is the binary inside Scrawl.app. The Homebrew cask links it onto your PATH, or click Install beside Command-line tool in Settings › Agents, which links it into /opt/homebrew/bin or /usr/local/bin when you can write there, else ~/.local/bin. The link always runs the app's current copy, so it updates with the app.

With the skill, an agent that gets a Scrawl paste reads the contact sheet and transcript, opens the keyframes the narration points at, and uses the command to look closer: scrawl zoom <bundle> --at 0:12 (or --at "a phrase you said") makes a dense sheet of frames around a moment, scrawl frames pulls a range, scrawl send queues a capture into an OpenCode session, and scrawl export makes a shareable .mp4. scrawl skill prints the skill without installing anything.

Usage

# Launch the GPUI menu-bar and review app (tap ⌥⇧S to record, hold it to choose what to record)
cargo run -- app

# Generate a realistic multi-frame demo bundle and print its agent summary
cargo run -- demo --out /tmp/demo.scrawl

# Open a bundle (or `latest`) in the native GPUI review window
cargo run -- preview /tmp/demo.scrawl

# Print the agent summary or JSON manifest for a bundle
cargo run -- inspect /tmp/demo.scrawl
cargo run -- inspect /tmp/demo.scrawl --json

# Extract frames in a time window for an agent to look closer
cargo run -- frames /tmp/demo.scrawl --from 0:02 --to 0:07

# Copy contact-sheet.png + summary.md to the clipboard or send to OpenCode V2
cargo run -- send /tmp/demo.scrawl --clipboard
cargo run -- send /tmp/demo.scrawl --session ses_...

# Which session a capture of a dev site would go to (without sending)
cargo run -- route --url http://localhost:5173/

# Capture a cabled iPhone for 8 seconds from the terminal (mirror window + native video)
cargo run -- record --iphone --duration 8
cargo run -- devices

# Build a bundle from a ScrawlKit in-app recording (newest pair in ~/Downloads by default)
cargo run -- import
cargo run -- import ~/Downloads/20261013T164000.mp4 --timeline ~/Downloads/20261013T164000.json

# Rebuild an existing bundle with the current transcriber and keyframe rules
cargo run -- reprocess latest --out /tmp/again.scrawl

# Tune auto-crop on a Screen capture, live
cargo run -- autocrop latest --serve --open

# Export a bundle as a shareable .mp4 (crop to the activity, ink burned in, audio; --zoom for auto-zoom)
cargo run -- export latest --zoom --out /tmp/demo.mp4

# Clean up old captures now (the app does it daily), or keep one forever
cargo run -- clean --dry-run
cargo run -- pin latest

Welcome and permissions

On first launch Scrawl opens a welcome window with four screens: a welcome, how ⌥⇧S works, one screen with every permission Scrawl needs, and a first capture. Each permission is a row with a button that shows the macOS prompt (or, once asked, opens System Settings) and a check that appears by itself when macOS grants it (the window re-reads the grants every 0.5 s). Screen Recording is first and its button is filled in; after that the next row's button is. Grant them in any order; Continue unlocks once all three are on, and the screen is skipped when they already are.

Scrawl never asks for Input Monitoring. Clicks, drags and scrolls in other apps come from an AppKit global mouse monitor (NSEvent.addGlobalMonitorForEvents), which needs no permission; ⇧ for ink and the switcher's held ⌥⇧ come from polled modifier flags, which need none either; key presses come from an active event tap, which Accessibility allows. macOS applies an Accessibility grant to a running app at once (System Settings shows no "Quit & Reopen" for it), and Scrawl makes the tap within half a second of it.

Screen Recording and Accessibility are lists you drag an app into, so their button skips Apple's prompt: it opens the pane in System Settings, and a card flies from the button to just below the Settings window (or, with no room on screen there, over the window's empty lower area), with its Scrawl row lined up under the list. Drag that row into the list. The card follows the window, steps aside when another app is in front, and shows "Scrawl is allowed" once a fresh process sees the grant (a drop alone proves nothing). The row drags the Scrawl.app that contains the helper, the bundle macOS grants. With Reduce Motion on, the card fades in place. Microphone and Camera can't be dragged in, so they use the macOS prompt.

Camera is asked for in the same window, with just its row, when first needed. Speech recognition isn't asked for: SpeechAnalyzer transcribes without it. The ⌥⇧S and ⌥⇧V hotkeys themselves need no permission (Carbon RegisterEventHotKey).

Until the required permissions are on, ⌥⇧S starts nothing (no switcher, picker or overlay that could sit over a macOS prompt): once the keys are released it brings the permissions window forward.

A Screen Recording grant may not reach a running app, and macOS offers Quit & Reopen or Later as soon as it's granted. Either way nobody reopens Scrawl by hand. If you pick Quit & Reopen, macOS restarts Scrawl and the tour opens on the permissions screen again, Screen Recording checked. If you pick Later (or nothing), Scrawl checks whether it can capture anyway (a one-frame ScreenCaptureKit screenshot, tried only once a fresh helper reports the grant), and if it can't, the row shows "Reopening Scrawl" for a second and Scrawl relaunches itself into the same screen. It only does that once in two minutes (relaunchedAt in the config); if a fresh copy still can't capture, the row's button becomes Reopen Scrawl. The relaunch waits for this copy to exit and opens the app without -n, so if macOS's Quit & Reopen got there first there's still one Scrawl. scrawl sck-probe [--watch SECONDS] and scrawl-helper sck-probe try the same capture from the command line.

Progress is "onboarding" in ~/.config/scrawl/config.json, including the screen the tour is on, so it picks up there whatever quits Scrawl. Once seen, the tour only comes back from Welcome tour in Settings › About, but a required permission that was granted and is gone again reopens the permissions screen at launch. SCRAWL_NO_ONBOARDING=1 skips it.

To replay it from scratch:

tccutil reset All dev.kitlangton.scrawl
jq 'del(.onboarding)' ~/.config/scrawl/config.json > /tmp/c.json && mv /tmp/c.json ~/.config/scrawl/config.json
# then quit and reopen Scrawl

Preview every screen without the app, including the permissions screen with none, some and all granted and each on-demand sheet: target/debug/scrawl-helper onboarding --render /tmp/onboarding --icon assets/app-icon.png.

Settings

Settings… in the menu bar (⌘, while the menu is open) opens a small window with six panes:

• General: Launch at login, Send dev-site captures to OpenCode, and the two shortcuts, Record (⌥⇧S) and Paste last capture (⌥⇧V).
• Recording: the microphone, with its input level, the transcriber (Apple Speech, or Hex while it runs, with its model) and, under Experimental, Video export.
• Storage: how long recordings are kept, how much space the captures take, and Show in Finder.
• Permissions: the onboarding checklist, so a permission can be turned on later.
• Agents: Install or Uninstall the scrawl command (see Agents), and the skill's install command with Copy. A scrawl that belongs to another program is left alone.
• About: the version, Check for Updates…, links, and the welcome tour.

To change a shortcut, click its keys and press the new combination; Esc cancels. It needs ⌘, ⌥ or ⌃ (a function key can stand alone), and Scrawl turns down ⌘ with one key, combinations macOS uses, the other Scrawl shortcut, and anything another app has already taken. The arrow beside the heading puts the default back. While the recorder listens, Scrawl's own shortcuts are paused. They are saved as "shortcuts" in ~/.config/scrawl/config.json. The menu keeps Record Screen, Choose What to Record…, Open Latest Capture, Export Last Capture as Video… (when on), Settings…, Check for Updates… and Quit.

Microphone lists the connected inputs, with System default first, which follows whatever macOS uses as it changes. The list updates as devices are plugged in or out. A chosen device is saved by its CoreAudio UID as "microphone": {"id", "name"}; if it isn't connected when you record, Scrawl records from the default instead and says so under