How it works

What counts as reading

The extension ticks once per second for each file that is currently readable. A file earns a second only when all of the following hold:

• The browser tab is focused. Background tabs earn nothing.
• The file's diff is on screen: at least a third of the file is visible, or the file fills at least a third of the viewport. The second case is what reading a long file actually looks like.
• The diff content is rendered. Collapsed files and diffs GitHub has not loaded yet earn nothing, even when their header is visible.
• The file is not excluded by your rules, and has not already met its threshold. Time never accrues past the requirement.

Nothing else is recorded. No keystrokes, no scroll positions inside files, no mouse movement, no page contents. See Privacy and security.

Heartbeats

Accumulated seconds flush to the API in batches every 15 seconds, and immediately when the tab blurs or unloads. Each heartbeat is a set of (file, deltaSeconds) pairs. Failed flushes are retried with the seconds intact, so a flaky connection does not lose reading time. The server treats its own total as a floor and never lets a refresh shrink your local progress.

Per-file thresholds

Each file's requirement comes from your reading rules:

required = clamp(
  minSecondsPerFile,
  minSecondsPerFile + ceil(changedLines * secondsPer100Lines / 100),
  maxSecondsPerFile
)

With the defaults (15s floor, 5s per 100 changed lines, 180s cap), a 40-line change needs 17 seconds and a 2,000-line change needs 115. A deleted file needs only the floor. The ring beside each file shows progress against exactly this number.

From heartbeat to check

1. A PR opens or a new commit is pushed. The GitHub App records the changed files and posts the check as Waiting on review.
2. Reviewers read. Heartbeats accumulate into per-reviewer, per-file reading sessions.
3. After each batch, the server re-evaluates the PR against its rule. When every non-excluded file meets its threshold for a required reader, the check completes as All files read.
4. A new push resets the evaluation for the new commit. Files whose diffs did not change keep their read state.

Who has to read

By default, one requested reviewer completing the read is enough. With requireAllReviewers enabled, every assigned reviewer must meet the thresholds before the check completes. Details in Reading rules.