How to Record a Code Walkthrough Video for a Pull Request

A good pull request video walkthrough runs under two minutes and shows one window at a large font size. It covers three things: why the change exists, the two or three parts of the diff that matter, and the change running. To record one, raise your editor's font size, record only the editor or browser window, zoom in on the lines you discuss, blur anything secret, and attach the MP4 to the PR below the written description.

The built-in macOS recorder (⇧⌘5, Shift-Command-5) is enough for a short clip with no secrets on screen. Screen Bolt adds three things that matter for code: it records a single window, it creates zooms from your clicks, and it lets you blur things after recording. These matter because reviewers often watch in a small inline player.

When a PR video beats a written description

A video is worth the extra minute in these cases:

• The change is visual or behavioral. UI changes, animations, loading states and error flows are faster to show than to describe.
• The reading order matters. In a refactor across 15 files, a video can say "start with this interface, then the two call sites." The file list on a diff page can't do that.
• Reviewers are in other time zones. A walkthrough can replace the call you'd otherwise schedule.
• You want feedback on one decision. Point at the exact line and say "I went back and forth on this." The review that comes back is more focused.

Skip the video for small diffs, dependency bumps and anything the reviewer needs to search or copy. Video can't be searched or diffed. Always keep the written description. The video adds context to the text and doesn't replace it.

What a good pull request video walkthrough looks like

• Short. Under two minutes. Reviewers watch it before they read the diff, not instead of reading it.
• One window. The editor or the browser. No Slack, email or second monitor in the frame.
• Readable at a small size. Code that reads fine on a large display can be illegible in a PR page's inline player.
• Ordered for the reviewer. Why first, then the risky part of the diff, then the demo.
• No secrets. No .env values, tokens, customer emails or internal hostnames, either in the frame or in the files you share.

This structure fits in two minutes:

Set up your editor for video

Do this before you press record. Each step makes the code easier to read once it's scaled down to a small player.

1. Increase the font size. In VS Code, open Settings, search for "font size" and raise Editor: Font Size to somewhere around 18 to 22. You can also press ⌘= (Command-Equals) to zoom the whole window. In Terminal, ⌘+ makes text bigger.
2. Hide panels you won't talk about. Close the sidebar (⌘B in VS Code), the minimap and any panels you don't need. The code gets that width back.
3. Close every tab that isn't part of the PR. This is the easiest way to keep .env, secrets.yaml and scratch files out of the shot.
4. Size the window to a video shape. A roughly 16:9 window fills a standard video frame without empty bars. About 1280×720 points works well. On a Retina display, Screen Bolt captures at 2× the window's size in points, so that window records at 2560×1440. That leaves headroom for zooms and a 1080p export.
5. Silence notifications. Turn on a Focus such as Do Not Disturb from Control Center.
6. Prepare the demo state. Have the branch running, test data loaded and the browser tab open at the right URL. Clear the terminal (⌘K in Terminal) so old output with tokens or paths doesn't show.
7. Set the frame rate (Screen Bolt). In Settings ▸ Quick export, Frame rate controls the recording as well as the export. It defaults to 60 FPS. 30 FPS is enough for code.
8. Write three bullets: what changed, why, and what to review. Screen Bolt's Script button opens a teleprompter that isn't captured in the recording, so you can keep the bullets in view while you talk. For more on type size and contrast, see how to make text readable in screen recordings.

Record the diff and the demo

With the built-in macOS tools

1. Press ⇧⌘5 to open the Screenshot toolbar.
2. Choose Record Selected Portion and drag the frame around your editor window.
3. Open Options and pick your microphone.
4. Click Record, talk through the diff and the demo, then click the stop button in the menu bar.
5. Open the file in QuickTime Player and choose Edit ▸ Trim (⌘T) to cut the start and end.

