Skip to content
ocrogramocrogram
ocrogram
macOS

ocrogram

Take a screenshot. Paste the text.

A set-and-forget Mac background tool. Install it, run ocrogram start, leave it on as a login item. After that, a normal macOS screenshot puts the text on the clipboard.

install
brew install joelpeckham/ocrogram/ocrogram
ocrogram start

Source on GitHub

How it works

Private, on-device, macOS only.

01Watches screenshots

The daemon watches the folder from your macOS screenshot location. A normal screenshot is enough.

02Reads with Apple Vision

A local helper runs on-device OCR. Nothing is uploaded. Text never leaves your Mac.

03Lands on the clipboard

The recognized text is copied automatically. Cmd+V pastes it anywhere.

Requirements

Check these before you run brew.

  1. 01macOS 14 Sonoma or later

    The Swift helper targets macOS 14 so it can use Apple Vision with language correction and automatic language detection.

  2. 02Homebrew

    ocrogram ships as a tap formula: brew install joelpeckham/ocrogram/ocrogram. Homebrew 6 asks you to trust third-party tap formulas the first time.

  3. 03Xcode Command Line Tools with Swift 6

    The formula builds from source. Homebrew pulls Go in as a build dependency. You need a Swift 6 toolchain from Xcode or the Command Line Tools for your macOS version.

  4. 04A screenshot that writes a file

    Cmd+Shift+3 and Cmd+Shift+4 work. Clipboard-only shortcuts (Cmd+Ctrl+Shift+3 / 4) never write a file, so ocrogram ignores them.

Install

Two commands. Then a normal screenshot.

install
brew install joelpeckham/ocrogram/ocrogram
ocrogram start

  1. 01Confirm the Command Line Tools

    Run xcode-select -p. If that fails, install the Command Line Tools with xcode-select --install. If Homebrew later says Xcode is outdated, update Xcode or the CLT for your macOS, or remove a leftover /Applications/Xcode.app so Homebrew can use the CLT.

  2. 02Install ocrogram with Homebrew

    Run brew install joelpeckham/ocrogram/ocrogram. That taps joelpeckham/homebrew-ocrogram, compiles the Go CLI and Swift helper from source, and puts ocrogram and ocrogram-helper on your PATH.

  3. 03Start the login item

    Run ocrogram start. That writes a LaunchAgent at ~/Library/LaunchAgents/com.joelpeckham.ocrogram.plist and bootstraps it with launchctl so the daemon starts now and at every login.

  4. 04Take a normal screenshot

    Use Cmd+Shift+3 for the whole screen or Cmd+Shift+4 for a region. Wait a beat while the file settles and Apple Vision runs.

  5. 05Paste the text

    Cmd+V in any app. The recognized text is already on the clipboard. Nothing is uploaded.

Commands

ocrogram start
Install and start the login item
ocrogram stop
Stop and remove the login item
ocrogram daemon
Background watcher. launchd runs this; you usually do not.
ocrogram version
Print the installed version. --version and -v work too.

ocrogram start writes ~/Library/LaunchAgents/com.joelpeckham.ocrogram.plist and bootstraps LaunchAgent com.joelpeckham.ocrogram. launchd runs ocrogram daemon at login. Logs go to ~/Library/Logs/ocrogram.log.

The formula lives in joelpeckham/homebrew-ocrogram. Homebrew 6 asks you to trust third-party tap formulas. To build latest main instead of the last release:

brew install --HEAD joelpeckham/ocrogram/ocrogram

Troubleshooting

Most failures are a folder the daemon cannot read, or a screenshot that never wrote a file.

Nothing lands on the clipboard

The daemon could not read the screenshot folder. If that folder is Desktop, grant Full Disk Access to /opt/homebrew/bin/ocrogram (Apple silicon) or /usr/local/bin/ocrogram (Intel), then run ocrogram stop && ocrogram start. Or point screenshots at a folder you own — see the screenshot location guide.

Homebrew says Xcode is outdated

The formula compiles from source. Update Xcode or the Command Line Tools to the version for your macOS. If an old /Applications/Xcode.app is sitting around after you switched to the CLT, remove it so Homebrew can find the tools it wants.

I used Cmd+Ctrl+Shift+3 or 4

Those shortcuts copy a screenshot to the clipboard and never write a file. ocrogram watches the filesystem, so it ignores them. Use Cmd+Shift+3 or Cmd+Shift+4 instead.

I renamed the screenshot and it took a few seconds

Default localized names (Screenshot, Bildschirmfoto, 截屏, and the rest) match immediately. A custom name waits until Spotlight sets kMDItemIsScreenCapture. ocrogram retries for a couple of seconds.

I need to see what the daemon is doing

launchd writes stdout and stderr to ~/Library/Logs/ocrogram.log. Open that file after a failed screenshot. There is no status command.

It says it is already running

A lock file at ~/Library/Application Support/ocrogram/daemon.lock keeps a second daemon from starting. If a previous process died badly, run ocrogram stop, delete that lock if it is still there, then ocrogram start.

I want the latest main, not the last release

Run brew install --HEAD joelpeckham/ocrogram/ocrogram. That still builds from source.

If Desktop is locked down, point screenshots at a folder you own:

mkdir -p ~/Pictures/Screenshots
defaults write com.apple.screencapture location ~/Pictures/Screenshots
killall SystemUIServer

Step-by-step: change the Mac screenshot save location.

FAQ

Short answers. Source of truth is the repo.

Does ocrogram upload my screenshots?

No. Apple Vision runs on your Mac. The helper never sends the image or the text to a server.

Which languages does it recognize?

Apple Vision detects the language automatically and applies language correction. Whatever Live Text can read, ocrogram can read.

How much does it cost?

Nothing. ocrogram is free and MIT-licensed. The source is on GitHub.

Does it work on Intel Macs?

Yes, if the Mac can run macOS 14. Homebrew builds from source for your architecture. There is no bottled binary.

Does it work with CleanShot, Shottr, or other screenshot apps?

Yes, if that app writes an image file (.png, .jpg, .jpeg, .heic, .tiff) into the folder macOS uses for screenshots. ocrogram watches that folder, not a specific app.

Do I need Screen Recording or Accessibility permission?

No. ocrogram never captures the screen. It watches files after macOS (or another tool) writes them. The permission that sometimes matters is Full Disk Access, and only if the screenshot folder is Desktop.

How do I uninstall it?

Run ocrogram stop, then brew uninstall ocrogram. That removes the LaunchAgent and the binaries.

Guides

Screenshot OCR questions people actually type.