The Hub

Red Pen Hub v0.9.1

One board that aggregates Red Pen notes from every project and every surface into a single screen - and lets you resolve and reopen them in place. Like every Red Pen surface, the Hub is free and open, with no cap and no key.

User manual (PDF)

Principles

• Local-first. The Hub is a small app you run on your own machine. There is no SaaS, no account, no telemetry, and no kill switch.
• No phone-home. It only ever reads the stores you connect and writes back only when you click a button. Nothing is sent anywhere on its own.
• It is never your only copy. The source of truth always stays at the surface - the WordPress database, the .redpen/ store in your repo, the browser. The Hub aggregates; it does not own your notes.
• Free and open. Every surface is free and complete on its own, and so is the Hub - every project, no cap, no license key. If it earns a place in your workflow, you can back the next release.

Supporting the project

The Hub is free and open source, and it aggregates every project you point it at - no cap, no license key, no account, no phone-home, and no kill switch. Everything works, forever. Configure as many sources as you like; nothing on the board is held back.

Red Pen is built and maintained by one person. If the Hub saves you time, you can back the next release - one-time support is the ask, not a subscription. Two rails: Buy Me a Coffee and GitHub Sponsors. Supporters are listed on the wall.

Running the Hub

The Hub is a standalone local Node application, published on npm. Run it with no install:

npx red-pen-hub
# Red Pen Hub running at http://localhost:3900

Or from a clone of the repo: npm install once, then npm start. A single-file executable is planned so it can run with no Node setup at all (see Distribution below). Open http://localhost:3900 in a browser to use the board.

Configuration - sources.json

All configuration lives in a single sources.json file in the Hub's per-user data directory - %APPDATA%\red-pen-hub\ on Windows, the XDG config directory on macOS and Linux, or wherever RED_PEN_HUB_DATA points. It never ships with the app, and it survives reinstalls and npx installs; state from older in-folder installs migrates on first run. The fields you care about:

Checking the install - --doctor

Run npx red-pen-hub --doctor (or npm run doctor) to have the Hub check itself and exit. It validates sources.json, then reports every source and connected push store - found, readable, note count, and the REST or auth error for a WordPress source that will not answer - plus the detected web roots and data directory. It exits non-zero if anything is wrong, so it works from a script, and it writes nothing: a check command reports, it does not change the install. --help and --version are there too.

Getting notes onto the board

There are three ways a project's notes reach the Hub. You can mix all three on one board.

1. Connect a Site (push)

The easiest path, and the one that scales. Instead of the Hub reaching out to each site, each site posts its notes to the Hub. A connecting site needs only two things: the Hub's URL and one shared token - the same token everywhere. There are no per-site passwords and no URLs to guess.

On the site side, you paste the Hub URL and token into that surface's "Connect to Hub" control - the Display settings on the WordPress plugin, or the "Connect to Hub" panel in the static drop-in's All-notes board. From then on the site pushes its notes to the Hub whenever they change. The first push self-registers the project - it appears on the board automatically, with no "Add" step, and is stored as a single JSON file under the Hub's connected/ directory.

2. Add Projects (pull)

The pull path is driven by a scan. Click + Add Projects in the Sources tab, point it at a development directory, and the Hub walks that directory and detects every Red Pen install regardless of platform:

• File stores - any .redpen/notes.json (Express apps, Blender projects, static exports, Ableton). A store that declares its own surface is badged with what it declares; the package.json heuristic is only the fallback for stores that declare nothing.
• WordPress installs - any folder with a wp-config.php and the Red Pen plugin present, with a guessed local URL.

The scan returns a checklist, pre-checked, with note counts. You uncheck what you do not want and confirm; your selection is persisted to sources.json. WordPress pull sources read the plugin's REST endpoint and need an Application Password (not the login password) entered once. Note that local WordPress sites are usually better connected by push - pull is most useful for file stores and for remote sites that cannot reach a localhost Hub.

3. File sources

A file source is the simplest kind - a direct path to a .redpen/notes.json store. The Hub reads it straight off disk. This is how Express apps, static exports, and the Ableton extension's store appear on the board. File sources are discovered by the Add Projects scan or can be added directly.

The board

The board is the whole interface. Everything is filterable and sortable, and the view follows a set of tabs.

Status tabs

Across the top, tabs split notes by where they are in the workflow, each with a live count that respects your active filters:

Columns

Each note row reads at a glance. The old single "When" column was split into a Created and a Resolved column so you can see and sort by when a note opened and when it closed; "Where" was renamed Location. An Age column sits beside them, measured from creation and weighted only on notes that are both old and unfinished - the Created date alone does not make "this has been open for five weeks" land. Every row also shows a compact byline - author, assignee, and reply count - and, when a note is resolved, the resolver's name under the Resolved date. Severity shows when a note has one (see Severities).

