MarkuprPlus

<p align="center"> <img src="src/renderer/assets/logo.svg" alt="MarkuprPlus" width="80" height="80"> </p> <h1 align="center">MarkuprPlus</h1> <p align="center"> <strong>You see it. You say it. Your AI fixes it.</strong> </p> <p align="center"> <strong>A Windows and macOS desktop app, CLI, and MCP server for visual feedback.</strong><br> Record and annotate from your desktop, process recordings from the terminal, or give your AI agent screen capture tools. </p> <p align="center"> <a href="https://github.com/hashfunction/MarkuprPlus/releases/latest"><strong>Download for Windows or macOS</strong></a> &middot; <a href="#cli">Use the CLI</a> &middot; <a href="#mcp-server">Connect an MCP client</a> &middot; <a href="markuprx-action/README.md">GitHub Action</a> </p> <p align="center"> <a href="marketing-video/markuprplus-explainer-v10b-four-step-tour-natural-agent.mp4"> <img src="docs/images/markuprplus/product-tour-v10-poster.png" alt="Watch the 33-second MarkuprPlus product tour" width="900"> </a> </p> <p align="center"> <a href="marketing-video/markuprplus-explainer-v10b-four-step-tour-natural-agent.mp4"><strong>▶ Watch the 33-second product tour</strong></a> </p> <p align="center"> Pick a window. Talk through what's wrong. Circle it while it happens.<br> Every circle becomes its own issue, with its own screenshot, ready to paste into your coding agent. </p> <p align="center"> <a href="https://github.com/hashfunction/MarkuprPlus/actions/workflows/ci.yml?query=branch%3Amain"><img src="https://github.com/hashfunction/MarkuprPlus/actions/workflows/ci.yml/badge.svg?branch=main" alt="CI"></a> <a href="https://github.com/hashfunction/MarkuprPlus/actions/workflows/nightly.yml"><img src="https://github.com/hashfunction/MarkuprPlus/actions/workflows/nightly.yml/badge.svg" alt="Nightly"></a> <a href="https://github.com/hashfunction/MarkuprPlus/actions/workflows/deploy-landing.yml?query=branch%3Amain"><img src="https://github.com/hashfunction/MarkuprPlus/actions/workflows/deploy-landing.yml/badge.svg?branch=main" alt="Deploy"></a> <a href="https://github.com/hashfunction/MarkuprPlus/actions/workflows/test-action.yml"><img src="https://github.com/hashfunction/MarkuprPlus/actions/workflows/test-action.yml/badge.svg" alt="Action"></a> <a href="https://github.com/hashfunction/MarkuprPlus/actions/workflows/ci.yml"><img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/hashfunction/MarkuprPlus/badges/coverage.json" alt="Coverage"></a> </p> <p align="center"> <img src="https://img.shields.io/badge/version-3.2.0-f59e0b?style=flat-square" alt="Version 3.2.0"> <img src="https://img.shields.io/badge/desktop-Windows%20%7C%20macOS-lightgrey?style=flat-square" alt="Desktop app for Windows and macOS"> <a href="#cli"><img src="https://img.shields.io/badge/CLI-markuprplus-blue?style=flat-square" alt="MarkuprPlus CLI"></a> <a href="#mcp-server"><img src="https://img.shields.io/badge/MCP-server-blue?style=flat-square" alt="MCP server for AI agents"></a> <img src="https://img.shields.io/badge/transcription-local%20Whisper-4ade80?style=flat-square" alt="Local Whisper transcription"> <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square" alt="License"></a> </p> <p align="center"> <a href="#quick-start">Quick Start</a> &middot; <a href="#the-loop">The Loop</a> &middot; <a href="#what-lands-in-your-folder">Output</a> &middot; <a href="#every-surface">Screenshots</a> &middot; <a href="#report-providers">Providers</a> &middot; <a href="#mcp-server">MCP</a> &middot; <a href="#cli">CLI</a> </p>

---

<p align="center"> <img src="docs/images/markuprplus/target-clean.png" alt="An app under review, unmarked" width="290"> &nbsp;&nbsp; <img src="docs/images/markuprplus/marked-issue-001.png" alt="The same screen with a red freehand ellipse around the problem" width="290"> </p> <p align="center"> <em>Hold <code>Ctrl</code> on Windows or <code>Cmd</code> on macOS, circle the problem, keep talking. That stroke becomes <code>MX-001</code>.</em> </p>

The Problem

Your coding agent can't see your screen. So you stop working and start transcribing: describe the layout bug in prose, take a screenshot, crop it, drag it into the right place, explain which part matters. You speak at 150 words per minute and type at 60, and the context leaks out on the way.

The Solution

MarkuprPlus is a Windows and macOS desktop app, with a CLI, MCP server, and GitHub Action for automated workflows. The desktop app lives in the Windows system tray or macOS menu bar. It records the exact window you point at, listens while you narrate, and lets you draw on the live screen without blocking your clicks. When you stop, it transcribes on-device, aligns your words to each mark, and writes a report your agent can act on — one finding per circle, each with its own annotated frame.

| Use MarkuprPlus as | What you can do | Get started | |---|---|---| | Windows desktop app | Record your screen and voice, draw live annotations, and review reports from the system tray. | Download for Windows | | macOS desktop app | Capture and annotate from the menu bar on Apple Silicon or Intel Macs. | Download for macOS | | CLI | Analyze existing recordings, watch folders, and generate reports in scripts. | CLI commands | | MCP server | Let an AI coding agent capture screenshots, record sessions, and receive structured reports. | Connect your agent | | GitHub Action | Process recordings in your GitHub Actions workflows. | Action setup |

