Skip to content

About

Eclipse Shield is an advanced AI productivity analyzer tool designed to help users stay focused on their tasks by blocking unproductive websites and providing contextual questions to understand the user's task better.

Resources

Code of conduct

Contributing

Security policy

Stars

1 star

Watchers

0 watching

Forks

Latest commit

Β 

History

19 Commits

Folders and files

NameName
Last commit message
Last commit date
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

Repository files navigation

Banner: the eclipse shield at full span, distracting app windows bouncing off its corona while the desk below stays calm and lit

Eclipse Shield Eclipse Shield logo: a black eclipse disc with a gold corona curving into a shield

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.

macOS License Python

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.

Scene: the corona shield, its rays pulsing while stray windows drift in and rebound

Major separator


🎩 Table of Contents


πŸš€ Quick Start

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):

  1. Read the QUICKSTART.md guide - Complete setup in 3 simple steps
  2. Run the installer: ./install-local.sh
  3. Optional: add a Google Gemini API key from Google AI Studio, either in api_key.txt or as the GOOGLE_API_KEY environment 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/health

For other platforms or advanced setup:


Major separator

✨ Features

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

βš™οΈ Configuration

  • Domain profiles (settings.json): Each profile (for example work or school) carries its own allowed platforms, blocked_specific sites, 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.txt or as the GOOGLE_API_KEY environment 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 /health endpoint reports "ai": "local-only".
  • Full guide: See the Configuration Guide for the remaining settings.

πŸ—οΈ How It Works

  1. Setup Your Context: Define your work domains and productivity goals
  2. AI Learning: Eclipse Shield asks contextual questions about your current task
  3. Smart Filtering: Based on your responses, the AI determines which sites support your goals
  4. Dynamic Blocking: Unproductive websites are blocked in real-time
  5. Continuous Adaptation: The system learns and improves its decisions over time
  6. Flexible Configuration: Customize rules and contexts for different work scenarios

πŸ“‹ Requirements

Minimum Requirements

  • 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 /health endpoint reports "ai": "local-only".

For Production Use

  • Redis (for rate limiting and caching)
  • Nginx (reverse proxy)
  • Docker (containerized deployment)

See System Requirements for detailed specifications.


Minor separator

πŸ”’ Security

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:5000

Run the automated test suite (no server or API key needed):

python3 -m pytest tests/ -q

πŸ“– Documentation

User Guides

Technical Documentation

Security & Operations


🀝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Quick Links


πŸ“„ License

This project is licensed under the Creative Commons Attribution-NonCommercial 4.0 International License.


πŸ†˜ Need Help?


Eclipse Shield - Stay focused, stay productive 🎯


Intro: a worker at a desk at night, the eclipse shield hanging in the sky above, its gold corona turning aside a rain of glowing app windows

Diagrams and maps

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.

Eclipse Shield architecture

About

Eclipse Shield is an advanced AI productivity analyzer tool designed to help users stay focused on their tasks by blocking unproductive websites and providing contextual questions to understand the user's task better.

Resources

Code of conduct

Contributing

Security policy

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages