Add Mac telemetry

Add one Logger where debugging gets vague

This use case is for Mac app flows where “something happened” is too fuzzy to debug from code review alone. Ask Codex to add a few high-signal unified logs around one behavior, run the app, trigger that behavior, and verify from Console or log stream that the expected events fired.

Use the Build macOS Apps plugin for that loop. Its macOS telemetry skill is intentionally lightweight: use Apple’s Logger, choose a clear subsystem/category pair, log action boundaries and state transitions, avoid sensitive payloads, and verify the event after a local build/run instead of assuming the instrumentation is wired correctly.

Why telemetry is useful for agentic engineering

Good logs give Codex a repeatable feedback loop after each patch. Instead of asking you to manually inspect every window, menu action, or sync transition, the agent can run the app, exercise the flow, inspect filtered logs, and decide the next code change from evidence.

That is especially useful for three agentic loops:

• Hands-free debug loop: Codex instruments a suspicious flow, launches the app, clicks the sidebar or triggers a command, reads the emitted log sequence, patches the state update path, and reruns the same flow until the logs and UI behavior agree.
• App session collection loop: Codex adds one event for app launch, window open, sidebar selection, import started, import finished, and import failed, then runs a local session and summarizes the resulting timeline so missing or out-of-order transitions become obvious.
• Human-driven capture loop: Codex launches the app with logging enabled, keeps a focused log stream running while you manually exercise a tricky flow, then inspects the captured session afterward and proposes the next patch from that trace.

Keep the instrumentation small and filterable

Ask Codex for one logger per feature area, not one permanent log line for every state mutation. Feature categories such as Windowing, Commands, MenuBar, Sidebar, Sync, or Import make logs much easier to filter during the next debugging pass.

import OSLog

private let logger = Logger(
  subsystem: Bundle.main.bundleIdentifier ?? "SampleApp",
  category: "Sidebar"
)

@MainActor
func selectItem(_ item: SidebarItem) {
  logger.info("Selected sidebar item: \(item.id, privacy: .public)")
  selection = item.id
}

Use info for concise action and lifecycle events that should remain useful over time, and debug for noisier local state details that may be removed or demoted before the task is done. Add signposts only when you are measuring a timing span, not by default.

Ask Codex to prove the event from logs

The useful part is not just adding Logger calls. Ask Codex to run the app, trigger the instrumented flow, and give you the exact Console filter or log stream predicate it used plus one or two representative log lines.

log stream --style compact --predicate 'subsystem == "com.example.app" && category == "Sidebar"'

If an expected event does not appear, ask Codex to move the log closer to the suspected control path, rerun the same flow, and keep iterating until the logs explain what happened. If the task turns into a crash or backtrace analysis, pivot to the plugin’s build/run debugging workflow and keep the telemetry focused on the action boundaries.

Save a session trace for a later Codex pass

For longer or intermittent bugs, ask Codex to save a focused log stream to a small local trace file, summarize the timeline, and leave that artifact in the workspace so a later Codex run can inspect the same evidence without replaying the whole session from memory. That makes multi-pass debugging easier when you want one agent run to collect a trace and another run to compare behavior before and after a patch.

This also works well when the human needs to drive part of the session. Ask Codex to launch the app in a logging-friendly debug loop, start a filtered capture, wait while you reproduce the issue manually, and then read the saved trace file once you are done.

Practical tips

Instrument one feature at a time

Start with one sidebar, window, command, or sync path so the log sequence stays easy to inspect. If that path becomes reliable, Codex can expand the same pattern to neighboring flows.

Make privacy part of the prompt

Ask Codex to explain every logged identifier and to avoid writing secrets, personal data, or raw content to unified logs. A tiny event vocabulary is usually enough for local debugging.

Keep sample output in the final summary

Representative log lines make the change much easier to trust than “telemetry was added.” Ask Codex to include the filter predicate and a short action timeline so the next agent run can reuse the same verification loop.