kitlangton / scrawl

# 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:
 [code] 
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:
 [code] 
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 --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
 [code] 
## 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),