The Location cell doubles as the artefact cell. A Blender note carries a viewport snapshot, and the board renders it there - those notes have no URL, so the space was empty anyway. The image is read off your local disk and served by note id rather than by path, so the route can only ever hand back a file some note actually declared.

The board also refreshes itself. It holds an event stream open to the Hub and repaints when a source changes, so a note you resolve in Blender or on a client site appears without you reaching for the Refresh button - which stays as the fallback if the stream drops.

Filtering, sorting, and saved views

Above the table sit a search box and four dropdowns - project, surface, type, and priority - which combine to narrow the list. Every column header is sortable; clicking a header toggles the direction, and an arrow marks the active sort column. The board defaults to sorting by priority, highest first, so the most urgent notes are always on top. Each row has a jump-to-source link that opens the note at its origin, and a dark / light toggle lives in the header.

The board now remembers where you left it: the active tab, the sort column and direction, and all filters persist across reloads. You can also save named views - a filter set you name once ("high-priority open on project X") and jump straight back to.

Start - the third state from the board

Open notes carry a Start button that moves them to in progress, alongside the existing Resolve / Reopen controls. The full three-state workflow (Open -> In progress -> Resolved) is now reachable directly from the board, not just at the source surface.

Write-back - resolve and reopen in place

The Hub is not read-only. Every note row carries a Resolve button (and Reopen once resolved). Clicking it changes the note's status and writes that change back to the note's real source of truth - so the board and the origin stay in sync without you visiting each project. The Hub routes the change to the right place automatically based on where the note came from:

When the board and the source disagree

A status you set on the board is a hold until the source agrees with it. What happens next depends on whether the Hub can tell who acted last, and it decides that per note:

• Both timestamps parse. The note carries a statusAt the Hub can read, so it compares that against its own override as instants - not as text - and the later action wins. The row shows a quiet held pill.
• It cannot tell. An older build, a stamp in a shape it cannot parse, or a note whose status has never moved. The hold is blind: the pill counts down and the source takes the note back after a few syncs, rather than the Hub silently overriding something it cannot prove is stale.

Every hold expires after seven days regardless of kind, so nothing on the board overrides a source forever. A stamp the Hub cannot parse is treated as absent rather than trusted.

If a write-back fails - a site is unreachable, an Application Password lacks rights - the board surfaces an error toast rather than failing silently.

Export

The Export MD button turns the current view into an Obsidian-friendly Markdown checklist - notes grouped by project, with checkboxes, type and priority, and a link back to each source. It is a tracking digest you can paste into a vault or a ticket, not a generated prompt. You can copy it to the clipboard or download it as a .md file.

Alongside it, a CSV export dumps the current view as a spreadsheet-ready file - the same notes, in a format you can open in a spreadsheet, filter, or hand off. Both exports run locally with no external service.

Passive git status

In the Sources tab you can point each project at its local git repository using the repo action. Once a path is set, that source row shows a read-only indicator of whether the repository is clean or has uncommitted changes, along with the branch. This is purely informational - a glance at which projects have unsaved work - and the Hub takes no action on it.

Assignees and automated work

A planned direction for the Hub is to treat coding agents (Claude and similar) as assignable users alongside people, so a note reads clearly as automated versus manual work. The assignee model already exists on the WordPress surface today. Bringing it to the Hub - including the ability to set an assignee from the board via write-back - is on the Roadmap.

Security posture

The Hub is a loopback-only, single-user local tool, and it is built to stay that way. The hardening in place:

• Loopback bind only. The server binds 127.0.0.1 / ::1 - it does not listen on your network.
• DNS-rebinding guard. Requests with a non-loopback Host header are rejected, so a malicious page cannot rebind a domain to your local Hub.
• Constant-time token comparison. The connect token is checked without leaking timing information.
• Bounded outbound fetches. When the Hub pulls a source, requests are restricted to http(s) and redirects are bounded and re-validated at every hop.
• Protected credential file. sources.json is written with 0600 permissions (owner-only).

It deliberately does not block internal or LAN addresses, because aggregating local development sites - which live exactly there - is the Hub's whole reason for existing. Blocking them would defeat the tool.

Accessibility

The board is keyboard- and screen-reader-operable, not mouse-only:

• Sortable column headers are keyboard-operable and announce their state with aria-sort.
• The status tabs announce which one is active.
• Modals have proper dialog roles, trap focus while open, and close on Esc.
• The light / dark toggle is a real, announced switch control rather than a bare button.

Distribution

The Hub is free and open source, and it is not tied to XAMPP or any one stack - it reads stores wherever they live. It is published on npm - npx red-pen-hub runs it with no install - and a single-file executable is planned, so it runs without an Electron bundle or a Node setup.