1name: Add Mac telemetry1# Add Mac telemetry | Codex use cases

2tagline: Use Codex to instrument one Mac feature with Logger, run the app, and

3 verify the action from unified logs.

4summary: Use Codex and the Build macOS Apps plugin to add a few high-signal

5 `Logger` events around windows, sidebars, commands, or sync flows, then run

6 the app and prove from Console or `log stream` that the right actions fired.

7skills:

8 - token: build-macos-apps

9 url: https://github.com/openai/plugins/tree/main/plugins/build-macos-apps

10 description: Use the macOS telemetry and build/run skills to add structured

11 `OSLog` instrumentation, launch the app, exercise the UI path, and verify

12 the emitted events from Console or `log stream`.

13bestFor:

14 - Mac app features where Codex needs a reliable trace of window opening,

15 sidebar selection, menu commands, menu bar actions, sync milestones, or

16 fallback paths

17 - Agentic debugging loops where Codex should patch code, rerun the app,

18 inspect logs, and decide the next fix from evidence instead of guessing

19 - Local app-session collection loops where you want a compact sequence of user

20 actions and app lifecycle events that can be compared across repeated runs

21starterPrompt:

22 title: Instrument One Feature and Verify It from Logs

23 body: >-

24 Use the Build macOS Apps plugin to add lightweight unified logging around

25 [name one Mac feature or action flow], then run the app and verify from logs

26 that those events fire in the expected order.

27 2 

3Need

28 4 

29 Constraints:5Runtime verification

30 6 

31 - Prefer `Logger` from `OSLog`, not `print`, and create a clear7Default options

32 subsystem/category pair for this feature so the logs are easy to filter.

33 8 

34 - Log one concise line for each important action boundary or state9Console.app and `log stream --predicate ...`

35 transition: for example window opened, sidebar selection changed, menu

36 command invoked, sync started, sync finished, or fallback path taken.

37 10 

38 - Keep permanent `info` logs stable and high signal. Use `debug` only for11Why it's needed

39 noisy local details, and remove or demote temporary instrumentation before

40 finishing.

41 12 

42 - Do not log secrets, auth tokens, personal data, or raw document contents.13A concrete log filter plus sample output gives the agent a repeatable handoff and makes the new instrumentation easy to verify across runs.

43 If an identifier must be logged, choose the safest privacy annotation and

44 explain why.

45 14 

46 - Build and run the app, exercise the feature path yourself, and verify the

47 events with Console or a focused `log stream` predicate.

48 

49 - If the flow is long, intermittent, or easier to reproduce by hand, save

50 the filtered log stream to a small local session trace file, let me manually

51 exercise the app if needed, then read that file back and summarize the event

52 timeline.

53 

54 - If an expected event does not appear, move the log closer to the suspected

55 control path, rerun the flow, and continue until the logs explain what

56 happened.

57 

58 

59 Deliver:

60 

61 - the new logger setup and the exact events you added

62 

63 - the Console filter or `log stream` predicate you used

64 

65 - a short before/after summary of what the logs now make observable

66 

67 - the saved trace file and timeline summary if this became a longer capture

68 session

69 

70 - one or two representative log lines that prove the flow is instrumented

71 correctly

72relatedLinks:

73 - label: Build macOS Apps plugin

74 url: https://github.com/openai/plugins/tree/main/plugins/build-macos-apps

75 - label: Agent skills

76 url: /codex/skills

77techStack:

78 - need: App logging

79 goodDefault: "[OSLog Logger](https://developer.apple.com/documentation/os/logger)"

80 why: Structured unified logging gives Codex a narrow, filterable feedback loop

81 without turning the codebase into a wall of `print` statements.

82 - need: Agent workflow

83 goodDefault: "[Build macOS Apps

84 plugin](https://github.com/openai/plugins/tree/main/plugins/build-macos-a\

85 pps)"

86 why: "The plugin's telemetry and build/run skills are designed to work together:

87 instrument one flow, launch the app, inspect logs, and tighten the event

88 set."

89 - need: Runtime verification

90 goodDefault: Console.app and `log stream --predicate ...`

91 why: A concrete log filter plus sample output gives the agent a repeatable

92 handoff and makes the new instrumentation easy to verify across runs.

93 

94## Add one Logger where debugging gets vague

95 

96This 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.

97 

98Use the [Build macOS Apps plugin](https://github.com/openai/plugins/tree/main/plugins/build-macos-apps) 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.

99 

100## Why telemetry is useful for agentic engineering

101 

102Good 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.

103 

104That is especially useful for three agentic loops:

105 

106- **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.

107- **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.

108- **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.

109 

110## Keep the instrumentation small and filterable

111 

112Ask 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.

113 

114```swift

115import OSLog

116 

117private let logger = Logger(

118 subsystem: Bundle.main.bundleIdentifier ?? "SampleApp",

119 category: "Sidebar"

120)

121 

122@MainActor

123func selectItem(_ item: SidebarItem) {

124 logger.info("Selected sidebar item: \(item.id, privacy: .public)")

125 selection = item.id

126}

127```

128 

129Use `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.

130 

131## Ask Codex to prove the event from logs

132 

133The 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.

134 

135```bash

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

137```

138 

139If 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.

140 

141## Save a session trace for a later Codex pass

142 

143For 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.

144 

145This 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.

146 

147## Practical tips

148 

149### Instrument one feature at a time

150 

151Start 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.

152 

153### Make privacy part of the prompt

154 

155Ask 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.

156 

157### Keep sample output in the final summary

158 

159Representative 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.