Agent guide / Claude Code

Show Claude Code the bug you are pointing at.

Use a local Markdown handoff when you want to stay in control, or let Claude Code call MarkuprPlus capture tools over MCP during the conversation.

Path one: paste a report file

The desktop workflow produces a durable file instead of flooding the conversation with an unstructured recording. Each completed mark becomes a separate finding with the words spoken around that moment.

Pick the exact window

Press Cmd+Shift+F, choose Window, and click the app you are reviewing. MarkuprPlus remains locked to that window as it moves or resizes.

Talk and mark

Narrate what is wrong. Hold Cmd and drag to draw a freehand, circle, or highlight mark; release it to create one finding for that moment.

Stop and paste the path

Press Cmd+Shift+F again. The Markdown report is written locally and its path is copied to the clipboard, ready to paste into your agent.

Path two: connect the MCP server

Add this block to ~/.claude/settings.json. The package runs locally over stdio; no MarkuprPlus account is required.

The configured process is npx --yes --package markuprplus markuprplus-mcp.

~/.claude/settings.json

{
  "mcpServers": {
    "markuprplus": {
      "command": "npx",
      "args": ["--yes", "--package", "markuprplus", "markuprplus-mcp"]
    }
  }
}

What Claude can call

The nine MCP tools cover immediate captures, narrated sessions, existing media, and tracker handoff. Each tool description states the artifact returned to the calling agent.

capture_screenshot
capture_with_voice
describe_screen
start_recording
stop_recording
analyze_video
analyze_screenshot
push_to_github
push_to_linear

What one mark looks like

This is the unit Claude receives: one issue identity, aligned narration, annotation metadata, and its own evidence file.

feedback-report.md

### MX-001

- **Timestamp:** 00:16
- **Tools:** freehand
- **Colors:** #ff3b30

#### User comment

> There's a search menu, and by default, if there have been previous searches,
> it should list out all the searches that have happened in the past.

#### Marked evidence

![Marked issue MX-001](./screenshots/marked-issue-001.png)

Claude Code can also write the report

Claude Code CLI is available as a report provider and runs non-interactively through the signed-in CLI. The session material is passed as bounded report input, not as a request to edit your project.

Failure stays safe. If Claude Code CLI is unavailable or returns an error, Local Rules still writes a deterministic report and processing-trace.json records why the provider fell back.