This page contains 7 additions and 152 deletions.
Need
Runtime verification
Default options
Console.app and log stream --predicate ...
Why it's needed
A concrete log filter plus sample output gives the agent a repeatable handoff and makes the new instrumentation easy to verify across runs.
11name: Add Mac telemetry# 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
295 Constraints:Runtime verification
30 6
317 - Prefer `Logger` from `OSLog`, not `print`, and create a clearDefault options
32 subsystem/category pair for this feature so the logs are easy to filter.
33 8
349 - Log one concise line for each important action boundary or stateConsole.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
3811 - Keep permanent `info` logs stable and high signal. Use `debug` only forWhy it's needed
39 noisy local details, and remove or demote temporary instrumentation before
40 finishing.
41 12
4213 - Do not log secrets, auth tokens, personal data, or raw document contents.A 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.
