Pointframe / website

# Pointframe

> Pointframe lets your coding agent test the real Windows UI. It is a free, open-source (MIT) toolkit, Windows x64 only: agents inspect your app, interact with its controls, and run repeatable checks with screenshots and signed evidence (`pointframe verify run`). Its standalone MCP server and CLI also let AI agents list monitors and windows, capture screenshots, read on-screen text with Windows OCR, search saved captures, and record redacted MP4s; the same project ships a screenshot and recording tray app for people. Everything runs locally; official builds of the MCP server and the CLI send only anonymous usage counts (tool or command name, outcome, duration bucket, host, client type, version, random install ID), and POINTFRAME_TELEMETRY_OPTOUT=1 or DO_NOT_TRACK=1 turns that off. Windows 10 and 11, interactive desktop session required.

Install the MCP server for Claude Desktop (open the .mcpb bundle), Claude Code (`claude mcp add`), Codex (`codex mcp add`), VS Code, or Cursor. The exact commands are on the agent page below and in the MCP reference.

## Short path for coding agents

<!-- short-path:begin (generated from Pointframe.Mcp/Guides/verify-desktop-work.md by scripts/sync-agent-guides.ps1; do not edit) -->
Run everything from the project root, in an interactive, unlocked Windows desktop session.

1. Install the CLI (skip this if `pointframe --version` works). Run this one line as it is, in one tool call; it works from Bash and from PowerShell:

```
pwsh -NoProfile -Command '$d=Join-Path $env:TEMP "pointframe-cli"; Remove-Item $d -Recurse -Force -ErrorAction Ignore; New-Item -ItemType Directory $d | Out-Null; try { $b=Invoke-RestMethod "https://api.github.com/repos/dimitar-radenkov/Pointframe/releases?per_page=100" -Headers @{"User-Agent"="pointframe-install";"Accept"="application/vnd.github+json"} | Where-Object { $t=[string]$_.tag_name; $n=$t.Substring(1); $a=@($_.assets | ForEach-Object { $_.name }); -not $_.draft -and -not $_.prerelease -and $_.published_at -and $t -cmatch "^v\d+\.\d+\.\d+$" -and @("Pointframe.Cli-$n-win-x64.zip","Pointframe.Cli-$n-win-x64.zip.sha256","Pointframe.Mcp-$n-win-x64.mcpb" | Where-Object { $a -cnotcontains $_ }).Count -eq 0 } | Sort-Object { [version]$_.tag_name.Substring(1) } -Descending | Select-Object -First 1; if (-not $b) { throw "no complete agent release on the first page" }; $v=$b.tag_name.Substring(1); $u="https://github.com/dimitar-radenkov/Pointframe/releases/download/v$v/Pointframe.Cli-$v-win-x64.zip" } catch { Write-Warning "Could not find the newest agent release ($($_.Exception.Message)); using the legacy latest-release download."; $u="https://github.com/dimitar-radenkov/Pointframe/releases/latest/download/Pointframe.Cli-win-x64.zip" }; Invoke-WebRequest $u -OutFile "$d\cli.zip"; Invoke-WebRequest "$u.sha256" -OutFile "$d\cli.zip.sha256"; if ((Get-FileHash "$d\cli.zip").Hash -ne ((Get-Content "$d\cli.zip.sha256" -Raw).Trim() -split "\s+")[0]) { throw "SHA-256 mismatch" }; Expand-Archive "$d\cli.zip" "$d\x"; & "$d\x\Pointframe.Cli.exe" install; "$env:LOCALAPPDATA\Programs\Pointframe.Cli\pointframe.exe"'
```

   The line takes the newest release that has the CLI zip and its checksum from the GitHub Releases API, and prints a warning if it has to use the latest-release download instead. `install` puts `pointframe` on the user `Path` for new shells only. In the shell you already have open, call the exe path the line prints (`%LOCALAPPDATA%\Programs\Pointframe.Cli\pointframe.exe`) in place of `pointframe`.
2. Write the spec, with your built exe's path relative to the project root (one line, for a single-project WPF app):

```
pointframe verify init --app bin/Release/net10.0-windows/MyApp.exe --hooks none
```

3. Add one scenario to the `scenarios` array of `.pointframe/verify.json`: an action, the resulting state, and a negative control (a check with `expectFailure` and a deliberately wrong expectation, which must fail):

```jsonc
{ "id": "save-text", "criteria": ["Saving shows the typed text in the status line."], "steps": [
  { "enterText": { "automationId": "textBox", "text": "hello" } },
  { "invoke": { "automationId": "saveButton" } },
  { "check": { "kind": "textEquals", "automationId": "statusLabel", "expected": "Saved hello", "criterion": "C1" } },
  { "check": { "kind": "textEquals", "automationId": "statusLabel", "expected": "Not saved", "expectFailure": true, "timeoutSeconds": 1 } } ] }
```

