Introduction to markupR
markupR is an open-source developer tool designed to bridge the gap between human insight and AI coding agents. Traditional workflows often require developers to describe bugs, take screenshots, and manually place them in context—this process is time-consuming and error-prone. markupR streamlines this by recording your screen while you narrate, then aligning your voice with video frames to produce structured Markdown reports with precise contextual cues. This allows AI agents to act on the feedback with minimal ambiguity.
The product is available as a desktop app, CLI, MCP server, and GitHub Action, making it highly versatile for integration into development workflows. With support for local transcription via Whisper and optional cloud-based OpenAI BYOK, markupR offers flexibility in privacy and performance. It is MIT-licensed, ensuring transparency and freedom for developers to use, modify, and extend the tool.
Takeaways
- Screen and voice recording with real-time narration
- Structured Markdown output with timestamps, frames, and context metadata
- Supports multiple platforms: macOS (Apple Silicon, Intel), Windows, CLI, and MCP server
- Integrates with AI coding agents: Claude Code, Cursor, Windsurf, GitHub Copilot, and more
- Privacy-focused: Local transcription available; optional cloud transcription
- Open source and MIT licensed
How markupR Works
markupR operates through a three-step workflow:
- Record + Narrate: Start a session and describe what you see in real time.
- Mark + Enrich: Manual shot markers confirm instantly, and after stopping, AI aligns the transcript with frames and adds context like cursor location, active window, and focused-element hints.
- Feed Your Agent: Paste the resulting Markdown into your AI coding agent, which can now act on the structured feedback.
The CLI also supports automation, allowing existing recordings to be processed without a desktop app. The MCP server enables AI agents to trigger markupR mid-conversation, capturing screenshots or recording sessions directly from within the agent’s interface.
Core Benefits and Applications
| Benefit | Description |
|---|---|
| Faster debugging | Reduces context-switching and manual documentation |
| Improved accuracy | Screenshots are placed at exact moments, aligned with voice narration |
| Enhanced collaboration | Structured reports can be shared in GitHub, Slack, or Linear |
| Flexible deployment | Runs locally or in CI/CD pipelines |
| Developer-friendly | Built for developers who read source code, with native macOS integration |
markupR is ideal for developers, QA engineers, and teams working with AI coding agents who want to improve the quality and speed of bug reporting and feedback loops.
