Surfaces

WordPress plugin v0.26.0

The flagship surface and the most complete implementation of Red Pen. A logged-in Dev Mode overlay on the site front end, plus a full notes repository in wp-admin - all from a single self-contained plugin file.

User manual (PDF)

At a glance Editors and admins flip on Dev Mode and drop typed notes, pinned to elements, anywhere on the front end. Every note collects on the post's edit screen and in one shared repository. The plugin is free and open source with no third-party services and no key. Dev credit: Lincoln Tracy / Tracy Digital Media LLC.

What it is

Reviewing a WordPress site usually means a messy spreadsheet, a thread of "the about page has a typo", or comments scattered across email. Red Pen puts the note where you found the problem - on the page itself - and collects every note in one place your whole team can see. It is good for editorial review, client hand-offs, content audits, QA passes, and shared to-do lists.

The plugin has two halves that share one data store:

The front-end overlay - a floating button (bottom right) shown only to logged-in users who can edit posts. This is where you leave, pin, and reply to notes while looking at the live page.
The repository - an admin screen under Tools in wp-admin listing every note across the whole site, with filters and one-click status changes. There is also a per-post meta box on each edit screen showing that page's notes.

Install and activate

Copy the wp-red-pen folder to wp-content/plugins/ (or upload the zip via Plugins -> Add New -> Upload).
Activate it. There is no build step and no settings you must configure to start - it is a single self-contained wp-red-pen.php with inline CSS and JS.
Click Red Pen: Off in the admin bar to turn Dev Mode on for your account.
Open any post or page on the front end and use the floating button.
Review everything under the Red Pen repository in wp-admin (under Tools).

Running many local sites? Red Pen works well as a default-workflow plugin across a local development fleet. Because it is a single self-contained file, a small script that copies the current build into each install's wp-content/plugins/ (and activates it with WP-CLI) keeps every local site on the same version.

Dev Mode

Red Pen is invisible until a logged-in user with the edit_posts capability (editors and admins) turns on Dev Mode from the admin-bar toggle. Dev Mode is per user - flipping it on affects only your account, so a client and a developer logged into the same site can have it on or off independently.

The admin-bar item reads Red Pen: On / Red Pen: Off and carries an open-note count badge, mirrored on the floating button, so you always see how many notes are still open.
Logged-out visitors never receive the Red Pen assets at all - the capability check happens before any CSS or JS is enqueued. There is no way for an end user to see or trigger the overlay.
A global "Where Red Pen appears" setting controls which views show the button - singular posts and pages, archives, taxonomy pages, the home/front page, search, and 404. It defaults to everywhere.

Leaving a note

With Dev Mode on, the floating button opens the note panel. From there you can:

Type a note with a type - note, idea, problem, or question - plus a priority of Low, Normal, or High. Custom note types with their own colour flag are supported too.
Set a severity (optional) - under More, next to Priority, tag the note's impact as Blocker, Critical, Major, Minor, or Trivial. Severity is the impact axis where priority is the scheduling one (see Severities); it is left unset by default, dev-only (client reviewers never see it), and shows on the note, in the CSV export, and on the Hub board.
Pin to an element - the "Pin to element" picker lets you click any element on the page to anchor the note to it. Anchored notes appear as numbered markers on the page; clicking a marker opens its note, and the note can jump you back to the element. A pin is labelled by the element's own visible text (falling back to its alt / aria-label / title, then a plain-language name for the tag), and editing a note re-resolves the saved selector, so a pin whose target has gone reads as gone. On a phone the page still scrolls normally in pin mode - a deliberate tap pins, a drag scrolls - and a visible Cancel control stands in for the Esc key.
Choose who sees it - Visible to client reviewers, off by default. Notes are internal unless you tick it; see Client review links below.
Snip a screenshot - click Screenshot, drag a box around the area, and the region is captured client-side (via vendored html2canvas) and stored as a small WebP in uploads/wp-red-pen/, attached to the note.
Set the reporting level - target This page (the exact post or archive you are on) or This template (the view type, so the note covers every page rendered the same way). A page shows its own notes plus the template notes that apply to it.

Every note also records auto-context - the browser, OS, and viewport it was created in - so a layout bug carries the environment it happened in.

Editing a note

Any note can be edited after it is added - change the text, type, priority, or assignee; swap, remove, or add a screenshot; and re-pin, move, or clear the attached element. The front-end panel has full editing.

Statuses, priorities, and replies

Every note carries a status, a priority, and its own reply thread.

