Agents

PwrSnap can hand a local AI agent — PwrAgent, a coding agent in your terminal, anything that speaks MCP — a controlled door into your Library. The agent can search captures, read pixels, ask for edits, and build Sizzle Reels, and every one of those actions runs through PwrSnap rather than around it.

It’s off until you turn it on, and once on, every connecting agent still has to get past a consent window you answer by hand.

What it is

PwrSnap runs a small MCP server on the loopback interface:

http://127.0.0.1:51729/mcp

Loopback only. Nothing on your network can reach it, and PwrSnap rejects any request that didn’t arrive addressed to 127.0.0.1:51729.

The point of routing agents through a server instead of just letting them read ~/Documents/PwrSnap/ is that a file is a file — a request is checkable. Going through PwrSnap means:

• The agent sees the edited composite by default, so a redaction you drew is a redaction the agent gets. Reaching the original pixels underneath is a separate, higher-tier permission most roles don’t grant.
• Every request is checked against a role you assigned, a history horizon you picked, and a rolling budget — at the moment it runs, not at the moment you approved it.
• Edits happen through PwrSnap’s own editing commands, so they land as ordinary overlays you can undo. See Library → your originals stay untouched.

Turn it on

Go to Settings → Local Agents. The page is titled Authorization graph, and the first card is MCP server:

Enable local-agent access — “When off, PwrSnap does not listen for MCP connections. Saved Sessions and roles remain available. When on, every connection still requires native approval and an assigned RBAC role.”

Flip it on and PwrSnap starts listening. A badge next to the header shows the live listener state, so you can tell “switched on” from “actually accepting connections” — if the port is busy, the switch staying on is not a claim that the door is open.

Turning it back off stops the listener. Your saved sessions and roles survive; they just have nothing to attach to.

Connect an agent

Point your agent at http://127.0.0.1:51729 and let it do the normal MCP OAuth handshake. PwrSnap registers the client dynamically — there’s nothing to paste, no key to generate.

The part that would normally kick you out to a browser doesn’t. PwrSnap intercepts the hand-off and opens its own window:

A local MCP client wants to access PwrSnap

Your library can contain private screen content. Choose exactly what this local agent may search, read, create, or change.

Underneath, in order:

1. Client-reported label: <name> — what the agent calls itself. It’s display metadata, not identity: any local process can claim any name, so treat it as a hint about which window you’re looking at, not proof of who’s asking.
2. Session Name — “Use a unique name you will recognize later in Access Control.” This is the handle you’ll revoke by, so name it after the thing that’s connecting, not after the task.
3. Choose an access role — a radio list of the built-in roles that fit inside what the agent asked for, plus Custom role (“Pick individual permissions and a limit on how far back the agent can see.”).
4. If you pick Custom: a Capture history horizon — Last 7 days / Last 30 days / Last 90 days / Last year / All time — and a checkbox per requested permission, each showing its label, what it actually does, and the raw capability id.
5. Deny or Allow access. The footer reminds you: “Access can be changed or revoked later in PwrSnap Settings.”

An authorization request expires after five minutes if you don’t answer it.

The agent’s side of this is ordinary MCP — if you’re wiring up PwrAgent, its own docs cover the client half.

Roles

A role is a bundle of permissions plus two limits: how far back in your history the agent can see, and how much it can do in a rolling 24 hours. Six ship built in:

Budgets read searches / preview images / full-res images / edits / trash moves, each per rolling 24 hours. A 1 is not a typo — it’s the smallest non-zero allowance, enough that a misrouted call fails visibly rather than silently succeeding.

Custom roles. Hit + New custom role on the Local Agents page, or duplicate a built-in and edit the copy. A fresh custom role starts at 7 days of history and 50 / 200 / 25 / 25 / 10.

Built-ins are drift-checked: if a built-in role’s definition ever doesn’t match what PwrSnap expects, every session bound to it fails closed rather than running with the wrong permissions. Edit a duplicate, not the original.

Permissions

