Protecting Research Time with a GPS-Aware MacBook Guard

I have been documenting a small but very practical Hammerspoon project for protecting research time on a MacBook.

GitHub links:

• Project repository: HammerspoonWorkMode
• Post source: 2026-04-17-gps-research-time-guard-for-macbook.md

The idea is simple:

• choose one approved location where real research work happens
• when you are physically sitting in that place, the system stays out of your way
• when you leave that place, the Mac starts enforcing stricter behavior rules

That makes the approved place a freedom zone for research, and other places become guarded zones.

What problem it solves

The biggest problem was not lack of tools. It was context drift.

At the right location, I may genuinely need everything:

• Terminal
• browser tabs
• PDFs
• Overleaf
• coding tools
• research notes

But outside that location, the same laptop can easily slide into distraction, low-value browsing, or tool use that looks productive but is really avoidance.

So instead of blocking everything all the time, this project flips the model:

• full freedom in the place where serious work happens
• stronger control everywhere else

How it works

The project is built around two modes:

ALLOW

This mode is active when the machine detects that it is inside one approved GPS area, such as a lab.

In ALLOW mode:

• the system relaxes blocking
• research tools stay usable
• the MacBook can be used freely for writing, reading, coding, analysis, or command-line work

BLOCK

This mode is active when the machine is outside the approved location.

In BLOCK mode:

• blocked apps can be closed automatically
• distracting browser tabs can trigger interventions
• full-screen overlays can appear
• activity is logged for later review
• even tools like Terminal can be restricted if they are listed as blocked outside the approved place

Why this framing matters

I wanted the project documentation to be honest about the intended behavior.

This is not just a generic productivity dashboard.

It is a research-time protection system with one strong promise:

• if you are in the place where you truly work, it should not fight you
• if you are outside that place, it should help control how you use the MacBook

That includes app behavior, browser behavior, and optional command-line restrictions.

Project structure

The work was split into a modular Hammerspoon layout:

• init.lua as the entry point
• location_mode.lua for GPS-based ALLOW / BLOCK
• schedule.lua for work-hour rules
• app_blocker.lua for non-research app enforcement
• browser_filter.lua for distracting URLs and titles
• activity_classifier.lua for research vs off-task heuristics
• overlay.lua for full-screen warnings and lockouts
• logger.lua for activity and marker logs
• config/default.lua for user-editable settings

The documentation was also expanded quite a bit so a non-programmer can follow the setup more easily:

• a main setup guide
• a beginner-friendly getting-started guide
• a “fill in these 5 values only” onboarding page
• helper docs for GPS coordinates and app names
• module-by-module plain-English guides

The practical use case

The clearest example is a lab workflow:

• choose the lab as the approved GPS location
• when sitting in the lab, use the MacBook however needed for research
• when leaving the lab, let the system become stricter

That means the laptop is not permanently locked down. It changes behavior based on where work is actually happening.

Why I like this approach

I like this model because it does not pretend every context is the same.

A browser is not always a distraction. Terminal is not always a distraction. Even coding tools are not always productive.

The important question is not just what app is open, but also where am I and what kind of work context am I in.

That makes location a surprisingly strong signal for protecting research time without making the machine unbearable to use.

If you want to browse the code or setup guides directly, the full project lives on GitHub here: MShirazAhmad/HammerspoonWorkMode.