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 15 or later (live transcription and Liquid Glass need macOS 26). 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.

On Windows 10 (2004) or later (x64), download the zip from the same page or the latest GitHub release, unzip it and run scrawl.exe. The Windows build is a preview and isn't signed yet, so Windows may say "Windows protected your PC": click More info, then Run anyway. It doesn't update itself yet; see Windows.

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", or --mark 2 for the mark the text shows as ✎②; scrawl inspect --marks lists them) 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 (press ⌥⇧S 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

# Build a capture whose build never ran (the app died first), in place; the app does this at launch
cargo run -- recover ~/Library/Application\ Support/scrawl/captures/scrawl-….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.

Permission	Used for	When it's asked for
Screen & System Audio Recording	Recording the screen (ScreenCaptureKit)	onboarding, required
Microphone	Your narration	onboarding, required
Accessibility ("Device Control and Data Access" on macOS 27)	The key event tap (⌘Z, Esc, ⌘-shortcuts in the window log), and ⌥⇧V and the Paste chip, which post ⌘V into the app in front	onboarding, required
Camera	The cabled iPhone mirror (macOS treats it as a camera)	the first time you pick iPhone

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 whether ⌥⇧ is still held after ⌥⇧S 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.

This is the beginning of the README. Read the rest at the original. Read the full README ↗