Omahub
← All plugins
0

Substack Feed

by 0x4A756E65

A calm, native feed of posts from your Substack subscriptions, with browser handoff and notifications.

GitHub

Security review

No obvious issues detected

Deterministic scan — not a security guarantee

None
Risk level
None
Analyzed commit
510ea9c
Scanned
1 month ago

No potentially dangerous behavior detected in the analyzed commit.

Automated analysis only — not a security guarantee.

AI advisory review

No obvious issues detected

Language-model assessment · ~deepseek/deepseek-v4-flash-latest — advisory only

Low
AI risk level
Low
Recommendation
install
Model
~deepseek/deepseek-v4-flash-latest
Analyzed commit
510ea9c
Reviewed
1 month ago

The plugin is a legitimate, well-contained Substack feed reader with no install hooks, privileged commands, or obfuscation in the sampled code. It defensively restricts network requests to Substack over HTTPS, rejects redirects, runs external commands via argument arrays, and discloses that it stores the user's Substack session cookie in the desktop keyring. Residual risk is limited to the inherent handling of a session credential and the unshown remainder of the backend daemon.

  • Stores a Substack session cookie in the desktop Secret Service keyring; logout is provided and should be used when removing the plugin.
  • The persistent background daemon runs as the desktop user and was only partially sampled, so the remaining backend code deserves a final human glance before publish.
How this check works

This review combines the deterministic scan (the rule-based results above) with an independent look at the plugin's code by a language model. The model reads a trimmed sample of the repository's files, the manifest, and the README, then gives a plain-language risk level and a recommendation: install (no notable danger), review (look closer first), or avoid (clearly dangerous).

It runs on the same analyzed commit as the deterministic scan and is strictly advisory — it is not a security guarantee and never blocks a plugin by itself. A human moderator still reviews plugins before they are listed.

AI advisory only — automated analysis, not a security guarantee.

Install
$ omarchy plugin add https://github.com/0x4A756E65/omarchy-substack --enable
Widgets #bar #quickshell

Omarchy Substack Feed

A calm, native reading desk for the Omarchy bar. It discovers the free and paid Substack publications attached to your account, watches their RSS feeds, sends desktop notifications for genuinely new posts, and opens stories in your normal browser.

It is intentionally not an article reader. Paid content and full article bodies stay on Substack.

The Substack reading desk open beneath the Omarchy bar

Install

omarchy plugin add https://github.com/0x4A756E65/omarchy-substack.git --enable

Click the Substack item in the bar, choose Connect Substack, and sign in on Substack's own page. Password sign-in is the most reliable option; email codes and pasted one-time links are also supported.

Update a Git-managed installation with:

omarchy plugin update aaron.substack

Remove

First open the plugin settings and choose Log out. This deletes the session from the desktop keyring and clears the local feed. Then remove the plugin:

omarchy plugin remove aaron.substack

Removal does not change subscriptions on Substack or overwrite other Omarchy configuration.

What it does

  • Discovers the signed-in reader's current subscriptions.
  • Excludes publications you administer by default, so your own posts do not take over the reading queue.
  • Polls each publication's canonical https://<subdomain>.substack.com/feed.
  • Uses ETag and Last-Modified validators to avoid downloading unchanged feeds.
  • Seeds the initial feed silently, then marks and notifies only later unseen posts.
  • Adapts polling frequency to each publication and exponentially backs off after errors.
  • Keeps polling already-discovered RSS feeds if the Substack session expires.
  • Uses real Substack publication artwork when available and never invents placeholder avatars.
  • Rejects network redirects and limits authenticated requests to Substack's exact HTTPS origin.

Settings

Open the gear in the panel to control:

  • Publication artwork
  • The scrolling newest-post headline in the bar
  • Desktop notifications
  • Whether publications you administer appear in the feed
  • Immediate subscription/feed resync
  • Account reconnection
  • Logout and local-feed removal

Logging out removes the Substack session from the desktop keyring and clears the local feed. It does not unsubscribe from anything on Substack.

Controls

  • Left click: open or close the reading desk.
  • Middle click: resync subscriptions and feeds.
  • Right click: mark all unread posts as read.
  • Click a story or notification: mark it read and open it in the default browser.

Security and storage

The plugin never receives or stores your password. Authentication happens in a dedicated ephemeral WebKit window displaying Substack's website. After a successful login, only Substack's session cookie is saved in the desktop Secret Service keyring.

Feed state lives at:

~/.local/state/omarchy/substack/state.json

The state file contains publication and article metadata, but no session cookie. The cookie is never written to shell.json, the repository, or the plugin directory.

The temporary sign-in window rejects navigation outside Substack and its Cloudflare challenge origin, blocks permission requests, and displays the current origin in its header. Publication and article text is always rendered as plain text.

Architecture and compatibility

Publication RSS feeds are an officially documented Substack feature. Account subscription discovery currently uses the authenticated endpoint used by Substack's web client because Substack does not publish an OAuth or reader API. That endpoint is therefore treated as replaceable: several known response shapes are normalized, subscription refresh failures retain the last good feed, and existing RSS polling continues independently.

The authenticated /api/v1/reader/feed endpoint was evaluated but is not used for the queue: it mixes posts with comments, suggestions, and other social-feed items. Canonical publication RSS is smaller, more predictable, and a better fit for notifications.

Runtime dependencies are provided by Omarchy: Quickshell, Python 3, GTK 3, WebKitGTK 4.1, and the Secret Service command-line client (secret-tool). The plugin has no third-party Python packages, install hooks, privileged commands, or bundled executable dependencies.

Security reports are welcome through GitHub's private vulnerability reporting flow; see SECURITY.md.

This project is independent and is not affiliated with or endorsed by Substack.

Development

omarchy plugin validate .
python3 -m unittest discover -s tests -v
python3 -m py_compile substack_backend.py

Useful local commands:

python3 substack_backend.py status
python3 substack_backend.py refresh
python3 substack_backend.py disconnect

License

MIT