Substack Notification Filter - Browser Extension

A Chrome extension to filter Substack notifications based on keywords, engagement, and other criteria.

🚧 Current Status: STARTER TEMPLATE

This is a starter template that provides the basic structure. It needs customization based on Substack's actual DOM structure.

What's Included

• ✅ Extension manifest (V3)
• ✅ Content script with filtering logic framework
• ✅ Settings popup interface
• ✅ Basic styling
• ⚠️ Placeholder DOM selectors (need to be customized)

What Needs to Be Done

1. Inspect Substack's DOM Structure

Before the extension will work, you need to:

1. Go to https://substack.com/notifications
2. Open Chrome DevTools (F12)
3. Inspect notification elements
4. Document the actual selectors for:
   • Notification container
   • Individual notification items
   • Username/author
   • Comment text
   • Like count
   • Notification type

2. Update Content Script Selectors

In content.js, replace the TODO placeholders:

// Line ~75: Find notification elements
const notificationElements = document.querySelectorAll('[ACTUAL-SELECTOR]');

// Line ~120: Extract username
const usernameElement = element.querySelector('[ACTUAL-USERNAME-SELECTOR]');

// Line ~126: Extract like count
const likeElement = element.querySelector('[ACTUAL-LIKE-SELECTOR]');

3. Test and Iterate

Load the extension in Chrome and test:

1. Does it detect notifications?
2. Does filtering work correctly?
3. Does the UI show up properly?

Installation (for testing)

1. Open Chrome and go to chrome://extensions/
2. Enable "Developer mode" (top right toggle)
3. Click "Load unpacked"
4. Select the substack-extension-starter folder
5. Navigate to https://substack.com/notifications
6. Open DevTools console to see debug logs

Icon Files Needed

The extension references icon files that don't exist yet. You need to create:

icons/
  icon16.png   (16x16)
  icon48.png   (48x48)
  icon128.png  (128x128)

For now, you can use any placeholder images or remove the icon references from manifest.json.

Features Implemented

Filtering Criteria

• ✅ Keyword/slur blacklist
• ✅ Minimum likes threshold
• ✅ Follow status (manual user list management)

UI Features

• ✅ Filter statistics display
• ✅ Toggle to show/hide filtered notifications
• ✅ Settings popup with configuration
• ✅ Visual distinction for filtered items

Technical Features

• ✅ Chrome storage sync
• ✅ Mutation observer for dynamic content
• ✅ Message passing between popup and content script

File Structure

substack-extension-starter/
├── manifest.json          # Extension configuration
├── content.js             # Main filtering logic (runs on Substack)
├── styles.css             # UI styling
├── popup.html             # Settings interface
├── popup.js               # Settings logic
├── icons/                 # (needs to be created)
│   ├── icon16.png
│   ├── icon48.png
│   └── icon128.png
└── README.md              # This file

Development Workflow with Claude Code

Recommended approach:

1. Inspect Substack

   # Open browser to Substack notifications
   # Document selectors in a file

2. Update selectors in content.js

   # Use Claude Code to edit content.js with real selectors
   claude code edit content.js

3. Test

   # Reload extension in Chrome
   # Check console for errors
   # Verify filtering works

4. Iterate

   • Fix bugs
   • Improve selectors
   • Add features
   • Refine UI

Configuration Options

Settings available in the popup (click extension icon):

• Enable/disable filtering: Master toggle
• Blocked keywords: One per line, case-insensitive
• Minimum likes: Filter notifications below this threshold
• Only show from followed users: Enable to hide notifications from users not in your followed list
• Followed users list: Manually add usernames (one per line, without @ symbol)

Known Limitations

1. Follow status requires manual management - Users must manually add usernames to the followed list
2. No icon files - Will show default extension icon
3. Substack might change their structure - Will require maintenance if DOM classes change

Debugging

Check the console logs:

• Content script logs: Open page, press F12, go to Console
• Background/popup logs: Go to chrome://extensions, click "service worker" or "Inspect popup"

Common issues:

• "No notifications found" → Wrong selectors
• "Config not loading" → Storage permission issue
• "UI not appearing" → Wrong container selector

Next Steps

1. ✅ Research complete (see main research doc)
2. ✅ Customize DOM selectors
3. ✅ Add follow status detection
4. 🔄 YOU ARE HERE → Test extension functionality
5. ⏳ Create icon files
6. ⏳ Polish UI/UX
7. ⏳ Add advanced features

Support

This is a development template. For issues:

1. Check browser console for errors
2. Verify Substack hasn't changed their structure
3. Update selectors as needed

License

This template is provided as-is for development purposes.