User guide

Installing

For installation instructions, refer to the separate installation guide.

Configuring

To update the configuration, select “Configure” from the system tray icon menu.

You should see a screen like this:

There is documentation in the configuration file that explains the various configuration options. A few of these are called about below.

🏆 Setting up a daily deep work goal

By default, there are no deep work goals set for any days of the week:

# For each day in your maker schedule, how many deep work hours are you targeting?
# Set to 0 if you don't have any deep work goals for that day, or remove the day entirely.
# The numbers can be whole numbers or decimals (eg, 1.5)
deep_work_hours_goal_by_day = { Mon = 0, Tue = 0, Wed = 0, Thu = 0, Fri = 0 }

If you set this to a number (including fractions), the you can track against your deep work goals. When you hit your deep work goal, you will see a full-screen popup notification letting you know.

Example config:

deep_work_hours_goal_by_day = { Mon = 4, Tue = 4, Wed = 6, Thu = 4, Fri = 2.5, Sat = 0, Sun = 2 }

⚒️ Setting up a work schedule

The configuration file has a default schedule of:

maker_schedule_days = ["Mon", "Tue", "Wed", "Thu", "Fri"]

and

maker_schedule_hour_ranges = ["9-18"]

This configuration ensures the app monitors and analyzes screenshots only during these specified times. For the hour ranges, you can specify a comma seperated list of hour ranges, like: ["9-17", "20-22"].

This means that the app will only monitor and analyze screenshots during these times.

🙅🏻‍♀️ Enabling distraction blockers

To enable real-time work deviation alerts during working hours, update the configuration:

enable_distraction_blocker = true

This activates full-screen alerts for non-work activities detected during work hours.

You can also tune the settings of these, see Advanced Configuration below.

The distraction blocker screen looks like this:

If you don’t get distraction blockers as expected, see the Understanding the Event Log section.

📄 Customize what is categorized as deep work

Customize the categories in the configuration to meet your specific needs, tailored for software engineers.

It is geared towards the categories of a software engineer, but you can update it to suit your particular flavor of deep work.

🔑 Use OpenAI API instead of LLama3

To use OpenAI instead of the Llama3 model, enter your OpenAI API key.

You will need to:

• Create or get an existing key from https://platform.openai.com/
• Set the openai_api_key to this value
• Set llava_backend to OpenAI
• Update llm_model to one of the OpenAI models, for example gpt-4o

⏰ Tuning the screenshot capture frequency

By default, these two configuration values control how often screenshots are collected:

duration_between_screen_captures_secs = 45

By default, the app captures your current screenshot every 45 seconds.

It’s not recommended to lower duration_between_screen_captures_secs below 30 seconds since it will use a lot of CPU.

⚙️ Understanding how it works

Here’s how distraction blockers work:

1. Wait 45 seconds (unless changed in configuration)
2. Check what the active app is, for example Google Chrome. If it’s Chrome or Safari, also check the browser URL.
3. Wait another 45 seconds - has the app changed or is it the same app? If it’s Chrome or Safari, also check if its the same browser URL.
4. The app takes a screenshot and retrieves OCR text via a local OSX API call if you’re using the same app and browser URL (for browsers), are actively using the computer, and it’s within scheduled hours. It skips this step if recently a distraction blocker was shown.
5. Invoke the LLM with the OCR text and pass the prompt, and receive a category and productivity score. If the OCR text is similar to a previous result, it will reuse that result instead.
6. The app analyzes the OCR text with the LLM, receiving a category and productivity score, and reuses the result for similar OCR text.
7. The app then deletes the screenshot, with an option to save it for event log display.
8. If consecutive low-productivity snapshots fall below a threshold, the app displays a distraction blocker, unless disabled. Otherwise, it resets the low-productivity count.

🔒 Data security

MakerTime automatically takes screenshots every 45 seconds by default.

• 🦙 MakerTime analyzes screenshots locally using the Llama3 open weights model.
• ⛁ MakerTime temporarily saves any collected screenshots to your hard drive in the /Users/<username>/Library/Application Support/ai.makertime directory, and then immediately deletes them a few seconds later after analysis.
• 📄 MakerTime does not send logs or any usage data to servers.

To purge any collected screenshots, see the Uninstalling + purging data section below.

If you update the configuration to use OpenAI instead of the default llama3 local model, refer to the OpenAI data security notes.

🛠️ Advanced configuration

🙅🏻‍♀️ Preventing certain apps and websites from being processed by the LLM

For enhanced privacy, MakerTime can ignore specific apps or websites by adding them to a “deny list,” useful for both OpenAI and local Llama3 analyses.

Note: The deny list only works for Chrome and Safari. Contact us for support with other browsers.

Here are the configuration values and instructions for using this feature:

# List of apps that should not be captured by screenshot since they will likely contain
# sensitive information
app_screenshot_denylist = ["com.apple.finder"]

# List of domain names that should not be captured by screenshot in either Chrome or Safari,
# since they might contain sensitive information.  Enter the domain name without http or https,
# exact match only (no wildcards supported).  Only Chrome and Safari supported for this feature
# at the moment.
# Example list of domain names:
#  ["meet.google.com", "teams.microsoft.com", "teams.live.com"]
url_screenshot_denylist = []

💥 Minimizing false positive distraction blockers

To minimize false positives with distraction blockers, consider these tips.

Via tuning the number of consecutive distraction threshold

Adjust the num_consecutive_distractions_before_block setting to reduce false positives.

The configuration value that you can tune is this, which is by default set to:

num_consecutive_distractions_before_block = 3

This setting triggers a distraction blocker after three consecutive low scores.

With this setting, if you are still getting consistent false positives, and the prompt tuning isn’t helping, you could try raising this to 4 and seeing if it helps.

If you feel like you are able to slack off too long without getting a distraction blocker, then try updating the num_consecutive_distractions_before_block to a lower value, for example:

num_consecutive_distractions_before_block = 2

😴 Snoozing distraction blockers

To snooze a distraction blocker when not working, follow these steps:

That’s currently the only way to snooze distraction blockers.

🧐 Understanding the Event Log

Annotated columns

Click this screenshot to show a zoomed-in version:

Icon explanation by column

Overall action	LLM call	Deep Work	Screenshot
🪞 Ignored event because it detected MakerTime was running	🔘 Did not call LLM	🔘 N/A	🔘 N/A
💾 Re-use prior cached LLM result with similar screenshot	✅ LLM call success	🙌 Performing Deep Work	🖥️ View Screenshot
🚶 Switching between apps or browser URLs	🚫 LLM call failed	😬 Apparently not in the zone
💥 Unexpected error
⏳ Ignored because there was a recent distraction blocker
💸 Exceeded LLM daily budget (OpenAI only)
🔧 Dev Mode
🔲 Screen was blank
🏖️ Outside scheduled hours
😴 Snoozed
🤖 Called LLM for analysis
🔘 Idle (no mouse or keystrokes)
🙅🏻‍♀️ App was in denylist

🔋 Battery usage notes

MakerTime only calls the LLM when the device is plugged in and the battery is over 90% charged.

If the battery charge falls below 25%, MakerTime will not call the LLM, regardless of power status.

Adjust the only_analyze_screenshots_while_plugged_in value to change this behavior.

Debug logs

Locate debug logs at:

/Users/<username>/Library/Logs/ai.makertime

Uninstalling + purging data

For data purging instructions, see the Uninstalling guide