Skip to content
Back to search

recper

Talk and draw on your screen; your coding agent gets a checklist with annotated screenshots. macOS menu-bar app + MCP server.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/imhalid--recper/badge.svg)](/listings/imhalid--recper)

HTML

<a href="/listings/imhalid--recper"><img src="/api/listings/imhalid--recper/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Download `Recper.zip` from the [latest release](https://github.com/imhalid/recper/releases/latest), unzip it and move `Recper.app` to Applications. The app is ad-hoc signed (not notarized), so the first time, right-click it and choose **Open**, or run `xattr -dr com.apple.quarantine /Applications/Recper.app`.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 279 lines
  1. <div align="center">
  2. <sub>💡 Inspired by <a href="https://x.com/jynniit/status/2123519487257514205">this post</a> · cc <a href="https://x.com/jynniit">@jynniit</a></sub>
  3. <img src="docs/media/logo.png" alt="recper logo" width="112">
  4. # recper
  5. **Talk and draw on your screen. Your coding agent gets a clean checklist with annotated screenshots.**
  6. A tiny macOS menu-bar app for giving visual feedback to coding agents such as Claude Code, Codex or Antigravity.
  7. ![macOS 26+](https://img.shields.io/badge/macOS-26%2B-black?logo=apple)
  8. ![Swift 6](https://img.shields.io/badge/Swift-6-F05138?logo=swift&logoColor=white)
  9. ![MCP](https://img.shields.io/badge/MCP-server-6E56CF)
  10. ![On-device](https://img.shields.io/badge/speech-on--device-2EA44F)
  11. [![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
  12. <img src="docs/media/hero.png" alt="A recper session: numbered marks on a web page, a blurred API key, live captions and the session bar" width="900">
  13. </div>
  14. Instead of typing long descriptions or pasting screenshots one by one, you pick a window, area or screen, say what's wrong
  15. and circle it. recper transcribes your speech on-device, captures screenshots with your marks burned in, binds each
  16. screenshot to the sentence you were saying, and hands the result to your agent as a Markdown file, via the clipboard or over MCP.
  17. It is not a screen recorder: no video, no audio files. Just text, numbered marks and screenshots.
  18. ## How it works
  19. <table>
  20. <tr>
  21. <td width="50%" valign="top">
  22. **1. Pick a target**
  23. Press `⌥⇧R` and choose a window, an area or a whole screen. Everything outside the target is dimmed and the screen
  24. edges light up while you choose.
  25. </td>
  26. <td width="50%"><img src="docs/media/choose.gif" alt="Choosing a window, dragging an area, choosing a screen"></td>
  27. </tr>
  28. <tr>
  29. <td valign="top">
  30. **2. Talk and draw**
  31. Speak naturally; the live caption follows you. Draw with pen, box, ellipse, arrow or blur in six colors. Every mark gets
  32. a number. Press `⌥⇧S` from any app for the radial menu at your pointer: pick a tool, undo, finish, or click the center
  33. for a screenshot.
  34. </td>
  35. <td><img src="docs/media/radial.gif" alt="The radial menu cycling through Cursor, Pen, Box, Arrow, Finish, Undo, Blur and the shutter"></td>
  36. </tr>
  37. <tr>
  38. <td valign="top">
  39. **3. Fix marks in place**
  40. Click a box, ellipse, arrow or blur region to move it or resize it from its edges and corners; `⌫` deletes it.
  41. Blur regions stay readable on screen as an outline and are pixelated only in the screenshot.
  42. </td>
  43. <td><img src="docs/media/edit-marks.png" alt="A selected blur region with resize handles"></td>
  44. </tr>
  45. <tr>
  46. <td valign="top">
  47. **4. Review and send**
  48. Finish with `⌥⇧R` (or say "finish"). Fix sentences, drop screenshots you don't need, then send: the prompt is on your
  49. clipboard and the files are on disk.
  50. </td>
  51. <td><img src="docs/media/review.png" alt="The review screen with sentences and screenshot thumbnails"></td>
  52. </tr>
  53. </table>
  54. ### What your agent gets
  55. Marks are burned into the screenshot with their numbers, and blurred regions are pixelated before anything is written to disk.
  56. <img src="docs/media/result.png" alt="The screenshot an agent receives: numbered marks and a pixelated API key" width="720">
  57. ## Features
  58. - **Pick a target**: window, area or full screen (`⌥⇧R`), with rounded frames and an aurora glow around the screen edges.
  59. - **On-device dictation** with Apple's `SpeechAnalyzer` / `DictationTranscriber`; live captions while you talk; pick the language in Settings.
  60. - **Draw & edit** with pen, box, ellipse, arrow and blur in 6 colors. Move, resize or delete marks until they are captured.
  61. - **Circle gesture**: in cursor mode, circle something with the mouse (without clicking) to drop a numbered ellipse around it.
  62. - **Radial menu** (`⌥⇧S`) at the pointer, from any app: cursor, pen, box, arrow, finish, undo, blur; the center takes a screenshot.
  63. - **Numbered marks**: every mark gets a `#n` badge, and the UI element under it is looked up via Accessibility (role, title, identifier).
  64. - **Screenshots** with a shutter: `Space` / `T` / `⏎` while drawing, the radial menu, or the button in the bar.
  65. - **Voice commands**: "take screenshot", "undo", "finish".
  66. - **Review screen** before sending (optional): edit sentences, inspect screenshots large, remove what you don't need.
  67. - **Sounds**: short synthesized UI sounds (no audio files), with a volume setting.
  68. - **Settings window** for defaults, dictation, shortcuts, permissions, agent setup and storage.
  69. - **Output**: `feedback.md` checklist + `session.json` + `shots/*.png`, and a ready-to-paste prompt on the clipboard.
  70. - **MCP server** (`Recper --mcp`) so agents can read feedback, check off items, and ask you for feedback themselves.
  71. ## Install
  72. Download `Recper.zip` from the [latest release](https://github.com/imhalid/recper/releases/latest), unzip it and move
  73. `Recper.app` to Applications. The app is ad-hoc signed (not notarized), so the first time, right-click it and choose
  74. **Open**, or run `xattr -dr com.apple.quarantine /Applications/Recper.app`.
  75. ## Requirements
  76. - macOS 26 or later, Apple Silicon
  77. - Swift 6 toolchain (Xcode or just the Command Line Tools)
  78. ## Build and run
  79. ```sh
  80. scripts/bundle.sh
  81. open build/Recper.app
  82. ```
  83. `bundle.sh` builds a release binary and wraps it in `build/Recper.app` with an ad-hoc signature.
  84. Optionally run `scripts/dev-cert.sh` once to create a local self-signed signing identity, so macOS permissions
  85. survive rebuilds.
  86. ## Permissions
  87. | Permission | Why |
  88. |---|---|
  89. | Microphone | Live dictation. Audio is never recorded or saved. |
  90. | Speech Recognition | On-device transcription. |
  91. | Screen Recording | Capturing the selected window, area or screen. |
  92. | Accessibility (optional) | Naming the UI element under each mark. |
  93. The Settings window shows the live status of each permission with a button to grant it.
  94. ## Settings
  95. Right-click (or ⌥-click) the menu-bar icon and choose **Settings…** (`⌘,`), or open `recper://settings`.
  96. <img src="docs/media/settings-general.png" alt="Settings: General" width="49%"> <img src="docs/media/settings-shortcuts.png" alt="Settings: Shortcuts" width="49%">
  97. General (default mode, review, auto-capture, sounds, launch at login) · Drawing (default tool and color, circle gesture) ·
  98. Dictation (language, on-screen terms) · Shortcuts · Permissions · Agents & MCP (copyable setup commands) · Storage · About.
  99. ## Shortcuts
  100. | Key | Action |
  101. |---|---|
  102. | `⌥⇧R` | Start / finish a session |
  103. | `1` / `2` / `3` | Target mode: window / area / screen (while choosing) |
  104. | `P` `B` `O` `A` `X` | Pen, box, ellipse, arrow, blur |
  105. | `1`–`6` | Ink color (while drawing) |
  106. | `Space` / `T` / `⏎` | Take a screenshot (while drawing) |
  107. | `⌘Z` | Undo the last mark, edit, deletion, or screenshot |
  108. | `⌫` / `Delete` | Remove the selected mark |
  109. | `Esc` | Deselect a selected mark; otherwise back to the cursor (clicks go to the app underneath) |
  110. | Click & drag a mark | Move a box, ellipse, arrow or blur region; drag its edges, corners or ends to resize |
  111. | Circle with the mouse | In cursor mode (without clicking), drop a numbered ellipse around what you circled |
  112. | `⌥⇧S` | During a session, from any app: radial menu at the pointer; click an item, or the center for a screenshot. Click outside, `Esc` or `⌥⇧S` closes it |
  113. | `⌥⇧V` `P` `B` `O` `A` `X` `Z` | During a session, from any app: cursor, pen, box, ellipse, arrow, blur, undo |
  114. | `⌘⏎` / `Esc` (Review) | Send (save & copy prompt) / save without copying |
  115. ### Drawing cursors
  116. Each tool has its own cursor with an exact hot spot and the current ink color, readable on light, dark and busy backgrounds.
  117. <img src="docs/media/cursors.png" alt="Drawing cursors for every tool on light, dark and gradient backgrounds" width="720">
  118. ## Output
  119. Each session is saved to `~/.recper/sessions/<timestamp>/`:
  120. ```
  121. feedback.md session.json shots/01.png 02.png ...
  122. ```
  123. `feedback.md` is a checklist of what you said, with screenshots attached to the sentence they belong to:
  124. ```markdown
  125. # Feedback — 2026-11-20 15:42
  126. - [ ] 1. This button's padding is too large, shrink it a bit. [00:07]
  127. ↳ drawn while speaking: #1 (screenshot 1)
  128. ![1](shots/01.png) — #1 box (10,20)–(110,60) → AXButton "Save"
  129. - [ ] 2. The logo in the header is shifted left, center it. [00:15]
  130. ```
  131. `session.json` holds the same data for machines: segments with timings, screenshots and mark coordinates.
  132. ## MCP
  133. Register the server with your agent, for example Claude Code:
  134. ```sh
  135. claude mcp add recper -- /path/to/Recper.app/Contents/MacOS/Recper --mcp
  136. ```
  137. | Tool | What it does |
  138. |---|---|
  139. | `get_feedback` | Returns the latest (or a given) session: checklist text plus downscaled screenshots and mark summaries. |
  140. | `list_sessions` | Lists recent sessions with duration, screenshot count, done/total items and the first sentence. |
  141. | `mark_done` | Checks off (or unchecks) an item in `feedback.md`. |
  142. | `request_feedback` | Opens recper on your screen (via `recper://start`), optionally with a question, and waits until you finish. |
  143. ## Privacy
  144. Everything stays on your Mac. Speech is transcribed on-device, audio is never stored, and recper makes no network
  145. requests. Blurred regions are blurred in the pixels before a screenshot is written to disk.
  146. ## Tests
  147. ```sh
  148. scripts/test.sh
  149. ```
  150. ## Performance
  151. recper is small and stays out of the way: it does nothing while idle, and its heavy work (burning marks into a
  152. screenshot) takes a few tens of milliseconds.
  153. ### Size
  154. | | Size |
  155. |---|---:|
  156. | Recper.app | 2.0 MB |
  157. | Recper.zip (download) | 838 KB |
  158. | Swift source | 11.4k lines |
  159. | Tests | 40 |
  160. No dependencies: AppKit, SwiftUI, ScreenCaptureKit, Speech and AVFoundation only. No audio or image assets; sounds are synthesized.
  161. ### Runtime
  162. | State | CPU | Memory |
  163. |---|---:|---:|
  164. | Idle in the menu bar | 0.0 % | 10 MB |
  165. | Choosing a target (edge glow on) | 9.8 % | 21 MB |
  166. | Idle again after cancelling | 0.0 % | 22 MB |
  167. Process start after `open`: ~90 ms. Animations run only while their window is on screen, and the sound engine
  168. stops 3 s after the last sound.
  169. ### Hot paths (median)
  170. | Operation | Input | Time |
  171. |---|---|---:|
  172. | Compose screenshot | 1800×1200, 5 marks + 1 blur region | 32.4 ms |
  173. | Write PNG | 1800×1200 | 15.8 ms |
  174. | Write `feedback.md` | 60 sentences, 25 screenshots | 0.19 ms |
  175. | Circle gesture detector | per mouse-move event | 12–15 ns |
  176. | Draw a tool cursor | 2× Retina, first use (cached after) | 0.36 ms |
  177. | Synthesize a UI sound | 3 voices, 48 kHz stereo | 0.14 ms |
  178. _Measured on an Apple M1 (16 GB), macOS 26.6. Reproduce with:_
  179. ```sh
  180. scripts/bench.sh # sizes, runtime CPU/memory and hot paths (relaunches recper)
  181. build/Recper.app/Contents/MacOS/Recper --benchmark # hot paths only
  182. ```
  183. ## Roadmap
  184. - Optional local Whisper model for speech recognition
  185. - Linux support
  186. - Short motion clips alongside screenshots
  187. ## README media
  188. The images above are rendered from synthetic scenes (no screen capture, no personal data):
  189. ```sh
  190. $(swift build -c release --show-bin-path)/Recper --render-media docs/media
  191. ```
  192. ## Credits
  193. The UI sounds follow the sound design of [chuanqisun/spaceship](https://github.com/chuanqisun/spaceship) (MIT License, © 2026 Sun).
  194. ## License
  195. [MIT](LICENSE)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.