4. Make it a `verify-<app>` skill (pstack-compatible), so the next agent can repeat the proof. Use ONE folder, the project skill folder the repo already has: `.claude/skills/` for Claude Code, `.agents/skills/` for Codex and other agents. The folder and the `name:` in the SKILL.md frontmatter are both `verify-<app>`:

```
<skills>/verify-<app>/SKILL.md              (frontmatter: name: verify-<app>, description: Prove that a change to <app> works ... Use after changing <app>.)
<skills>/verify-<app>/features/README.md    (lists the feature files)
<skills>/verify-<app>/features/<feature>.md (one per feature)
```

   Each feature file has exactly four H2 sections, with these exact headings: `Sub-features`, `How to get to it (user POV)`, `Driving it with Pointframe`, `Gotchas`. `Driving it with Pointframe` and `Gotchas` name the scenario id (for example `save-text`) and say to run `pointframe verify run --scenario <id>`; they never copy steps from the spec. Write all skill files in one shell command, before step 5.
5. Run `pointframe verify run`. It runs the gates, launches the app, drives the scenario in the real UI, and installs the MCP server itself on its first run. Read `status` in the printed JSON: `pass` is exit 0, `fail` is exit 1, a wrong spec is exit 2. Run `verify run` last: any later edit, even to docs or skill files, makes the pass stale (`verify status` then shows `fresh: false`), so write everything first and run again if you change anything.
6. Evidence: `artifacts/pointframe-verify/verdict.json` is the verdict, and each scenario's signed bundle (`report.json`, `evidence/` screenshots, `index.html`) is under `artifacts/pointframe-verify/runs/<time>/`. Say the work is done only when `status` is `pass`.

The spec fields are in [verify-spec.md](https://github.com/dimitar-radenkov/Pointframe/blob/master/docs/cli/verify-spec.md); the example above covers the common case.
<!-- short-path:end -->

## Agents

- [Windows screenshot MCP server for AI agents](https://dimitar-radenkov.github.io/Pointframe/windows-screenshot-mcp-server.html): what the server does, install steps per client, the eleven tools, and the privacy model
- [Let your coding agent test the real Windows UI](https://dimitar-radenkov.github.io/Pointframe/verify-coding-agents-windows.html): inspect your app, drive its controls, and run repeatable checks with screenshots and signed evidence; build and test gates and a Stop hook included
- [Coding agents: verify a Windows desktop app in six steps](https://github.com/dimitar-radenkov/Pointframe/blob/master/docs/cli/verify.md#coding-agents-start-here)

## Documentation

- [MCP reference](https://github.com/dimitar-radenkov/Pointframe/blob/master/docs/mcp/README.md): tools, resources, workflow, and per-client install
- [Privacy policy](https://dimitar-radenkov.github.io/Pointframe/privacy.html): what the desktop app, CLI, and MCP server collect, where it goes, retention, and the opt-out
- [PRIVACY.md](https://github.com/dimitar-radenkov/Pointframe/blob/master/PRIVACY.md#privacy-policy): the same policy in the repository
- [CLI guide](https://github.com/dimitar-radenkov/Pointframe/blob/master/docs/cli/README.md): commands, JSON output, exit codes, and the MCP installer
- [Desktop-testing MCP guide](https://github.com/dimitar-radenkov/Pointframe/blob/master/docs/mcp-desktop-testing/README.md): the opt-in tools that drive a Windows app, off by default
- [pointframe verify](https://github.com/dimitar-radenkov/Pointframe/blob/master/docs/cli/verify.md): declarative done-checks for coding agents

## Releases

- [Latest release](https://github.com/dimitar-radenkov/Pointframe/releases/latest): installer, CLI ZIP, MCP bundle, and checksums
- [Pointframe.Mcp-win-x64.mcpb](https://github.com/dimitar-radenkov/Pointframe/releases/latest/download/Pointframe.Mcp-win-x64.mcpb): the MCP server bundle (self-contained, includes ffmpeg)
- [Pointframe.Mcp-win-x64.mcpb.sha256](https://github.com/dimitar-radenkov/Pointframe/releases/latest/download/Pointframe.Mcp-win-x64.mcpb.sha256): its SHA-256
- [Pointframe.Cli-win-x64.zip](https://github.com/dimitar-radenkov/Pointframe/releases/latest/download/Pointframe.Cli-win-x64.zip): the standalone CLI
- [MCP Registry entry](https://registry.modelcontextprotocol.io/v0/servers?search=pointframe): io.github.dimitar-radenkov/pointframe-mcp

## Optional

- [Source code](https://github.com/dimitar-radenkov/Pointframe)
- [Pointframe website](https://dimitar-radenkov.github.io/Pointframe/)