User guide

Everything FlowShelf does, and how to use it.

This guide is written from the current app code, not a generic feature list. Use it to set up FlowShelf, learn the shortcuts, and find the exact place each tool lives.

Download for macOS Start with setup
Setup

Quick start

1

Install FlowShelf

Download the DMG, drag FlowShelf into Applications, then open it from Applications. It lives in the menu bar, so you will not see a normal Dock app window.

2

Open the shelf

Click the FlowShelf menu-bar icon to open the compact shelf. Right-click or Control-click the same icon for the app menu with Dashboard, Shelf, snippet shortcuts, and Quit.

3

Grant permissions only when needed

Clipboard and basic shelf features work immediately. Window snapping, window switching, and Dock previews need Accessibility. Live thumbnails need Screen Recording.

Main workspace

Shelf & clipboard history

The shelf is the center of FlowShelf. It collects copied text, links, images, screenshots, and dragged files so you can reuse them without hunting through apps.

Capture clipboard items

When “Record clipboard history” is on, copied text, links, and supported images are saved automatically unless the source app is excluded.

Use the menu-bar shelf

Click the menu-bar icon, search “today’s shelf,” filter by Today, Pinned, Shots, Files, Links, or Text, then click an item to copy it back to the clipboard.

Use the floating shelf

Press ⌘⇧S or enable mouse shake in Settings. Drop files, images, links, or text into the floating panel, then click or drag items back out.

Keep important items

Hover an item and click the pin icon, or use the context menu. Pinned items do not expire. Unpinned items clear after 24 hours unless you switch retention to Permanent.

Useful context menu actions: Copy, Open, Reveal in Finder, Pin, Remove, Annotate image, Pin image to Screen, Run OCR, Scan QR Code, Combine images, and Before / After GIF.
Screenshot studio

Capture, OCR, annotate, and reuse screenshots

Region screenshot

Press ⌘⇧7 or click the screenshot button in the menu-bar shelf. Select a region with the macOS crosshair. If annotation is enabled, the editor opens automatically.

Screenshot + OCR

Press ⌘⇧O. FlowShelf captures the selected region, runs local Apple Vision OCR, saves the recognized text to the shelf, and copies the text to the clipboard.

Window capture

Open the menu-bar shelf and click the window-capture button. Choose a window and FlowShelf captures it without the macOS drop shadow.

Annotate an existing image

Right-click any image or screenshot on the shelf and choose “Annotate…”. The same editor opens without needing to recapture the screen.

Annotation tools

ArrowArrow, line, or double-ended arrow.
BoxOutline, filled, rounded rectangle, or ellipse.
HighlightMarker-style freehand highlight or block highlight.
StepNumbered badges or A/B/C badges for tutorials.
BlurPixelate, blur, or solid redaction for sensitive areas.
SpotlightDim the screenshot while keeping a rectangle or ellipse visible.
TextSmall, Medium, Large, and XL text labels.
CropFree crop, 1:1, 16:9, or 4:3 crop ratios.
RulerMeasure length or width × height in pixels.
MagnifySelect an area and place a zoomed callout over the screenshot.
Export options: choose a backdrop, then Pin, Save, Add to Shelf, or Copy. Undo and redo are available with ⌘Z and ⇧⌘Z in the editor.
Reusable text

Snippets

Snippets are reusable pieces of text such as signatures, addresses, canned replies, and code blocks.

  1. Open the Dashboard with ⌘⇧D or the App button in the shelf.
  2. Go to Snippets and click New.
  3. Add a title, optional keyword, and the text content.
  4. Click a snippet row or copy button to put it on the clipboard.
  5. Right-click the menu-bar icon and use Copy Snippet for quick access to your first 20 snippets.
Window workflow

Peek, switch, and snap windows

Dock previews

In Settings, enable “Show window previews when hovering Dock icons.” FlowShelf lists app windows and shows live thumbnails when Screen Recording works.

Option-Tab switcher

Enable the window switcher, then hold ⌥ and press Tab. Use ⌥⇧Tab or arrows to move, release Option or press Return to switch, and Esc to cancel.

Window snapping

Enable snapping in Settings. Hold ⌃⌥ and press arrows for halves, U I J K for corners, Return to maximize, or C to center.

Notch shelf

Enable the notch shelf in Settings. It appears in the MacBook notch or as a top-center pill on external displays. Expand it and drop files, images, or text into it.

Uninstall helper

App cleaner

The Clean tab helps uninstall an app and find related leftovers. FlowShelf moves selected files to Trash, so you can restore them with Put Back if needed.

  1. Open Dashboard, then choose Clean.
  2. Drop a .app file into the cleaner, or click Choose App.
  3. Review the grouped files: app bundle, preferences, caches, Application Support, containers, and group containers.
  4. Low-confidence matches are unchecked by default. Review them before selecting.
  5. Click Move to Trash. If any files cannot be moved, FlowShelf shows them, labels the likely reason, and adds a cleanup report to the shelf.
Important: built-in macOS apps and protected system files cannot be removed by FlowShelf. Some user Library files need Full Disk Access; some system Library files need admin removal.
Private AI

On-device AI

FlowShelf uses Apple Intelligence / Foundation Models when available. AI actions are explicit: the app does not constantly run a model in the background.

Ask AI

Open Dashboard → Shelf and click Ask AI. It answers using shelf items and snippets as context.

Summarize day

Click Summarize day to get a friendly recap of collected text from today’s shelf.

Item actions

Right-click text, OCR, link, or cleaner report items for Summarize, Clean up, Smart title, Reply, Explain, Make formal, Make casual, Bullet points, Translate, or Custom.

Auto-title

Settings includes “Auto-title new text items.” It is off by default because it runs AI during capture and can use more battery/RAM.

Control

Privacy, storage, and settings

Private Mode

Click the eye button in the menu-bar shelf or enable Private mode in Settings. Clipboard capture pauses until you turn it off.

Excluded apps

Settings includes excluded bundle IDs. Copies from those apps are never recorded. Common password managers are excluded by default.

Retention

Default retention is 24 hours. Switch to Permanent if you want a full clipboard history, but clean it manually over time.

Updates

Settings includes Check for Updates. FlowShelf uses Sparkle for update checks.

Reference

Shortcuts

Open shelf search⌘⇧V
Show floating shelf⌘⇧S
Screenshot region⌘⇧7
Screenshot + OCR⌘⇧O
Open dashboard⌘⇧D
Window snapping halves⌃⌥ ← → ↑ ↓
Window snapping corners⌃⌥ U I J K
Window maximize / center⌃⌥ Return / C
Window switcher⌥Tab