Nine capabilities, with the labels you’ll see in the consent window and on the Settings page:

The composite / original split is the one to understand. “Read edited previews” gets the picture as you see it, redactions baked in. “Read original images” gets what was underneath. They’re deliberately separate permissions, and every role below Full Media grants only the first — so an agent without Read original images can’t see under a redaction you drew.

Nothing short of Full Access grants Move to Trash or Read full Sizzles, and nothing at all exposes a permanent delete — the Trash is as far as an agent can go, and the Trash is recoverable.

Sessions, budgets, and audit

Each approval becomes a named, durable Session. The Local Agents page draws them as a graph — Session → role → permissions, with allowed paths in the accent color and rejected ones in red — and every Session card carries the client’s self-reported label, an active/revoked badge, a role dropdown you can change on the spot, when it was last used, and Revoke.

Policy is re-resolved on every single call. Revoking a session or narrowing its role takes effect on the agent’s next request, not at its next restart — and anything ambiguous fails closed.

Budgets are sliding windows, shown with used-vs-limit bars under a LIVE SCOPE card for the selected session:

• Searches
• Preview images
• Full-res images
• Edits
• Trash moves

Each reads used / limit and rolling 24 hours. Alongside them, Capture history shows the horizon: “Searches and direct resource reads are checked against this moving horizon.”

Audit. A collapsed Recent agent actions card holds the last 50 protected-media and mutation actions — what was done, which Session did it, which capture, when, and whether it succeeded. Reads that aren’t protected don’t clutter it: “Protected media and mutation actions appear here.”

What an agent can do

The tools PwrSnap exposes, in plain English. Each one needs the permission in brackets, or it doesn’t run:

Finding things

• Search the Library — text, source app, exact tags, kind, date, whether there’s OCR text. No-query searches come back newest-first; queries come back by relevance. [Search library]
• List what’s searchable — the source apps and accepted tags actually present in the Library, so the agent can build a real filter instead of guessing. [Search library]
• Read one capture’s metadata — compact details for a single capture, no pixels. [Search library]

Reading pixels

• Fetch a capture — the current edited composite by default, or the original if the role allows it. [Read edited previews, or Read original images]
• Export a capture — Low / Med / High at PNG, JPEG, PDF, or (on supported macOS installs) HEIC. Defaults to Med PNG. [Export captures]

Changing things

• Edit an image — one or more instructions applied in a single blocking turn, running through the same editing substrate as Library Chat, so the result is ordinary undoable overlays. [Edit images]
• Move a capture to Trash — recoverable. Permanent purge is not exposed to agents at all. [Move to Trash]

Sizzle Reels

• Create a reel from a set of captures, optionally with a brief that starts its composition chat. [Compose Sizzles]
• Send a follow-up instruction to that reel’s chat, and check its status. [Compose Sizzles]
• Render a preview (low resolution) [Read Sizzle previews] or render the full reel [Read full Sizzles].

Media comes back either as an MCP resource the agent reads by its canonical pwrsnap:// URI, or over a short-lived signed URL for clients that don’t do resource reads. Either way the grant is re-checked before the bytes move.

Privacy

• Nothing leaves your machine. The server binds to loopback and nothing else. Whether the agent you connect sends anything onward is between you and that agent — but PwrSnap itself is handing bytes to a process on the same computer.
• Off by default. localAgents.enabled starts false, and no connection is accepted until you flip it and approve a session by hand.
• Every protected request is checked against live policy, not against whatever was true when you clicked Allow.
• A hard-off switch. Launching PwrSnap with the environment variable PWRSNAP_DISABLE_LOCAL_AGENT_MCP=1 prevents the server from starting at all, regardless of what the setting says. Useful for a locked-down or shared machine where the toggle shouldn’t be reachable.

Not yet

• No per-capture allow list. Access is scoped by role, permission, and history horizon — you can’t hand an agent three specific captures and nothing else.
• No cross-machine access. Loopback only, by design. An agent on another machine can’t connect, and there’s no plan to change that.