This works, and it's free. It has two limits for code. The toolbar records a fixed rectangle, not a window, so anything that passes over that area gets recorded too. And there's no zoom and no way to blur a line afterwards. You end up with a trimmed clip and nothing else.

With Screen Bolt

Screen Bolt's Window mode records one window on its own, even when something covers it. A Slack window dragged over your editor won't end up in the video.

1. In the recording bar, open Mic and choose your microphone. Unless you need them, open Camera and choose Don't record camera, then open Audio and choose Don't record system audio.
2. Choose Record ▸ Record window (⌥⌘4, Option-Command-4). This shortcut only works while Screen Bolt is the active app.
3. In Select Window to Record, click your editor window and press Return (or click Record Window). Recording starts right away, with no countdown.
4. Walk through the diff. Click on each line as you talk about it. The next section explains why.
5. If you need to switch branches or restart the server, click Pause in the bar. Screen Bolt removes the pause gap from the recording.
6. Click Stop. With the default settings, the editor opens with zooms already created from your clicks.

If the diff and the demo are in different apps, you have two options:

• Do both in the browser. Open the diff view on your code host (on GitHub, Files changed) and run the app in another tab of the same browser window. You're still recording that one window, so it captures whichever tab is showing.
• Use Area mode. Put the editor and browser side by side and drag an area around both. Area mode records everything inside the rectangle, so silence notifications first.

For more on window capture, see how to record a single window on Mac and the recording docs.

Zooms and cursor settings that keep code readable

Even at a larger font size, a full editor window is hard to read in a small player. Zooming in on the lines you're discussing fixes that.

Where auto zoom comes from. Screen Bolt creates zoom regions from mouse clicks. Clicks within 1 second and 200 px of each other merge into one zoom, and each zoom holds for at least 1.8 seconds. Three details matter for code:

• Typing doesn't create zooms. Only clicks do. If you edit code live, click on the line first.
• Drags are ignored. Selecting text by dragging won't trigger a zoom. Click the line first, then select.
• The zoom centers on the cursor. You can't move a zoom's focus point later, so rest the pointer on the code you're explaining.

Adjust zooms in the editor:

1. Open the Zoom panel (⌘5 in the editor). Default Level starts at 2.0×. For code, a lower level such as 1.5× keeps more surrounding lines in view. Set it, then click Apply to All Regions.
2. To remove a zoom, right-click the region on the zoom track and choose Delete This Region.
3. To add a zoom where you didn't click, move the playhead there and press ⌘K (Command-K) or click Add Zoom at Playhead. The zoom centers on wherever your cursor was at that moment.
4. If a zoom feels abrupt, right-click the region and change Transition Speed. Smooth (0.60s) suits code.

Leave Auto Zoom on Click on. Turning it off disables every zoom region in preview and export, including the ones you added by hand. Cursor settings for code. In the Cursor panel, Size defaults to 3.0×. A cursor that large can cover the code you're explaining, so try something closer to 1.5×. Keep Smooth Movement on so moving between lines doesn't look jittery. If the cursor sits over code while you talk, turn on Auto-hide when Static. Don't rely on turning off Show Cursor: it hides the cursor in the preview, but the export still draws it.

For more on zooms in general, see how to zoom in on a screen recording on Mac.

Hide .env files and keys

The best protection is never showing a secret at all, which is why the setup steps close those tabs. In VS Code you can also hide .env from the file tree for the session. Add a **/.env pattern to the files.exclude setting, and remove it afterwards to undo.

If a secret does appear, fix it in the Screen Bolt editor before you export. Finish your cuts and speed changes first, then add blurs.

Blur a specific line or value

1. Move the playhead to where the secret first appears.
2. Press B, or click Add Blur Region in the Effects panel. This adds a 5-second blur.
3. In Edit Blur Region, set Style to Solid Color. A solid block is the safest choice for keys and tokens. Gaussian or Pixelate are fine for less sensitive text, such as a username.
4. Use Region (X / Y / W / H) to cover the value. Stretch Duration (up to 60 s) so it covers every frame where the value is visible.
5. Scrub through the whole range. Manual regions don't track moving text, so check the frames around zooms and scrolling closely. Add more regions, or cut that part, wherever the value slips out from under the blur.

