# Scrawl records your screen and narration so a coding agent can see the problem

> Scrawl is a MIT licensed macOS app that records the screen, your voice and your drawn marks into a bundle of keyframes, a transcript, a timeline and a manifest, and it ships a skill that lets Claude Code, OpenCode or Codex read that bundle. It suits a developer who can demonstrate a bug faster than they can describe it, and it needs macOS 26 on Apple silicon, with a Windows build that is a preview and not signed.

**kitlangton/scrawl** — Show an agent a problem: mark up, record, send

- Repository: https://github.com/kitlangton/scrawl
- Website: https://scrawl.kitlangton.com
- Stars: 714 · Forks: 71
- Language: Rust
- License: MIT
- Published: 2026-10-22 · Updated: 2026-10-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/kitlangton-scrawl

## A shortcut, a recording, and a bundle of files

Scrawl's one line summary is that you show an agent a problem instead of describing it. The mechanics are a keyboard shortcut and a stop key.

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 with four parts: a contact sheet of annotated keyframes called contact-sheet.png, individual full resolution keyframes under frames/ named frame-XX.png, a time aligned transcript and interaction timeline called summary.md, and a structured manifest called scrawl.json.

That bundle design is the core idea. Rather than handing an agent a video file, which a model cannot read directly, Scrawl produces a set of images with a text layer attached, and a transcript that points at moments in them. The transcript and the images are the same evidence, indexed two ways.

The repository is a Rust project with a Cargo.toml at version 0.3.10, edition 2024, licensed MIT, with the default run target set to scrawl. The tree is broader than a single binary: Sources/ and src/ for the code, helper/ for the privileged side, video/, perf/ for performance work, skills/ for the agent skill, site/ for the website, and a Package.swift, which is how a Rust project ends up with a Swift file in it, namely the macOS app target.

## Installing on a Mac, and the Windows preview you should think twice about

Scrawl needs an Apple silicon Mac on macOS 26 or later. The install is a DMG from the project site, or Homebrew.

```sh
brew install --cask kitlangton/tap/scrawl
```

The app updates itself through Sparkle, so Homebrew leaves updates to it, which is the arrangement the documentation asks for: the Homebrew cask is an install, not an update channel.

On Windows the story is different and the documentation is upfront about it. On Windows 10, version 2004 or later, x64, you download the zip from the same page or from 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, and the instruction is to click More info, then Run anyway. It does not update itself yet.

The Cargo manifest shows why the two platforms differ so much. The macOS dependency block is the long one: screencapturekit pinned to 11.0.0 with the macos_15_0 feature, objc2 and the objc2-app-kit family, core-foundation, core-graphics, core-text, core-video, metal, block2, and gpui with the font-kit feature. The Windows block is different in kind: the windows crate with the Graphics_Capture and Direct3D11 features, lyon for vector drawing, ab_glyph for fonts, raw-window-handle, tray-icon, sha2, and transcribe-cpp pinned to 0.2.4.

So the Windows build does not reuse the macOS capture path, it has its own graphics capture and its own transcriber binding, and the documentation marks the result as a preview.

## The command line is the real interface

The scrawl command is the binary inside Scrawl.app, and the usage section is a list of what the agent or the developer can do with a bundle. The commands run under cargo run -- in the repository, and the binary does the same thing once installed.

```sh
# 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
```

The rest of the list covers the operations that matter when you are debugging with an agent.

```sh
# 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_...
```

There is also a routing command, `scrawl route --url http://localhost:5173/`, which answers which session a capture of a dev site would go to without sending it, and a set of device commands, `scrawl record --iphone --duration 8` and `scrawl devices`, for capturing a cabled iPhone as a mirror window plus native video.

Maintenance commands are there too: `scrawl reprocess latest --out /tmp/again.scrawl` rebuilds an existing bundle with the current transcriber and keyframe rules, `scrawl autocrop latest --serve --open` tunes auto crop live, `scrawl export latest --zoom --out /tmp/demo.mp4` produces a shareable video with the crop applied and the ink burned in, and `scrawl clean --dry-run` and `scrawl pin latest` manage retention, with the app doing the daily cleanup itself.

## The agent skill turns a bundle into a conversation

The part that makes this an agent tool rather than a screen recorder is the skill, and it is installed the same way other agent skills are.

```sh
bunx skills add kitlangton/scrawl
```

That works for Claude Code, OpenCode, Codex and other agents. The `scrawl` command itself is the binary inside Scrawl.app, and the Homebrew cask links it onto your PATH, or you 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 installed, the described behaviour is that 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. The specific look-closer commands are `scrawl zoom <bundle> --at 0:12`, or `--at "a phrase you said"`, or `--mark 2` for the second mark the text shows, while `scrawl inspect --marks` lists them. Then `scrawl zoom` 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, which is the sensible first command to run.

