BuildLens User Guide

Build less blindly.
See what changed.

BuildLens watches Xcode build output and turns errors and warnings into persistent diagnostic sessions you can compare, filter, revisit, and act on.

Overview

What BuildLens does.

BuildLens is a native macOS developer utility that captures Xcode build diagnostics and keeps them visible after the build output would normally disappear into Xcode's activity stream. It is built around errors, warnings, build-to-build comparison, history, and direct navigation back to the source.

BuildLens does not build your project for you.

Keep working normally in Xcode. BuildLens watches the result and organizes the diagnostics.

Basic workflow

Build → capture → compare → act.

1. Run BuildLens.

Leave BuildLens available while you work in Xcode.

2. Build in Xcode.

Build your project normally. BuildLens watches for the resulting build diagnostics.

3. Review the captured session.

Errors and warnings become a persistent BuildLens session rather than temporary build-stream noise.

4. Act on what matters.

Open the source location, copy the diagnostic, pin a warning, ignore known noise, or move to another build.

Comparison

New since last build. Fixed since last build.

BuildLens compares the current build with the previous captured build for the same project. The first captured build establishes a baseline. Beginning with the next build, diagnostics can be identified as new or fixed.

New

A diagnostic appears in the current build that was not present in the previous comparison build.

Fixed

A diagnostic that existed previously no longer appears in the current build.

Clipboard

Copy the useful part.

Copy Clean Error

Copies the shorter useful diagnostic without dragging the surrounding build noise along with it.

Copy for ChatGPT

Includes useful troubleshooting context such as severity, file, line, column, message, and raw diagnostic text.

No AI is required by BuildLens.

The app can prepare diagnostic context for ChatGPT, but BuildLens itself does not require an AI service, account, cloud dependency, or subscription.

Focus

Pin, ignore, filter, and search.

Use filtering and search when a build becomes crowded. Pin a warning when you want it kept visible. Ignore a known diagnostic when it is not useful right now. BuildLens preserves pin and ignore preferences between sessions.

Build history

Recent builds stay available.

BuildLens keeps recent build sessions so you can move between results without losing the last build. The product view keeps four recent builds in sight, with older captured builds available through history navigation.

Testing & reset

Test without waiting for a broken build.

Import Plain-Text Log…

Load a text or log file manually when you want to test BuildLens with existing diagnostic material.

Sample diagnostics

Use the sample-diagnostics command to verify the interface without waiting for a real Xcode failure.

Restart watcher

If build capture appears stalled, restart the watcher and perform another Xcode build.

Clear Build History

Remove stored sessions and reset the comparison baseline when you want to begin fresh.

Troubleshooting

If a build does not look right.

If a build is missing, make sure BuildLens is running and build again. If a build appears incomplete, give Xcode a moment to finish writing its activity log; BuildLens retries incomplete logs automatically. For project selection, comparison questions, navigation problems, or capture issues, the Support page has the focused checks.