Neuron Daily Newsletter Automation

Why This Exists: Reading the Neuron Daily newsletter is a great way to start the day, but manually clicking through all the article links takes time. This automation opens everything at once, so you can spend your morning reading instead of clicking. Built collaboratively with Claude AI to solve a real daily workflow need.

If this saves you time too, give it a ⭐ and let us know how it works for you!

Cross-platform automation system that automatically opens the latest Neuron Daily newsletter with all article links in separate tabs every weekday morning.

Supported Platforms: Linux, macOS, Windows

📚 Complete Documentation | 💻 GitHub Repository

Project Review

📊 Complete Project Review & Analysis - Comprehensive technical documentation, architecture decisions, development history, and future roadmap.

📋 Table of Contents

• Project Review
• Features
• Quick Start
  • Option 1: pip Install (Recommended)
  • Option 2: Manual Installation
  • Test the Installation
• Usage
  • Automatic Operation
  • Manual Operation
• How It Works: Smart Multi-Run System
  • Daily Schedule
  • Smart Detection Logic
  • Chrome Browser Integration & Persistence
  • System Management
• 📅 Blacklist Time Rewind Tool
  • Quick Examples
  • Use Cases
  • Complete Documentation
• Configuration
  • Key Settings
  • Customizing the Schedule
• Troubleshooting
  • Common Issues
  • Debug Mode
  • Manual Testing
• File Structure
• Advanced Usage
  • Running in Different Modes
  • Custom Link Filtering
  • Headless Mode
  • Custom Selectors
• Security Considerations
• Performance
• Uninstallation
• Contributing
  • Development Setup
  • Testing
  • Project Roadmap
• Updating
  • Easy Update Method
  • Update Process
  • What's Preserved
  • Manual Update
  • Version Management
• Changelog
• License
• Support

Features

• ✅ Smart Multi-Run System: Multiple scheduled runs with intelligent change detection
• ✅ Optimal Newsletter Coverage: Catches newsletters regardless of publication time (5:00-7:00 AM)
• ✅ Intelligent Link Extraction: Finds and filters relevant article links
• ✅ Error Recovery: Robust retry mechanisms and comprehensive error handling
• ✅ Cross-Platform: Works on Linux, macOS, and Windows
• ✅ System Integration: Automatic scheduling (systemd/launchd/Task Scheduler)
• ✅ Easy Installation: Platform-specific installers or pip install
• ✅ Shell Compatibility: Auto-detects and configures bash, zsh, fish, and Oh My Zsh
• ✅ Logging: Detailed logging for troubleshooting
• ✅ Configuration: Easily customizable settings
• ✅ Chrome Integration: Opens tabs in your regular Chrome browser (preserves existing tabs)
• ✅ Link Management: Advanced blacklist system prevents duplicate reading and tracks analytics
• ✅ Time Rewind Tool: Go back in time and restore previously blacklisted content for re-learning
• ✅ Network Resilience: Checks connectivity before running

Quick Start

Option 1: Git Clone (Current Method)

git clone https://github.com/pem725/NeuronAutomator.git
cd NeuronAutomator
./installers/install_linux.sh  # or install_macos.sh / install_windows.ps1

Option 2: pip Install (Coming Soon)

# Package not yet on PyPI - use git clone method above
# pip install neuron-automation  # Will be available in future release
# neuron-automation --setup

Manual Installation Steps

1. Clone the Repository

git clone https://github.com/pem725/NeuronAutomator.git
cd NeuronAutomator

2. Run Platform-Specific Installer

Linux (Ubuntu/Debian)

chmod +x installers/install_linux.sh
./installers/install_linux.sh

macOS

chmod +x installers/install_macos.sh
./installers/install_macos.sh

Windows

# Run PowerShell as Administrator
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
.\installers\install_windows.ps1

The installer will:

• Install system dependencies (Python, Chrome, package managers)
• Create a virtual environment with required packages
• Set up automatic scheduling (systemd/launchd/Task Scheduler)
• Configure the system to run multiple times each weekday morning (5:30, 6:00, 6:30, 7:00 AM)
• Detect and configure your shell (bash, zsh, fish) with proper PATH settings
• Handle Oh My Zsh and other shell frameworks automatically

3. Test the Installation

Test that everything works:

neuron-automation

This should open Chrome with the Neuron Daily newsletter and article tabs.

Usage

Automatic Operation