Windows: Ctrl+Shift+F → talk → Ctrl-drag → Ctrl+Shift+F → paste into your agent
macOS:   Cmd+Shift+F  → talk → Cmd-drag  → Cmd+Shift+F  → paste into your agent

The Loop

1. Press the capture shortcut and pick your target

Use Ctrl+Shift+F on Windows or Cmd+Shift+F on macOS.

<img src="docs/images/markuprplus/popover-ready.png" alt="The MarkuprPlus popover in its Ready To Capture state" width="320" align="right">

The picker opens above every window. Whatever is under your cursor lights up — click it and the recorder locks onto that window alone, and stays locked through moves, resizes, and app switches. Region and full-display modes are one click away when a finding needs a wider frame.

If the window's identity or native geometry ever becomes ambiguous mid-session, capture stops rather than widening to whatever is behind it. You never ship a frame you didn't mean to share.

The capture controls live in one portrait popover, accessible from the Windows system tray or macOS menu bar.

<br clear="right">

2. Talk while you work

Keep clicking through your app as usual. MarkuprPlus records the window and your microphone together, then transcribes with Whisper on-device after you stop.

The picker, the drawing canvas, and the recording HUD are all excluded from screen capture at the OS level — nothing MarkuprPlus draws ends up in your video. Only your app does, plus the strokes you meant to leave.

3. Hold Ctrl (Windows) or Cmd (macOS) and draw

<img src="docs/images/markuprplus/marked-issue-003.png" alt="A red hand-drawn ellipse around the tab bar of the app under review" width="250" align="right">

Hold the modifier key and drag to paint straight onto the live screen — freehand, circle, or highlight, in a colour you choose. Let go of the key and your next normal click both reaches the app underneath and saves that mark, clearing the canvas for the next one.

Three circles means three issues, not one screenshot with three scribbles on it. Each finding carries its own PNG, timestamp, tool, and colour.

<br clear="right">

4. Press the capture shortcut again to stop

Use Ctrl+Shift+F on Windows or Cmd+Shift+F on macOS.

<img src="docs/images/markuprplus/popover-report.png" alt="The popover showing Report Ready with the markdown path copied to the clipboard" width="320" align="right">

Whisper runs, your narration is aligned to each mark, and the report is written to disk. The markdown path lands on your clipboard the moment it's ready — paste it straight into Claude Code, Codex, Cursor, or anything else that reads a file.

Everything for the session goes in one folder: the report, the screenshots, the session video, the narration audio, and the metadata.

<br clear="right">

Quick Start

Windows and macOS desktop app (recommended)

Download from markuprplus.com or the releases page. Choose the Windows installer (.exe) or the macOS disk image (.dmg) for Apple Silicon or Intel.

macOS install note: Direct downloads from GitHub Releases are signed, notarized, and stapled. If Gatekeeper rejects an artifact, use MarkuprPlus support so the release can be investigated.

1. Press Cmd+Shift+F (macOS) or Ctrl+Shift+F (Windows) and click the window you want.
2. Narrate what you see. Hold Cmd / Ctrl and drag to mark the live screen.
3. Release the key, then click normally — that saves the mark and clears the canvas. Repeat for every finding.
4. Press the hotkey again to stop. The report path is on your clipboard.

MCP server (for AI coding agents)

npx --yes --package markuprplus markuprplus-mcp

CLI (for recordings you already have)

npx markuprplus analyze ./recording.mov

Compatibility: the public package and commands are markuprplus and markuprplus-mcp. Existing .markuprx project files, storage paths, and app identifiers remain unchanged so upgrades keep their settings and sessions.

Optional companion for Mac App Store CLI integrations

The sandboxed Mac App Store app can use AI command-line tools already installed and signed in on your Mac through the optional MarkuprPlus CLI Bridge. Local Rules, Ollama, LM Studio, and Anthropic API do not require this companion.

Install and pair it from a Terminal:

npm install -g markuprplus
markuprplus bridge install     # installs and starts a per-user LaunchAgent
markuprplus bridge token       # paste this value in Settings → Advanced
markuprplus bridge status

The public npm package contains the same versioned CLI and MCP entry points used by the source release.

The service listens only on 127.0.0.1:49647, requires its random pairing token for every provider request, and accepts a fixed structured-report protocol rather than shell text. The App Store app does not run shell commands or launch external tools; the separately installed companion invokes only the provider selected in Settings.

Lifecycle and recovery commands:

markuprplus bridge start
markuprplus bridge stop
markuprplus bridge status
markuprplus bridge token
markuprplus bridge rotate-token
markuprplus bridge uninstall

Rotating the token requires pairing again. Uninstall removes the exact LaunchAgent and bridge configuration owned by MarkuprPlus; it does not uninstall your AI CLIs.

What Lands in Your Folder

One session, one directory:

originplayer-test-iphone-20260818-104731/
├── feedback-report.md          # the file you paste
├── feedback-summary.md         # counts and duration
├── metadata.json               # per-issue capture context
├── processing-trace.json       # which provider ran, how long, why it fell back
├── screenshots/
│   ├── marked-issue-001.png    # one frame per mark, your stroke composited in
│   ├── marked-issue-002.png
│   └── marked-issue-003.png
├── session-recording.webm      # the window, with annotations
└── session-audio.webm          # your narration

A real, unedited finding from that session:

### MX-001

- **Timestamp:** 00:08
- **Too