The design detail worth noticing is the phrase to look closer. A contact sheet is dense, so the agent does not read it as a human would; it is told to zoom into a moment, pull a range of frames, or open a specific mark. The tool is built around an agent's need for targeted, cheap views rather than a single large artefact.

## Permissions, and the parts macOS makes you click through

On first launch Scrawl opens a welcome window with four screens: a welcome, how the shortcut works, one screen with every permission it 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, because the window re-reads the grants every half second.

The permission table is worth reading because it explains the design.

| 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 |

Two of the design decisions are unusual. Scrawl never asks for Input Monitoring, because clicks, drags and scrolls in other apps come from an AppKit global mouse monitor, NSEvent.addGlobalMonitorForEvents, which needs no permission, and the shift key for ink and the state of the option-shift chord come from polled modifier flags, which need none either. Key presses do come from an active event tap, which Accessibility allows.

The other is that Screen Recording and Accessibility are lists you drag an app into, so their button skips Apple's prompt and opens the pane in System Settings instead, with a card that flies from the button to just below the Settings window. The row drags the Scrawl.app that contains the helper, because that is the bundle macOS grants.

Until the required permissions are on, the shortcut starts nothing, so no picker or overlay can sit over a macOS prompt. Once the keys are released it brings the permissions window forward.

## What the release cadence says about where the work is going

The listed releases are v0.3.10 on 2026-10-20, v0.3.9 the same day, and v0.3.8 also on 2026-10-20. The last push was on 2026-10-20, and the repository is not archived.

Three releases in one day is not a coincidence of scheduling, it is a statement about where the effort is. A screen recorder that packs keyframes and a transcript needs a transcriber, a keyframe selection rule and a crop policy, and all three of those change as you look at real recordings. The `scrawl reprocess` command exists precisely because of that: you can rebuild an existing bundle with the current transcriber and keyframe rules rather than re-recording.

The Cargo dependencies support the same picture. anyhow, clap and serde for the command line and serialisation, cpal for audio capture and playback, hound for WAV handling, png for image encoding, flume for channels, dirs for paths, and libc for the platform calls. The gpui dependency appears in both the macOS and Windows blocks, which is the windowing and review interface shared across the two, while metal and core-graphics are what the macOS build uses to draw.

The build.rs and Package.swift in the tree are how the Rust core and the native macOS app are assembled into one bundle, and the helper/ directory is the privileged side that lets the app draw its overlay and post a paste into the app in front.

The AGENTS.md and CONTEXT.md at the root are the working notes for an agent that contributes to the project, which fits a project whose entire premise is agents.

## Conclusion

Scrawl fits a developer working with a coding agent on a bug that is easier to show than to describe, since the bundle gives the agent a contact sheet, a transcript and full resolution keyframes instead of a paragraph of description. It does not fit a Linux user, because the app targets macOS 26 and later on Apple silicon, and the Windows build is a preview that is not signed and does not update itself. Before adopting it, confirm the machine can run macOS 26 on Apple silicon, grant Screen Recording, Microphone and Accessibility during onboarding, and read the agent skill first, because the workflow assumes the agent knows how to zoom into a bundle and pull frames around a moment.

## FAQ

### What does Scrawl record and what does it produce?

It records the screen, your voice and your marks, and packs them into a bundle with a contact sheet of annotated keyframes, individual full resolution keyframes, a time aligned transcript and interaction timeline, and a structured manifest.

### How do I install Scrawl on macOS?

You need an Apple silicon Mac on macOS 26 or later. Download the DMG from the project site, or use Homebrew with brew install --cask kitlangton/tap/scrawl. The app updates itself through Sparkle, so Homebrew only handles the install.

### How does a coding agent read a Scrawl capture?

You install the skill with bunx skills add kitlangton/scrawl, then the agent reads the contact sheet and transcript, opens the keyframes the narration points at, and uses commands like scrawl zoom, scrawl frames and scrawl inspect --marks to look closer at a moment.

### Is the Windows version of Scrawl ready for daily use?

Not according to the documentation: the Windows build is a preview and isn't signed yet, so Windows may show a protected your PC warning, and it does not update itself yet. The macOS build is the supported one.

## Sources

- [kitlangton/scrawl on GitHub](https://github.com/kitlangton/scrawl)
- [License: MIT](https://github.com/kitlangton/scrawl/blob/main/LICENSE)
- [Project website](https://scrawl.kitlangton.com)
- [README](https://github.com/kitlangton/scrawl/blob/main/README.md)
- [Releases](https://github.com/kitlangton/scrawl/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/kitlangton-scrawl