Code review
Walking a colleague through a code review on a screen share
A review call is expensive. It is worth it exactly when the comment thread has stopped converging.
Most reviews should stay in the thread
Asynchronous review is not a compromise forced on remote teams — it is better than a call for the common case. It leaves a record, it lets the reviewer think at their own speed, and it survives the reviewer being asleep. A call replaces all of that with two people's undivided attention and produces nothing anyone can read afterwards.
So the question is not whether to review on a call. It is whether this particular pull request has hit one of the few states where the thread has stopped working. There are about four.
Worth a call
The change is structural
A refactor that touches thirty files reviewed file by file is reviewed in the wrong unit. The shape of the change is the thing under review, and the diff view actively hides it.
Worth a call
The thread has stopped converging
Three rounds in, the comments are getting longer and no closer. That is a disagreement about approach wearing a comment thread's clothes, and it usually resolves in ten minutes of talking.
Worth a call
The reviewer is new to this code
You are not asking for approval, you are transferring context. A walkthrough teaches the subsystem and gets the review done as a side effect.
Not worth a call
The review is merely long
Volume is not a reason. A long, mechanical review is faster in the thread, where both people can work through it without holding a slot in a calendar.
Decide who drives before the call starts
The most common way a review call wastes half an hour is that neither person decided whose screen it is. The author narrates their own change while the reviewer silently reads a diff on their own monitor, and the two conversations never meet.
Pick one, say it out loud in the first ten seconds, and let the other person interrupt freely.
| Format | Who shares | Fits when |
|---|---|---|
| Author walkthrough | The author, showing the change in the order it was made | The reviewer needs context before they can judge anything — a new subsystem, a large refactor |
| Reviewer interrogation | The reviewer, driving through their own open questions | The reviewer has already read the diff and arrives with a specific list |
| Joint editing | Whoever is typing, swapping when the other has the idea | The fix is small, known, and faster to make than to describe — this is pairing, not review |
| Neither — go back to the thread | Nobody | The disagreement is about a decision nobody on the call is allowed to make |
Leave the review readable before you talk
GitHub's review model already has the vocabulary for this. A review is submitted as a comment, an approval, or a request for changes; reviewers can comment on specific lines, suggest exact changes, and those review conversations stay in the pull request timeline where the team can track the feedback and the decisions. A call that happens instead of using any of it produces a merged pull request with no explanation attached.
So do the async part first, even when you know a call is coming. Leave the line comments you already have, and use the call for the ones you could not phrase. It turns the call from a reading exercise into a conversation about the four things that were genuinely unclear.
- Batch line comments into one review rather than firing them individually — the author gets one coherent pass instead of eleven notifications.
- Put the summary of what the change does in the pull request description, not in the call. The call is for the part that would not fit there.
- If the diff is unreadable in file order, say so in the description and name the order you want it read in.
- Separate the blocking comments from the preferences explicitly. Half of all review friction is a reviewer's taste being read as a requirement.
Navigating a diff live without losing the room
Once you are sharing, everything you do with the keyboard becomes invisible to the other person. You press two keys and a different file appears; they see a jump they cannot follow and cannot reproduce later on their own machine. Over a review call that matters more than usual, because half the value of a walkthrough is the other person learning to navigate the code themselves.
GitHub documents its own shortcuts for exactly this navigation, and they are worth learning whether or not anyone is watching. The file finder on t, jumping to a line with l, showing or hiding comments on diffs with i, opening blame with b, and g c and g p to move between a repository's Code and Pull requests tabs. On the Files changed tab, c opens the commits dropdown to filter the diff — which is often the fastest way to make a large refactor legible, one commit at a time.
A keystroke overlay closes the visibility gap. Show KeyPress draws each press as a keycap in an always-on-top window on your display, so the person watching sees the chord that caused the jump rather than only the jump. There is no integration with GitHub, no browser extension and no plugin for your conferencing tool — it is simply drawn on screen, which is why it works with all of them.
Show the code, not just the diff
A diff is a poor representation of a change and a worse one of a system. It shows what moved, in file order, with no callers, no tests running, and no history. Most of what makes a review call worth having is the things a diff cannot show, and they all live outside the browser tab.
Jump to the definition of the thing being changed and show its other callers. Run the test that covers it and let the reviewer watch it fail against the old code. Open blame on the block being replaced and read out why it was written that way three years ago. Each of those takes twenty seconds and answers a comment thread that would have taken two days.
- Show the failing case first, then the fix. A reviewer who has seen the bug reproduce reviews a different pull request to one who has only read about it.
- When you jump between the browser and the editor, say which is which — over a compressed share, two dark windows of text look identical for the first second.
- If the reviewer says stop, stop and let them read. Silence while somebody reads is not dead air, it is the review.
Turn the call back into a record
The call has no memory. Whatever you agreed exists only in two people's heads until one of them writes it down, and the person who most needs it — the engineer who opens this file in eight months — was not on the call at all.
Close the loop the same day. Whoever drove writes the outcome into the pull request: the decisions, the reasoning that was not obvious, and anything deferred to a follow-up issue. Submit it as a comment, an approval or a request for changes so the review state matches what actually happened.
If the walkthrough was really a context transfer — a subsystem tour that happened to be attached to a pull request — consider recording it instead of holding it again next quarter. Any recorder that captures the display captures the overlay along with it, because the keycaps are drawn on the screen; Show KeyPress records nothing itself.
What the overlay does not do here
- It shows your keys only. The reviewer's presses are on their machine, and each Mac draws its own input — a two-way call needs the app on both.
- It has no connection to GitHub, GitLab or any review tool, and cannot annotate a diff, a comment or a review state.
- While macOS Secure Input is active — a password field, an unlock dialog, a terminal with Secure Keyboard Entry — the keyboard visualization is cleared and a short Keyboard hidden — Secure Input banner appears instead. Turn off Show Status HUD under General if you would rather the call saw nothing at all.
- It runs on macOS 14 or later and nowhere else, so a colleague on Windows or Linux cannot show their keys back to you.
- Nothing is logged. Key events are processed on device, are never persisted, and the app has no network entitlement — there is no record of what was typed during a review.
Sources and further reading
Product details and guidance were checked against these first-party pages on August 5, 2026. Re-check current listings before making an install or high-stakes decision.
- About pull request reviews
GitHub
GitHub's description of review states — comment, approve, request changes — and of line-level review conversations.
- Keyboard shortcuts
GitHub
GitHub's own shortcut reference, covering the file finder, line jumps, blame and the pull request review keys.
- Sharing your screen in a Zoom meeting
Zoom
Zoom's screen share options, including sharing a whole desktop versus one window.
- Secure Keyboard Entry
Apple
How macOS Secure Keyboard Entry stops other apps from receiving key events.
FAQ
Questions people ask
Should code review happen on a call at all?
Usually not. Asynchronous review leaves a record, works across time zones and lets the reviewer think at their own pace. Reserve calls for structural changes, threads that have stopped converging, and reviewers who need the context more than they need the diff.
Why should I show my keyboard during a review walkthrough?
Because half of a walkthrough is teaching someone to move around the code themselves. If they only see files appearing, they learn this change; if they see the chord as well, they learn the navigation, which is the part that outlives the pull request.
The other person cannot see my keycaps — what is wrong?
You are almost certainly sharing a single application window. The overlay is a separate always-on-top window, so it is not part of your browser's content. Re-share the whole screen, and check the overlay is pinned to the display you shared.
Do I need to write anything in the pull request if we talked it through?
Yes, and it is the step teams skip. The call convinces two people; the review record convinces everyone who reads the code later. Submit the outcome as a review — comment, approve or request changes — with the reasoning attached.