Scan for emails and keywords

Effects ▸ Blur / Privacy ▸ Auto-Detect Sensitive Text scans the recording on your Mac using Apple's Vision text recognition. It blurs every email address it finds. It can also blur phone numbers (turn on Also detect phone numbers) and any terms you enter in Custom keywords (comma separated). Keywords aren't case-sensitive. These blurs follow the text through zooms and scrolling.

Good keywords are internal hostnames, your company domain and customer names. The scan doesn't look for API keys or tokens, so cover those with manual blur regions.

Run the scan after you've finished cutting. Detected regions aren't re-timed if you later reorder clips, add cuts or change speed. When the scan finishes, it reports how many regions it added. Review each one on the Blur track before you export.

Where the secret still exists

• The raw recording. Your .screenbolt project keeps the original, unblurred recording.mov. The blur only exists in exported files.
• The toolbar Share button. Share sends that raw recording.mov through the macOS share sheet, not your edited version. For PR videos, always use Export.
• The project file. The scan saves matched text as each blur item's label in project.json. Don't share the project folder.
• Live blur zones in Window mode. The Blur button in the recording bar draws frosted zones on your screen. In Window mode, though, Screen Bolt captures the window directly, so those zones don't appear in the recording. Use editor blurs instead.

If a real key was visible in a video someone has already seen, rotate the key. Blurring the video later doesn't make the key secret again.

The effects docs cover every blur and focus option.

Export the file and attach it to the PR

Screen Bolt doesn't upload anything or create share links. You export a local file and attach it to the PR, or put it wherever your team keeps files.

1. In the editor, click Export.
2. Under Format, choose MP4 (H.264, the in-app note says "Plays everywhere").
3. Under Quality, choose 1080p with a license, or 720p on the free version.
4. Check the size estimate in the summary line against your code host's attachment limit. If the file is too big, cut more, or close the sheet and lower Compression in Settings ▸ Quick export. Web uses half the bitrate of the default Social Media, and Web (Low) uses a quarter.
5. Click Export. When it's done, Finder shows the file. The default Save to folder is the Desktop.
6. Drag the MP4 into the PR description, under your written summary.

GIF is a poor fit for narrated walkthroughs. Screen Bolt's GIFs are silent, play at about 10 fps, are 640 or 960 px wide, and need a license. A GIF only makes sense for a few seconds of UI with no voice. To compare video formats, see MP4 vs MOV.

On the free version: exports are capped at 3 minutes and 720p, and they carry a "Made with Screen Bolt" watermark. A two-minute PR video fits the length limit. However, the export sheet checks the 3-minute cap against the full recording, not the trimmed result. Keep the raw take under 3 minutes. The export docs list every limit.

Common mistakes

• Recording the whole display. Your second monitor, open tabs and notifications end up in the video. Record one window.
• Default font size. Text that looks fine on your screen is unreadable in an inline player. Raise the size before recording.
• Narrating line by line. Reviewers can read. Spend the time on why, not what.
• Typing instead of clicking. Typing doesn't trigger a zoom. Click the line you're talking about.
• Changing speed with J or L by accident. In the editor, J and L change the project's speed, and that speed is exported. Before exporting, check that the speed menu reads "1x".
• Using Share instead of Export. Share sends the raw, unblurred recording.
• Dropping the written description. The reviewer still needs text to search and quote.

If you record longer code videos for teaching rather than review, see the guide to recording developer tutorials on macOS. For reproducing a bug instead of explaining a fix, see how to record a bug report video.

Screen Bolt has a free version with no time limit. You can download Screen Bolt for Mac and upgrade later if you need 1080p and no watermark.