The Corona Shield A black eclipse hangs over the desk, its gold corona bent into a shield, and every glowing distraction breaks against it and falls away.
AI-powered productivity analyzer that helps users stay focused by blocking unproductive websites and providing contextual task guidance.
Eclipse Shield uses artificial intelligence to understand your current work context and dynamically blocks distracting websites while asking intelligent questions to keep you on track with your goals.
- π Quick Start
- β¨ Features
- βοΈ Configuration
- ποΈ How It Works
- π Requirements
- π Security
- π Documentation
- π€ Contributing
Warning
The browser extension asks Chrome or Opera for access to the sites you visit: extension/manifest.json lists host permissions for all URLs, plus the tabs and web navigation permissions. It needs that access so each visit can be sent to the Eclipse Shield backend running on your own machine at http://localhost:5000 and checked against your context and rules. Eclipse Shield does not ask macOS for Screen Recording or Accessibility permissions.
Under the corona, in plain words. Set the context in plain words first, then let each visit be judged against it, in the order the Security entry logs.
For macOS users (recommended):
- Read the QUICKSTART.md guide - Complete setup in 3 simple steps
- Run the installer:
./install-local.sh - Optional: add a Google Gemini API key from Google AI Studio, either in
api_key.txtor as theGOOGLE_API_KEYenvironment variable
Without Docker, on any platform:
python3 -m venv venv && source venv/bin/activate
pip install -r requirements.txt -r requirements-secure.txt
python3 secure_app.py # serves http://localhost:5000
curl http://localhost:5000/healthFor other platforms or advanced setup:
| Feature | What it does | Why it matters |
|---|---|---|
| Contextual Understanding | AI analyzes your current task and goals | Blocking decisions follow the work you are doing, not a fixed list alone |
| Smart Blocking | Dynamic website filtering based on work context | Sites that fight your current context are filtered while you work |
| Adaptive Questions | Intelligent prompts to maintain focus | The app checks your intent instead of guessing silently |
| Cross-Platform Extensions | Chrome and Opera support | The same blocking works in either supported browser |
| Real-Time Communication | Secure messaging between browser and backend | The extension and the local backend stay in step on every visit |
| Smooth Blocking | Instant website filtering without page refreshes | A blocked site is stopped at once, without a reload cycle |
| OWASP Top 10 Compliance | Complete security framework implementation | The backend is built against a known security checklist |
| Multi-Layer Defense | Firewall, intrusion detection, and application security | More than one layer has to fail before the app is exposed |
| Production Ready | Automated deployment with security hardening | The same setup can move from a laptop to a server |
- Domain profiles (
settings.json): Each profile (for example work or school) carries its own allowed platforms,blocked_specificsites,blocked_keywords, and blocked categories. Edit the profile that matches the context you are working in. - API key (optional): Add a Google Gemini API key from Google AI Studio in
api_key.txtor as theGOOGLE_API_KEYenvironment variable. The key enables AI decisions for sites that match no explicit rule. - Without a key: The analyzer runs in local rules-only mode: explicit allow and block lists, category rules, and context matching still work, and the
/healthendpoint reports"ai": "local-only". - Full guide: See the Configuration Guide for the remaining settings.
- Setup Your Context: Define your work domains and productivity goals
- AI Learning: Eclipse Shield asks contextual questions about your current task
- Smart Filtering: Based on your responses, the AI determines which sites support your goals
- Dynamic Blocking: Unproductive websites are blocked in real-time
- Continuous Adaptation: The system learns and improves its decisions over time
- Flexible Configuration: Customize rules and contexts for different work scenarios
- Python 3.8+
- Modern web browser (Chrome or Opera)
- Google Gemini API key (optional, free tier available): enables AI decisions for sites that match no explicit rule. Without a key the analyzer runs in local rules-only mode: explicit allow and block lists, category rules, and context matching still work, and the
/healthendpoint reports"ai": "local-only".
- Redis (for rate limiting and caching)
- Nginx (reverse proxy)
- Docker (containerized deployment)
See System Requirements for detailed specifications.
Eclipse Shield implements comprehensive security measures:
- β Input Validation: Prevents injection attacks and malicious inputs
- β Rate Limiting: Protects against abuse and DDoS attacks
- β Secure Authentication: API key management and CSRF protection
- β Privacy Protection: Local processing with encrypted communications
For detailed security information, see SECURITY.md.
Run Security Tests (with the server running):
python3 security_test.py http://localhost:5000Run the automated test suite (no server or API key needed):
python3 -m pytest tests/ -q- π macOS Quick Start - Get started in 3 steps
- βοΈ Configuration Guide - Customize your settings
- π§ Troubleshooting - Common issues and solutions
- ποΈ Installation Guide - Detailed setup instructions
- π Deployment Guide - Production deployment
- π API Reference - API endpoints and usage
- ποΈ Architecture - System design and components
- π‘οΈ Security Guide - Comprehensive security documentation
- π Monitoring - Logging and performance monitoring
- π Backup & Recovery - Data protection procedures
We welcome contributions! Please see our Contributing Guide for details.
This project is licensed under the Creative Commons Attribution-NonCommercial 4.0 International License.
- Quick Issues: Check TROUBLESHOOTING.md
- Documentation: Browse the docs/ folder
- Bug Reports: Use our issue tracker
- Security Issues: See SECURITY.md for reporting procedures
Eclipse Shield - Stay focused, stay productive π―
I drew the system out in Eclipse-Shield-Visuals: an architecture diagram, a component map, a flowchart of one navigation, and a product map, with the written product map, statistics with citations, and the roadmap in VISUAL.md. Every sheet also ships as a PNG photograph of the paper page beside its SVG.