The script runs automatically at 5:30, 6:00, 6:30, and 7:00 AM on weekdays, with smart detection to prevent redundant executions.

Manual Operation

Run manually anytime:

neuron-automation

Check version:

neuron-automation --version

Check for updates:

neuron-automation --check-updates

How It Works: Smart Multi-Run System

The automation uses a sophisticated Phase 2 approach that combines multiple scheduled runs with intelligent content detection:

📅 Daily Schedule

• 5:30 AM: Early check (catches early publications)
• 6:00 AM: Primary window (most common publication time)
• 6:30 AM: Late catch (for delayed publications)
• 7:00 AM: Final safety net (covers very late publications)

🧠 Smart Detection Logic

Scenario 1: Normal Publication (6:15 AM)

• 5:30 AM → Finds old content → Proceeds (user gets yesterday's articles temporarily)
• 6:00 AM → Same old content → SKIPS (smart detection prevents redundancy)
• 6:30 AM → NEW content detected! → Proceeds (user gets today's articles)
• 7:00 AM → Same new content → SKIPS (already got today's content)

Scenario 2: Late Publication (6:45 AM)

• 5:30 AM, 6:00 AM, 6:30 AM → All skip old content after first run
• 7:00 AM → NEW content detected! → Proceeds (catches late publication)

Result: Perfect coverage with zero redundancy ✨

🌐 Chrome Browser Integration & Persistence

The automation integrates seamlessly with your Chrome browser and keeps tabs open after script completion:

✅ Browser Persistence Features:

• Tabs Stay Open: Browser detaches after automation, keeping all newsletter tabs accessible
• No Premature Closing: Script ending does NOT close your reading tabs
• Morning Workflow: Perfect for getting up to pre-opened articles ready to read
• Manual Control: Only you decide when to close the tabs

✅ Integration Benefits:

• Regular Profile: Uses your bookmarks, extensions, and settings
• Existing Windows: Connects to running Chrome when possible
• Smart Detection: Prevents opening duplicate content on multiple runs
• Error Handling: Only successful runs leave browser open (failures close automatically)

📖 Reading Scenarios:

• Early Bird (6:00 AM): Automation runs, tabs open → read immediately
• Late Riser (8:00 AM): Earlier tabs still open and waiting for you
• Multiple Runs: Smart detection prevents duplicates, adds only new content
• Browser Persistence: Tabs remain accessible until you manually close them

System Management

Check if the timer is active:

systemctl status neuron-automation.timer

View service logs:

journalctl -u neuron-automation.service

View application logs:

tail -f ~/.config/neuron-automation/neuron_automation.log

Stop the automatic timer:

sudo systemctl stop neuron-automation.timer
sudo systemctl disable neuron-automation.timer

Re-enable the timer:

sudo systemctl enable neuron-automation.timer
sudo systemctl start neuron-automation.timer

📅 Blacklist Time Rewind Tool

The Time Rewind Tool lets you "go back in time" and restore previously blacklisted links, making them available for reading again. Perfect for testing learning patterns, content review, and experimentation.

Quick Examples

# Preview what a 7-day rewind would restore (safe preview)
neuron-automation --rewind-preview 7

# Restore links blacklisted in the last 5 days
neuron-automation --rewind 5

# Show recently blacklisted content
neuron-automation --recent-blacklisted 10

# Use standalone tool with more options
blacklist-rewind --stats
blacklist-rewind --backup

Use Cases

• 🧪 Learning Experiments: Test how re-introducing content affects retention
• 📚 Content Review: Bring back important articles for reinforcement learning
• 🔄 Pattern Testing: Experiment with different content exposure cycles
• 🛡️ Recovery: Undo accidental over-blacklisting of valuable content
• ⏰ Content Rotation: Manage long-term content availability strategically

Complete Documentation

📖 Full Blacklist Rewind Usage Guide - Comprehensive guide with examples, best practices, and advanced workflows

Configuration

The script can be customized by editing the configuration file:

nano ~/.config/neuron-automation/config.py

Key Settings

Setting	Description	Default
BASE_URL	Newsletter URL	https://www.theneurondaily.com/
ENABLED_DAYS	Days to run (0=Monday, 6=Sunday)	[0,1,2,3,4] (weekdays)
MAX_RETRIES	Retry attempts on failure	3
PAGE_LOAD_TIMEOUT	Page load timeout (seconds)	30
CHROME_OPTIONS	Chrome browser options	See config.py
LOG_LEVEL	Logging verbosity	INFO

Customizing the Schedule

To change when the script runs, edit the systemd timer:

sudo systemctl edit neuron-automation.timer

Add your custom schedule:

[Timer]
# Add an additional run at 7:30 AM
OnCalendar=Mon,Tue,Wed,Thu,Fri *-*-* 07:30:00

Common schedule formats:

• *-*-* 09:00:00 - Daily at 9:00 AM
• Mon *-*-* 05:30:00 - Mondays only at 5:30 AM
• *-*-01 05:30:00 - First day of every month

Troubleshooting

Common Issues

Chrome not opening:

# Check if Chrome is installed
google-chrome --version

# Check Chrome driver
~/.config/neuron-automation/venv/bin/python -c "from selenium import webdriver; print('Selenium OK')"

Permission errors:

# Fix permissions
chmod +x /usr/local/bin/neuron-automation
sudo chown -R $USER:$USER ~/.config/neuron-automation/

Service not running:

# Check service status
systemctl status neuron-automation.service

# View recent logs
journalctl -u neuron-automation.service -n 50

Network issues:

# Test connectivity
curl -I https://www.theneurondaily.com/

Debug Mode

Enable debug logging by editing the config:

LOG_LEVEL = "DEBUG"

Or use the development configuration:

ACTIVE_CONFIG = DevelopmentConfig

Manual Testing

Test individual components:

# Activate the virtual environment
source ~/.config/neuron-automation/venv/bin/activate

# Test the script directly
cd ~/.config/neuron-automation
python3 neuron_automation.py

File Structure

~/.config/neuron-automation/
├── neuron_automation.py      # Main script
├── config.py                 # Configuration file
├── venv/                     # Python virtual environment
├── neuron_automation.log     # Application logs
├── requirements.txt          # Python dependencies
└── uninstall.sh             # Uninstallation script

/usr/local/bin/
└── neuron-automation        # System command wrapper

/etc/systemd/system/
├── neuron-automation.service # Systemd service
└── neuron-automation.timer   # Systemd timer

Advanced Usage

Running in Different Modes

Test mode (minimal retries, debug logging):

# Edit config.py and change:
ACTIVE_CONFIG = TestConfig

Development mode (verbose logging, runs every day):

# Edit config.py and change:
ACTIVE_CONFIG = DevelopmentConfig

Custom Link Filtering

Modify link filtering by editing these config variables:

SKIP_LINK_PATTERNS = [
    # Add patterns to skip
    'advertisement', 'promo', 'sponsor'
]

SKIP_TEXT_PATTERNS = [
    # Add text patterns to skip
    'buy now', 'limited time'
]

Headless Mode

Run without opening browser windows:

CHROME_OPTIONS = [
    "--headless",
    "--no-sandbox",
    "--disable-dev-shm-usage"
]

Custom Selectors

If the website structure changes, update selectors:

CONTENT_SELECTORS = [
    ".newsletter-content",  # Add site-specific selectors
    ".article-list"
]

Browser Behavior & Persistence

Why Tabs Stay Open

The automation is designed to keep your newsletter tabs open after the script finishes:

• ✅ Intended Behavior: Tabs remain open for you to read at your own pace
• ✅ Persistent Access: Articles stay available until you manually close them
• ✅ Morning Ready: Wake up to pre-opened content waiting for you
• ✅ No Rush: Read articles throughout the day without time pressure

What You Should See

1. Script Opens: Browser launches with main newsletter site
2. Newsletter Loads: Latest newsletter post opens in new window
3. Tabs Open: Article links open in additional tabs (one by one)
4. Script Ends: Automation completes but browser stays open
5. Read When Ready: All tabs remain accessible for reading

Troubleshooting Browser Closure

If your browser closes immediately after opening tabs, this indicates an error occurred:

# Check the logs to see what went wrong
tail -20 ~/.config/neuron-automation/neuron_automation.log

# Try running manually with verbose output
neuron-automation --verbose

Common causes of premature closure:

• Network connectivity issues during tab loading
• Chrome driver compatibility problems
• Permission or security restrictions
• System resource limitations

Security Considerations

• The script opens tabs in your regular Chrome browser, using your existing profile and settings
• When possible, it connects to existing Chrome instances rather than creating new ones
• Browser Persistence: Successful automation runs leave tabs open indefinitely for reading
• Automatic Cleanup: Failed automation attempts close browser windows to prevent resource waste
• Logs may contain URLs visited - review log files if sharing system access
• The script only accesses the specified newsletter URL and extracted links
• Privacy Note: Newsletter tabs remain accessible in your browser until manually closed

Performance

Resource Usage:

• Memory: ~100-200MB during execution
• CPU: Low (brief spike during Chrome startup)
• Disk: ~50MB for virtual environment and dependencies
• Network: Minimal (loads newsletter page once, then opens tabs)

Optimization Tips:

• Use headless mode to reduce resource usage
• Adjust PAGE_LOAD_TIMEOUT for slower connections
• Reduce MAX_RETRIES if network is reliable

Uninstallation

To completely remove the automation:

~/.config/neuron-automation/uninstall.sh

This will:

• Stop and disable the systemd timer
• Remove all system files
• Optionally remove configuration and logs

Contributing

Development Setup

1. Fork the project
2. Create a development environment:

python3 -m venv dev-env
source dev-env/bin/activate
pip install -r requirements.txt

3. Use the test configuration:

ACTIVE_CONFIG = TestConfig

Testing

Run tests with different configurations:

# Test with current site
python3 neuron_automation.py

# Test connectivity
python3 -c "from neuron_automation import NeuronNewsletterAutomation; n=NeuronNewsletterAutomation(); print(n.check_internet_connectivity())"

Project Roadmap

See TODO.md for:

• 📚 Complete project history and evolution
• ✅ Current implementation status
• 🚧 Future enhancement ideas and priorities
• 💡 Community and ecosystem possibilities
• 🔧 Technical debt and maintenance tasks

Changelog

Version 1.6.0 (October 2025)

• Fixed: Browser persistence and tab population on Linux
  • Resolved "user data directory in use" errors
  • Removed conflicting Linux-specific profile code
  • Simplified to dedicated automation profile for all platforms
• Added: PROJECT_REVIEW.md comprehensive project documentation
  • Architecture decisions and technical documentation
  • Development history and evolution
  • Future roadmap and planned enhancements
• Improved: Documentation website integration
  • Added prominent Netlify website links (https://neuronautomator.netlify.app/)
  • Updated README with documentation and GitHub links
  • Enhanced docs homepage with Quick Links section
• Fixed: Cross-platform browser behavior consistency
  • Unified Chrome setup for Linux and macOS
  • Browser stays open reliably after automation completes
  • Successfully tested with 43 newsletter tabs

Version 1.5.0

• Enhanced browser persistence options
• Cross-platform improvements
• Link management system
• Blacklist time rewind functionality

Version 1.0.0

• Initial release
• Automated weekday newsletter opening
• Intelligent link extraction
• Systemd integration
• Comprehensive error handling
• Configurable settings

License

MIT License - feel free to modify and distribute.

Support

For issues or questions:

1. Check the troubleshooting section above
2. Review logs in ~/.config/neuron-automation/neuron_automation.log
3. Test manually with debug logging enabled
4. Check systemd service status and logs

System Requirements:

• Ubuntu 18.04+ (or compatible Debian-based distribution)
• Python 3.6+
• Internet connection
• X11 display server (for GUI Chrome)

Tested On:

• Ubuntu 20.04 LTS
• Ubuntu 22.04 LTS
• Ubuntu 24.04 LTS

Updating

The system includes an automatic update mechanism to easily upgrade to newer versions while preserving your configuration.

Easy Update Method

Linux/macOS:

./update.sh

Windows:

update.bat

Update Process

The updater will:

1. 📦 Backup your current configuration and logs
2. 🌐 Download the latest version from GitHub
3. 🔧 Install the new version using platform-specific installers
4. 📂 Restore your preserved settings and data
5. ✅ Verify the update completed successfully

What's Preserved

• Configuration files and customizations
• Application logs
• Content change detection cache

Manual Update

If the automatic updater doesn't work:

1. Download latest version:

   git clone https://github.com/pem725/NeuronAutomator.git neuron-update
   cd neuron-update

2. Run installer:

   # Linux
   ./installers/install_linux.sh
   
   # macOS
   ./installers/install_macos.sh
   
   # Windows (PowerShell as Admin)
   .\installers\install_windows.ps1

Version Management

• Check current version: neuron-automation --version
• Check for updates: neuron-automation --check-updates
• View update history on GitHub Releases