Three-state workflow - every note is Open, In progress, or Resolved. Resolve and reopen are one click; In progress sits between the two for work that is underway.
Priority - Low, Normal, or High, surfaced as a column and a filter in the repository.
Threaded replies - reply to any note from the panel to build a discussion under it. Replies are stored as child notes of the parent.

Assignee and agent

WordPress is the surface where assignment is fully implemented today. A note carries two distinct, complementary fields:

Assignee - a WordPress user the note is assigned to (a real person). The repository adds an Assigned column and an "Assigned to me" filter. This is the manual-work lane.
Agent - an AI agent slug (for example a coding agent's handle). An empty agent means a human note; a set agent marks the note as automated work, and the REST API can return just the notes targeted at a given agent. This is the automated-work lane.

Why two fields Keeping a human assignee separate from an agent slug lets a board distinguish manual from automated tasks at a glance. This model is the reference the other surfaces and the Hub will adopt as assignment rolls out to them.

The repository

The shared repository admin page lists every note across the site. You can filter by Open / In progress / Resolved / All, by priority, and by assignee ("Assigned to me"), and resolve or reopen any note with one click. A CSV export dumps the current view (honouring the active filters) for handing off or archiving - generated locally, with no external service, and carrying a Client visible column. Each post's edit screen also carries a meta box listing that page's notes inline.

Client review links v0.13.0, free

The reason this surface exists for client work: you can let a non-technical client leave pinned notes on a site without a WordPress login. From the "Client review links" panel (under Tools, alongside the Hub settings) you generate a labelled, shareable link. Send it privately to your client; they open it, click the red button, and leave typed notes and replies pinned to the page - the same overlay you use, in a restricted "reviewer mode". This is free core, never gated. Since v0.26.0 the link is a one-way door by default: it collects your client's feedback and shows them their own reports, and it shows them nothing of yours unless you deliberately share it.

What a reviewer can and cannot do

Reviewer mode is a deliberately narrow door. A link holder can open the overlay, pin notes to elements, leave typed notes (type and priority), and reply. A link holder cannot resolve, reopen, edit, delete, or assign notes, cannot open the admin repository, cannot view screenshots, and never sees the user list, the agent options, or any other reviewer link. The boundary is enforced on the server, not just hidden in the interface.

What a reviewer can see changed in v0.26.0

Two rules decide whether a note reaches a reviewer link, and both are checked on the server through one gate:

Their own reports, at any status. A note filed through a link is visible to that link whatever state it has reached, with the date it was marked fixed. Before 0.26.0 reviewer reads were pinned to open notes, so a client's Resolved tab could never fill and a fixed report looked identical to one that never saved. A note also records which link filed it, so one client's link cannot surface another client's history.
Your notes, only when you share them. Everything else is internal by default and reaches a reviewer only when its author ticks Visible to client reviewers on the note - and then only while it is open. The check fails closed: no flag means internal, so every note that predates 0.26.0 is invisible to a reviewer link until it is shared deliberately.

If you used review links before v0.26.0 Any note that was open, on a public page and not aimed at an agent was readable by anyone holding a reviewer link - including a developer's own working notes. That is fixed, and the fix is retroactive: notes are internal unless opted in. A one-time migration backfills the flag on notes a client filed through a link, so feedback they sent you before the release stays visible to the link that sent it. Legacy notes from before links carried that stamp stay open-only, which is exactly what they had before.

The checkbox sits on the note form in both the front-end panel and the repository edit panel, off by default. A shared note carries a badge in the front-end list, the edit-screen meta box and the repository table, and a Client visible column rides along in the CSV export - so "what has the client actually seen?" is answerable from the same screens you triage on.

Managing links

Generate with a label (the client or project name) and an optional expiry (never, 7, 30, or 90 days). The full URL is shown once at creation - copy it then, because only a hash is stored and it cannot be displayed again.
Revoke any link instantly from the active-links table. A revoked link stops working on the next request.
Triage reviewer feedback in the repository: reviewer notes carry a red "Client" badge and the reviewer's name, and a Source filter (All / Client reviews / Dev notes) narrows the list so you can review or bulk-action client feedback on its own.

Share it privately A review link is a bearer link - anyone who has it can leave notes, so share it with your client directly rather than posting it publicly. Abuse is bounded by a per-visitor rate limit and the instant revoke, and an optional expiry adds a second backstop. Because it is a link, the token appears in the URL, so it can show up in that browser's history.

Client report v0.21.0

The deliverable you hand a client. From the Client report panel (under Tools, alongside the review links) you generate a clean, printable summary of the site's notes - Generate report (all) for everything including resolved items, or Open items only. It opens in a new tab; use the browser's Print / Save as PDF to send it. This is the "here is what you asked for, here is what is done" document, drawn straight from the notes you have been triaging.

The report groups notes by status (Open, In Progress, Resolved) with summary counts, and shows each note's type, its severity when set, the page it is on, its screenshot, and the dates it was added and resolved. It is deliberately client-facing: the agent queue and internal-only fields (assignee, agent, code scope, browser context) are left out.

Plain and branded reports

The report comes in two styles, both free. The plain report carries the tool's credit; the branded report lets you set a custom report title, your logo, an accent colour, and hide the "Generated with Red Pen" credit, so it goes out as your own deliverable rather than the tool's. You set these in the same panel.

REST API

The front-end button talks to a small REST API under the wprp/v1 namespace. The same routes are what the Red Pen Hub uses for two-way write-back. Every route is gated by an edit_posts capability check. The front-end button authenticates with the standard wp_rest nonce; a server-to-server client (such as the Hub) authenticates with a WordPress Application Password over HTTP Basic auth.

Method + route	Purpose
`GET /wp-json/wprp/v1/notes`	List notes for a view. Accepts `target`, `status`, context `keys`, or an `agent` slug to fetch an agent's queue. Also accepts `scope=all` so the Hub can pull every note on the site, not just site-wide (`target=0`) ones. Notes carry an ISO `createdAt` and, once resolved, `resolvedAt` + `resolvedBy`.
`POST /wp-json/wprp/v1/notes`	Create a note (body, type, priority, target, anchor, screenshot, agent, and more).
`POST /wp-json/wprp/v1/notes/{id}`	Edit an existing note - text, type, priority, assignee, anchor (re-pin / clear), screenshot, and context.
`POST /wp-json/wprp/v1/notes/{id}/status`	Set the status (`open`, `progress`, or `resolved`). The Hub's Resolve / Reopen calls this route.
`POST /wp-json/wprp/v1/notes/{id}/replies`	Add a threaded reply to a note.

Connect to Hub

To see this site's notes alongside every other project, connect it to the Red Pen Hub. Under the plugin's Display settings, fill in "Connect to Red Pen Hub" with the Hub URL and the shared connect token. The plugin then pushes its notes to the Hub whenever a note changes - the site sends to the Hub, so no Application Password or inbound access is needed.

What the push sends. A push includes every top-level note on the site - all pages and posts, not just site-wide ones - each with its full data: type, priority, severity, anchor, the ISO created and resolved timestamps, statusAt (when the status last moved), the custom type's typeLabel, the resolver, and the assignee. So the board shows the same detail no matter how the site is connected.

There is a second way to connect: instead of the site pushing, the Hub can pull from the site using a WordPress Application Password (see the REST /notes route above). A pull uses the ?scope=all parameter added in v0.19.0 to get the whole note set - before it, a pull saw only site-wide (target=0) notes and page/post-attached ones went missing. Pull connections are also how the Hub writes a resolve back into the WordPress database over REST.

Known gotcha The Hub URL must include the scheme - write http://localhost:3900, not localhost:3900. A schemeless URL is silently rejected by WordPress sanitisation, which saves the token but blanks the URL, so the push quietly no-ops. Recent versions auto-prepend http://, but include it to be safe.

Architecture and data

The plugin keeps everything in standard WordPress structures - no custom tables:

Storage - a private wprp_note custom post type. The note body is the post content; author and date are native; status is a custom post status (wprp_open / wprp_progress / wprp_resolved).
Replies are child wprp_note posts (the parent is the note id). Priority, assignee, agent, context, and the element anchor are all post meta.
Targeting context - each note stores a context key (for example post:12, pt_archive:composer, term:genre:5, tpl:single-track, search, 404), a human label, and a level (page or template). The front end fetches by the current view's page and template keys.
Clean uninstall - deleting the plugin removes every note and preference it created, and nothing else.

Troubleshooting

No floating button. Confirm you are logged in as an editor or admin and Dev Mode is On in the admin bar. Logged-out users never get the assets. Check the "Where Red Pen appears" setting covers the view you are on.
Notes not reaching the Hub. Verify the Hub URL includes http:// and the connect token matches the Hub's token exactly. A bad token returns a 401; a missing scheme blanks the URL.
A screenshot did not save. Screenshots are stored under uploads/wp-red-pen/; confirm the uploads directory is writable.

Previous← Surface matrix NextExpress middleware →