Imported from henno/stillcolor-watchdog (AGENTS.md). Install upstream with npx skills add henno/stillcolor-watchdog. Copyright stays with the author.

AGENTS.md

Project Goal

The purpose of this directory is to investigate and mitigate cases where Stillcolor on macOS does not reliably keep temporal dithering disabled.

This is not meant to be theoretical research. The goal is to find a practical and reliable approach that reduces or eliminates situations where dithering silently turns back on.

What Stillcolor Does

Stillcolor is a macOS app intended to disable GPU/DCP-side temporal dithering on Apple Silicon Macs.

For this project, treat temporal dithering as a real accessibility problem whose presence or absence directly affects usability.

How To Verify Dithering State

The current verification command is:

ioreg -lw0 | grep -i enableDither

Interpretation:

• enableDither = No means dithering is disabled
• enableDither = Yes means dithering is enabled

Important notes:

• the output may contain multiple lines
• if all lines are Yes, Stillcolor did not actually apply the change at that moment
• if the lines are No, Stillcolor has applied the change at least at that moment

Observed Problem

Stillcolor's menu bar UI may show settings such as:

• Disable Dithering
• Disable uniformity2D

but that does not always mean dithering is actually disabled.

Observed failure mode:

• Stillcolor appears to be configured to disable dithering
• ioreg -lw0 | grep -i enableDither still shows Yes
• restarting Stillcolor has been observed to change enableDither from Yes back to No

That suggests one or more of the following:

1. Stillcolor sometimes fails to apply its change
2. Stillcolor applies the change, but later loses effect
3. a system event restores dithering
4. the Stillcolor UI does not always reflect the real system state

Working Assumptions

Use these assumptions as the starting point:

• restarting Stillcolor can sometimes change enableDither from Yes to No
• the main question is not whether Stillcolor can work at all
• the main question is why the effect does not always remain active

What This Directory Should Contain

The work in this directory should focus on practical mitigation and diagnostics.

Preferred directions:

1. Reproduce The Problem

Identify which events can flip enableDither back to Yes, including at least:

• Stillcolor launch
• Stillcolor restart
• login
• logout/login
• sleep/wake
• display lock/unlock
• external monitor attach/detach
• resolution or scaling changes
• refresh rate changes
• True Tone on/off
• Night Shift on/off
• HDR on/off

2. Automate State Checking

Create small utilities or scripts that:

• check enableDither regularly
• log state transitions
• clearly distinguish Yes from No

3. Add Recovery

Find a way to automatically disable dithering again when it turns back on.

Examples:

• watchdog script
• launchd agent
• wake hook
• menu bar helper
• combined logging and recovery

4. Root Cause Analysis

If possible, determine:

• what Stillcolor changes internally
• why the change does not always persist
• whether the issue is tied to a specific macOS version, Apple Silicon generation, or display state change
• whether the UI reflects desired state instead of actual state

Do Not Assume

Do not assume:

• the problem is imaginary or purely subjective
• the UI checkmark always reflects the real state
• a running app automatically means the effect is still active
• the issue is irrelevant just because other display variables may also affect comfort

The focus of this project is specific:

Stillcolor does not always remain effectively applied.

Desired Outcome

Good outcomes would include one of the following:

1. a confirmed explanation of which event turns dithering back on
2. a reliable automatic workaround that restores Stillcolor's effect quickly
3. a patch that improves Stillcolor's reliability
4. a diagnostic toolkit that captures precise evidence for later fixes

The most valuable outcome is something that is actually usable in day-to-day work.

Practical Rules

• prefer small, testable steps
• every hypothesis should be testable
• every test should include before/after verification with:

ioreg -lw0 | grep -i enableDither

• prefer simple and robust scripts
• if you build a watchdog, log:
  • check time
  • observed state
  • action taken
  • result after action

Suggested First Steps

1. map the events that may change enableDither
2. create a minimal state-check script that clearly returns Yes or No
3. create a minimal watchdog prototype that restarts Stillcolor when the state returns to Yes
4. add logging so later analysis can correlate state changes with context