xcodebug 1.2.0 → 1.2.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -59,24 +59,24 @@ a session is running therefore has no effect on that session.
59
59
 
60
60
  ## Claude Code and Codex (MCP)
61
61
 
62
- Neither client has an in-process extension API - tools reach them as MCP servers.
63
- `mcp/server.ts` is that adapter: it loads `index.ts` with a stub host and serves
64
- the tool it registers, so it exposes the same actions and arguments as the pi
65
- extension rather than a parallel implementation.
62
+ The shared actions reach both clients through MCP. `mcp/server.ts` loads
63
+ `index.ts` with a stub host and serves the tool it registers, so it exposes the
64
+ same actions and arguments as the pi extension rather than a parallel
65
+ implementation. Claude Code can also load the optional native display below.
66
66
 
67
67
  ### Set up (once per machine)
68
68
 
69
69
  ```bash
70
70
  npm i -g xcodebug@latest # installs the latest published release
71
71
  codex mcp add xcodebug -- bun "$(npm root -g)/xcodebug/mcp/server.ts"
72
- claude mcp add xcodebug -- bun "$(npm root -g)/xcodebug/mcp/server.ts"
72
+ claude mcp add --scope user xcodebug -- bun "$(npm root -g)/xcodebug/mcp/server.ts"
73
73
  ```
74
74
 
75
75
  Working from a checkout instead? Point both at `mcp/server.ts` in the repo:
76
76
 
77
77
  ```bash
78
78
  codex mcp add xcodebug -- bun /path/to/xcodebug/mcp/server.ts
79
- claude mcp add xcodebug -- bun /path/to/xcodebug/mcp/server.ts
79
+ claude mcp add --scope user xcodebug -- bun /path/to/xcodebug/mcp/server.ts
80
80
  ```
81
81
 
82
82
  Bun is required ([bun.sh](https://bun.sh)). The sources are TypeScript, and Node
@@ -92,6 +92,75 @@ codex mcp list # xcodebug bun …
92
92
  claude mcp list # xcodebug: … ✔ Connected
93
93
  ```
94
94
 
95
+ Set Codex's MCP timeout high enough for the stages your calls use. For example,
96
+ 4200 seconds leaves room for the default 15-minute pod install, 15-minute build
97
+ and 30-minute command budgets, plus device operations. Increase it if you pass
98
+ larger timeouts; the client can still cancel before xcodebug's own deadline.
99
+
100
+ ```toml
101
+ [mcp_servers.xcodebug]
102
+ tool_timeout_sec = 4200
103
+ ```
104
+
105
+ Claude Code needs no setting for this. Its default limit on a tool call is about
106
+ 28 hours. It also ends a call to a stdio server that has sent neither a reply
107
+ nor a progress notification for 30 minutes; this server sends progress once a
108
+ second to a client that asks for it.
109
+
110
+ Cancelling an MCP request aborts that request. On SIGINT, SIGTERM or detected
111
+ stdout loss, the server stops accepting work, cancels admitted requests and
112
+ then cleans up captures. Closing only stdin lets admitted requests finish and
113
+ sends their replies; a silent lost reader cannot be distinguished from this
114
+ until stdout closes or a write fails.
115
+
116
+ To run `npm test` from a checkout, use Node.js 22.18 or later and put Bun on PATH
117
+ for the stdio integration tests.
118
+
119
+ ### Install the manual entry point
120
+
121
+ Connecting MCP makes the tool available to the model; it does not register a
122
+ `/xcodebug` command in either client. The shared
123
+ [xcodebug skill](skills/xcodebug/SKILL.md) adds an explicit entry point:
124
+ `/xcodebug` in Claude Code, `$xcodebug` in Codex, or Codex's `/skills` picker.
125
+
126
+ Both clients can read the same skill directory through user-level symlinks:
127
+
128
+ ```bash
129
+ XCODEBUG_DIR="/absolute/path/to/xcodebug" # a checkout containing the skill
130
+ # For an npm package that includes the skill, use this instead:
131
+ # XCODEBUG_DIR="$(npm root -g)/xcodebug"
132
+
133
+ (
134
+ source="$XCODEBUG_DIR/skills/xcodebug"
135
+ test -f "$source/SKILL.md" || { printf 'Skill not found: %s\n' "$source/SKILL.md" >&2; exit 1; }
136
+ for dest in "$HOME/.agents/skills/xcodebug" "$HOME/.claude/skills/xcodebug"; do
137
+ if test -e "$dest" || test -L "$dest"; then
138
+ if ! test -L "$dest" || ! test "$dest" -ef "$source"; then
139
+ printf 'Existing skill path: %s; inspect it before installing.\n' "$dest" >&2
140
+ exit 1
141
+ fi
142
+ fi
143
+ done
144
+ mkdir -p "$HOME/.agents/skills" "$HOME/.claude/skills" || exit 1
145
+ for dest in "$HOME/.agents/skills/xcodebug" "$HOME/.claude/skills/xcodebug"; do
146
+ test -L "$dest" || ln -s "$source" "$dest" || exit 1
147
+ done
148
+ )
149
+ ```
150
+
151
+ If the installed package does not contain `skills/xcodebug/SKILL.md`, use a
152
+ checkout that contains it. The commands check both target paths before installing,
153
+ skip symlinks already pointing to this skill, and stop on other existing files,
154
+ directories or symlinks, including broken links.
155
+ Keep the checkout or npm package at the linked path. Updating that source updates
156
+ the shared skill for both clients.
157
+
158
+ Start a new Claude Code or Codex session after installing. The skill uses the
159
+ MCP connection already configured above; it does not start a separate server or
160
+ replace the native pi command. Both manual and model-selected invocation remain
161
+ available. See the clients' [Claude Code skill documentation](https://code.claude.com/docs/en/skills)
162
+ and [Codex skill documentation](https://learn.chatgpt.com/docs/build-skills).
163
+
95
164
  ### Use
96
165
 
97
166
  Start the client **in the project directory**. The server inherits its cwd, and
@@ -102,7 +171,32 @@ cd ~/myapp # holds the .xcworkspace or .xcodeproj
102
171
  codex # or: claude
103
172
  ```
104
173
 
105
- Then ask for the outcome; the model calls the tool:
174
+ Enter these in the client's chat input, not in your shell, after installing the skill:
175
+
176
+ | Operation | Claude Code | Codex |
177
+ |---|---|---|
178
+ | Build, install and launch with defaults | `/xcodebug` | `$xcodebug` |
179
+ | Show capture status | `/xcodebug status` | `$xcodebug status` |
180
+ | Check the toolchain | `/xcodebug doctor` | `$xcodebug doctor` |
181
+ | List devices | `/xcodebug devices` | `$xcodebug devices` |
182
+ | Build, install and launch | `/xcodebug launch scheme=MyApp` | `$xcodebug launch scheme=MyApp` |
183
+ | Read filtered logs | `/xcodebug logs grep="Weather Sync" limit=100` | `$xcodebug logs grep="Weather Sync" limit=100` |
184
+ | Wait for an event | `/xcodebug wait match="sync complete" timeoutSeconds=30` | `$xcodebug wait match="sync complete" timeoutSeconds=30` |
185
+ | Rebuild and rerun the last launch | `/xcodebug restart` | `$xcodebug restart` |
186
+ | Stop capture, leave the app running | `/xcodebug stop` | `$xcodebug stop` |
187
+
188
+ A bare skill invocation calls `{"action":"launch"}`: it builds as needed, installs,
189
+ launches and starts capturing using the server's project/device defaults. Use
190
+ `status` to inspect captures without launching. An explicit action maps directly
191
+ to MCP arguments: `logs grep="Weather Sync" limit=100`
192
+ becomes `{"action":"logs","grep":"Weather Sync","limit":100}`. The skill keeps
193
+ quoted strings, numeric and boolean parameters, and JSON arrays/objects in their
194
+ tool-schema types. Add `captureId=...` to read or stop a specific capture.
195
+
196
+ The skill is a model instruction, not a direct RPC command: the model makes the
197
+ tool call and the client's permission rules still apply. It should execute the
198
+ requested action and report its result, rather than just explain how to do it.
199
+ Natural-language goals can also select the skill:
106
200
 
107
201
  ```text
108
202
  Build and launch on my device, then show me the console.
@@ -119,23 +213,171 @@ action=status captures, line counts, log paths
119
213
  action=stop close every running capture
120
214
  ```
121
215
 
216
+ If the entry point is missing, check the symlink and restart the client. If the
217
+ skill is found but the MCP tool is missing, check `claude mcp list` or Codex's
218
+ `/mcp`; installing the skill alone does not connect MCP. A `Called
219
+ xcodebug.xcodebug` line is a tool-call record, not a command to type.
220
+
221
+ Capture IDs, cursors and the last launch belong to one MCP server process.
222
+ Claude Code and Codex each start their own server, so a capture created in one
223
+ client cannot be read or stopped in the other. Stay in the same client session
224
+ for `launch` → `logs`/`wait` → `restart`/`stop`.
225
+
226
+ ### Claude Code live display
227
+
228
+ The live band needs three separate components: the `xcodebug` MCP server runs
229
+ the actions, the [shared skill](#install-the-manual-entry-point) provides
230
+ `/xcodebug`, and the `xcodebug-live` Mod draws above the prompt. Connecting MCP
231
+ or installing the skill alone does **not** load the Mod.
232
+
233
+ #### Prerequisites
234
+
235
+ Use Claude Code **2.1.323 or later** in an interactive terminal. Choose a checkout
236
+ or installed package that contains both the Mod and the updated MCP adapter:
237
+
238
+ ```bash
239
+ XCODEBUG_DIR=/path/to/xcodebug
240
+ # For an npm package containing this feature:
241
+ # XCODEBUG_DIR="$(npm root -g)/xcodebug"
242
+ claude --version
243
+ test -f "$XCODEBUG_DIR/claude/.claude-plugin/plugin.json"
244
+ test -f "$XCODEBUG_DIR/mcp/server.ts"
245
+ ```
246
+
247
+ If either file check fails, use a checkout containing the Mod and its updated
248
+ MCP adapter. Keep the MCP registration named `xcodebug` and point it at
249
+ `mcp/server.ts` from this same
250
+ root, using Bun. Follow [Set up](#set-up-once-per-machine) to register it, or
251
+ inspect an existing registration with `claude mcp get xcodebug`.
252
+
253
+ #### Install once for ordinary Claude sessions
254
+
255
+ Claude loads personal skills-directory plugins on startup. The display plugin
256
+ uses its own path, separate from the `xcodebug` skill. Run this in your shell
257
+ after setting `XCODEBUG_DIR` above:
258
+
259
+ ```bash
260
+ (
261
+ source="$XCODEBUG_DIR/claude"
262
+ dest="$HOME/.claude/skills/xcodebug-live"
263
+ test -f "$source/.claude-plugin/plugin.json" || {
264
+ printf 'Missing Mod manifest: %s\n' "$source" >&2
265
+ exit 1
266
+ }
267
+ if test -e "$dest" || test -L "$dest"; then
268
+ test -L "$dest" && test "$dest" -ef "$source" || {
269
+ printf 'Existing plugin path: %s\n' "$dest" >&2
270
+ exit 1
271
+ }
272
+ else
273
+ mkdir -p "$(dirname "$dest")" && ln -s "$source" "$dest" || exit 1
274
+ fi
275
+ )
276
+ ```
277
+
278
+ This skips a correct existing link and refuses to overwrite another file,
279
+ directory, wrong link or broken link. Keep the source directory in place.
280
+ Check discovery, then start a new session normally:
281
+
282
+ ```bash
283
+ claude plugin list # xcodebug-live@skills-dir, enabled
284
+ claude
285
+ ```
286
+
287
+ If this plugin was previously disabled, enable it with
288
+ `claude plugin enable xcodebug-live@skills-dir`. In the new session, `/plugin`
289
+ should list it and `/mcp` should show `xcodebug` connected. The official
290
+ [personal plugin loading rules](https://code.claude.com/docs/en/plugins/create#make-a-plugin-load-in-every-session)
291
+ describe this installation mechanism.
292
+
293
+ #### Use and expected display
294
+
295
+ From your app's working directory, use the installed skill in the same Claude
296
+ session:
297
+
298
+ ```text
299
+ /xcodebug launch scheme=MyApp
300
+ /xcodebug status
301
+ /xcodebug logs limit=100
302
+ /xcodebug stop
303
+ ```
304
+
305
+ During build, install, launch, and the rebuild within `restart`, the band shows
306
+ the current phase and elapsed time. An operation's phase takes priority over
307
+ an existing capture; capture continues in the background. When the operation
308
+ finishes, fails, or is cancelled, the band returns to the running capture's
309
+ line count and latest four log lines.
310
+
311
+ It refreshes every second, between turns too, from a build, install, launch,
312
+ restart, syslog or await call until no operation or capture is running, then
313
+ clears and stops reading. A session that starts or reloads the Mod reads once
314
+ and resumes a capture already running. Calls that only read or end something
315
+ (`doctor`, `devices`, `changes`, `status`, `logs`, `wait`, `stop`, `terminate`)
316
+ do not start it unless they carry a `command`, and an idle session makes no
317
+ reads. An empty band is normal in
318
+ that idle state. Build
319
+ percentages are estimates; installation shows elapsed time, not an installation
320
+ percentage. These lines are displayed to you without entering model context
321
+ or starting model turns; use `logs`/`wait` when Claude needs to analyze them.
322
+
323
+ The Mod calls the read-only `xcodebug_ui` tool on the existing connection once
324
+ when a display starts. That in-memory read bypasses the action queue, so a
325
+ build or `wait` cannot block it. A tool call runs the session's `PreToolUse`
326
+ and `PostToolUse` hooks, so the reads after it come from a file instead: the
327
+ server keeps the same snapshot in `~/.xcodebug/ui/<pid>.json`, names it in the
328
+ `xcodebug_ui` answer and removes it when it exits; one left by a server that
329
+ was killed is removed by the next server to start. Each call that starts a
330
+ display asks the server again, as does a file that is missing or stops
331
+ changing; with an older server that names no file the Mod calls the tool on
332
+ every read. After three failed reads in a row it
333
+ stops and clears the band until the next such call. Reading does not change the
334
+ active capture or log cursors, and request progress still stops when its
335
+ originating call returns. No second server is started. The Mod leaves an
336
+ existing statusLine alone;
337
+ Codex does not load this Claude-only Mod.
338
+
339
+ #### If the band is missing
340
+
341
+ 1. Run `claude plugin list` and check `/plugin` in the affected session.
342
+ `xcodebug-live` must be loaded; seeing the `/xcodebug` skill or a connected
343
+ MCP server does not establish that. Check `/plugin`'s Errors tab if loading
344
+ failed. Safe mode, disabled Mods/hooks or managed settings can prevent it.
345
+ 2. Check `/mcp` for the server named exactly `xcodebug`. An unavailable band or
346
+ unknown `xcodebug_ui` tool usually means a missing connection or an older
347
+ adapter. Inspect `claude mcp get xcodebug` to check the path.
348
+ 3. Use `/xcodebug status` to check that a capture is running in this session.
349
+ Captures in another client/session cannot populate this band's snapshot.
350
+ With no running capture or published phase, the band is intentionally empty.
351
+ 4. After updating the package, changing the server path or installing the Mod,
352
+ restart Claude so both components load together. `/reload-plugins` can reload
353
+ the Mod's files but does not restart the existing MCP server. `-p` sessions
354
+ do not draw the band.
355
+
356
+ To disable the persistent display, run
357
+ `claude plugin disable xcodebug-live@skills-dir` and restart Claude; enable it
358
+ again with the matching `enable` command. Capturing and the shared skill
359
+ remain available without the display.
360
+
122
361
  ### What differs from pi
123
362
 
124
363
  | | pi / omp / omo | Claude Code / Codex |
125
364
  |---|---|---|
126
365
  | how the tool is exposed | registered in-process | MCP server process |
127
- | status line, widget | yes | none |
128
- | `push` | mirrors new lines into the session | refused |
366
+ | manual entry point | native `/xcodebug` | shared skill: `/xcodebug` in Claude, `$xcodebug` in Codex |
367
+ | status line, widget | yes | Claude: optional live Mod above; otherwise request progress when rendered |
368
+ | `push` | mirrors new lines into the session | `off` only; `context` and `wake` refused |
129
369
  | capture state | in the session | in the server process |
130
370
  | lifetime | the session | the client process |
131
371
 
132
- - **`push` is refused on purpose.** MCP has no channel that injects content into a
133
- running turn, and neither client renders `notifications/message` - measured on
134
- both, where the model reported that nothing arrived on its own between two tool
135
- calls. Read with `action=logs` or `action=wait`; both are pull-based, and the
136
- cursor means you only pay for new lines.
137
- - **Captures end with the client.** The server is a child of Codex/Claude, so
138
- quitting the client stops the bridges. Relaunch next session.
372
+ - **The adapter refuses `push=context` and `push=wake`.** It does not implement
373
+ background log delivery into model context. Read with `action=logs` or
374
+ `action=wait`; these pull reads are separate from the Claude Mod's user-visible
375
+ display. Cursor reads exclude earlier indices, but a limited read can omit
376
+ lines; see [Reading logs from a cursor](#reading-logs-from-a-cursor).
377
+ - **Captures end with the client.** The server is a child of Codex/Claude. When
378
+ the client closes the connection, the server finishes the call in progress,
379
+ stops its captures and exits. On SIGINT or SIGTERM it stops at once, a build
380
+ still running included. Relaunch next session.
139
381
 
140
382
  Logs land in `~/.xcodebug/logs/xcodebug/`, or under `XCODEBUG_AGENT_DIR` when set.
141
383
  Every response also reports the exact path, so the model can read the file once a
@@ -236,13 +478,23 @@ rather than writing logs to a guessed path.
236
478
  `device` may be a name, UDID, ECID or CoreDevice uuid. With one physical device
237
479
  connected it can be omitted.
238
480
 
481
+ A file that is not valid JSON is an error, not an absent config: `doctor` reports
482
+ it, and every action that would read it refuses to run rather than use the
483
+ defaults the file was written to override. The actions that never read it -
484
+ `devices`, `logs`, `wait`, `status`, `stop` and `await` - still work.
485
+
239
486
  ## Change detection and pod install
240
487
 
241
488
  Every `build` and `launch` first inspects the working tree with
242
489
  `git status --porcelain -uall`:
243
490
 
244
- 1. **Any build-relevant change** (sources, resources, Podfile, podspec, project
245
- files) forces a rebuild + relaunch.
491
+ 1. **Any change git reports** forces a rebuild + relaunch, tracked or not and
492
+ whatever its type (`Podfile.rb`, an `.xcconfig`, a new image): a build that
493
+ is reused must not be older than what it was built from. The exceptions are
494
+ the types no build reads - notes, logs, crash reports and patches (`.md`,
495
+ `.log`, `.ips`, `.patch`, `.diff`) - so what a run leaves in the tree does
496
+ not trigger a build. A run that writes files of other types into the
497
+ repository, such as JSON results, does.
246
498
  2. **A new file inside a pod** forces `pod install --no-repo-update` first,
247
499
  because the generated Pods project enumerates pod sources and will not
248
500
  compile a file it has never seen. Pod membership comes from the repo's own
@@ -256,10 +508,24 @@ Every `build` and `launch` first inspects the working tree with
256
508
  `Podfile` (the workspace's parent). If there is none, the step is skipped and
257
509
  the reason is reported - it never searches elsewhere, because that could
258
510
  reinstall a different project's pods.
259
- 4. **No change** since the last successful build in this session reuses that
260
- build instead of rebuilding for minutes. Pass `force=true` to override.
511
+ 4. **No change** since this session last built the same scheme, configuration
512
+ and device reuses that build, for `launch` as well as `build`, instead of
513
+ rebuilding for minutes. The app is still installed and launched. Pass
514
+ `force=true` to rebuild. "No change" means all of:
515
+ - the same committed code and the same uncommitted changes. A commit, pull or
516
+ checkout rebuilds even though `git status` is clean again; `git add` alone
517
+ does not;
518
+ - the same files in every pod the workspace installs from a path outside the
519
+ repository (`:path` in `Podfile.lock`), which `git status` cannot see;
520
+ - the built `.app` is as that build left it. Xcode, or an `xcodebuild` in
521
+ another terminal, writes the same product path.
522
+
523
+ A build during which the tree changed is not reused, and its reply says so.
261
524
 
262
525
  Inspect the decision without building:
526
+ Use the same target and device options as the intended build. If the target
527
+ cannot be resolved, the report cannot identify a reusable build. If pod install
528
+ is needed, the preview assumes a rebuild until the updated tree is available.
263
529
 
264
530
  ```text
265
531
  xcodebug action=changes
@@ -269,6 +535,7 @@ xcodebug action=changes
269
535
  2 build-relevant change(s)
270
536
  M Packages/FeatureX/Classes/Weather/AddCityController.swift
271
537
  fingerprint: 963e92a4
538
+ last build for this target: (none)
272
539
  rebuild needed: yes
273
540
  pod install needed: no
274
541
  ```
@@ -283,8 +550,10 @@ run. Set `installPods=false` to skip it deliberately.
283
550
  ```
284
551
 
285
552
  Detects the workspace from the current directory (walking up, so a nested cwd
286
- works), rebuilds when the tree changed, installs, launches, and streams the
287
- console into this session. The phrase is a goal for the model, not a log filter.
553
+ works), rebuilds when the tree changed, installs, launches, and starts capturing.
554
+ Native pi/omp can push logs into the conversation; Claude Code and Codex use
555
+ `logs`/`wait` pull reads through MCP. The optional Claude Mod displays a console
556
+ tail to the user, not to the model. The phrase is a goal, not a log filter.
288
557
 
289
558
  - **CocoaPods vs plain project** is decided by `Podfile`/`Podfile.lock`: a
290
559
  CocoaPods project uses its `.xcworkspace`, a plain project its `.xcodeproj`.
@@ -414,7 +683,10 @@ nothing about any test framework. Two consequences worth knowing:
414
683
  What it reports: exit code, elapsed time, how many new lines the capture gained,
415
684
  the log path, and the `action=logs` call (with the right `since`) that returns
416
685
  the app side of that run. A non-zero exit is surfaced as an error, not as a
417
- successful "run finished".
686
+ successful "run finished". Two things about the capture are reported when they
687
+ happened, because either one changes what the log means: that it was no longer
688
+ capturing when the command finished (with the reason, or the last line logged),
689
+ and that a console reattach relaunched the app during the run.
418
690
 
419
691
  ### What the model does with it
420
692
 
@@ -467,39 +739,60 @@ Boundaries that keep it out of every other workflow:
467
739
  **Prerequisite when the command drives the UI:** the runner must not relaunch the
468
740
  app. Many UI-test fixtures terminate and relaunch the app before every test
469
741
  unless `autoAppLaunch: false` is set, which kills the very launch xcodebug is
470
- capturing. Set it in the config the run uses. A command that does not touch the
471
- app (a curl, a fixture import, a codegen step) has no such constraint.
742
+ capturing. Set it in the config the run uses. When it happens anyway, the capture
743
+ ends there and says the app was restarted outside it; it does not relaunch over
744
+ the runner's instance. A command that does not touch the app (a curl, a fixture
745
+ import, a codegen step) has no such constraint.
472
746
 
473
747
  ### Run semantics
474
748
 
475
749
  Verification is a loop: run, read the log, conclude, stop, edit the code, run
476
750
  again. Each `launch` or `syslog` retires the previous cycle's capture for that same
477
- app **before** the new bridge starts, so the two never push the same app's lines
478
- into one conversation; other apps keep streaming, so several apps can be
479
- debugged in one session.
751
+ app **before** the new bridge starts, avoiding duplicate capture streams for that
752
+ app; other apps' captures are preserved, so several apps can be debugged in one
753
+ session.
480
754
 
481
- - **Stop once the log has answered the question.** Keeping a capture alive after
482
- the conclusion only floods the session.
755
+ - **Stop once the log has answered the question.** Keeping a capture alive consumes
756
+ resources; with native push enabled, it also keeps sending log batches.
483
757
  - **Do not stop while the user has not acted yet.** Silence there means nothing
484
758
  has been tried, not that the run is over: say what to do on the phone and keep
485
759
  listening.
486
- - A capture ends on its own when the app process exits. A run whose app the user
487
- deliberately closed is not reconnected.
488
- - A dropped console bridge otherwise reconnects indefinitely. An inconclusive
489
- probe (USB unplugged, `devicectl` timeout) is **not** treated as "the app exited".
760
+ - A console capture ends when the app process is confirmed gone, and its syslog
761
+ companion is stopped too. It records why - `the app exited`, with the last
762
+ line logged, which is devicectl's own `App terminated due to signal 9.` when
763
+ the app was killed - in the log file, in `status`, and under later `logs`
764
+ reads. If the device wrote a crash report for the app, it is copied next to
765
+ the log and its path is reported the same way. A standalone `syslog` capture
766
+ is not bound to the app's lifetime and keeps reconnecting; stop it explicitly
767
+ when finished.
768
+ - A dropped console bridge whose app is still running is reattached, retrying
769
+ for as long as it takes. devicectl attaches a console only by launching, so
770
+ with the default `terminateExisting` **a reattach restarts the app** and its
771
+ state is gone: the log says so and `status` counts the relaunches. An
772
+ inconclusive probe (USB unplugged, `devicectl` timeout) is retried without
773
+ relaunching. If the current PID is known but capture ownership cannot be
774
+ verified, a reattach that would terminate the running app is skipped.
775
+ - If the instance running is not the one this capture launched - another
776
+ session, a test runner or the user relaunched the app - the capture ends and
777
+ leaves that instance alone. Reattaching would terminate it. The session that
778
+ did the relaunching is told as well: its `launch` reply notes that the app was
779
+ already running and not started by it.
490
780
  - `idevicesyslog` can go silent with its process still alive; a 30s watchdog kills
491
781
  it and the exit hook reattaches. Reattachment has exactly one owner, so the
492
782
  watchdog and the exit hook can never both assume the other is handling it.
493
- - After 60s with no new lines the run says so once and keeps capturing.
494
- - A footer line and a widget above the editor show the live state, e.g.
495
- `📖 xcodebug · capturing · 7895 lines · 42s · /xcodebug stop to end`, plus the
496
- last few log lines and how many channels are streaming.
497
- - Pushed log batches are **hidden from the transcript** (`display: false`) but
498
- still delivered to the model, which is the only consumer that needs every
499
- line. The screen keeps one status line instead of a wall of log frames.
500
- - `/xcodebug stop` (or `action=stop`) closes **every running capture** - the
501
- console bridge and its syslog companion, plus any other app still streaming.
502
- Pass `captureId=` to close one. `keepApp=false` also terminates the app.
783
+ - In native pi/omp push modes, after 60s with no new lines the run says so once
784
+ and keeps capturing. MCP users use `logs`/`wait` to inspect quiet captures.
785
+ - In pi/omp, a footer line and a widget above the editor show the live state,
786
+ e.g. `📖 xcodebug · capturing · 7895 lines · 42s · /xcodebug stop to end`, plus
787
+ recent log lines and the number of streaming channels. Claude Code can instead
788
+ load the [live display Mod](#claude-code-live-display).
789
+ - Native pushed log batches are **hidden from the transcript** (`display: false`)
790
+ but delivered to the model, subject to the per-batch limit. MCP does not push
791
+ batches; the Claude Mod's display does not add logs to model context.
792
+ - `/xcodebug stop` (or `action=stop`) without `captureId` closes **every running
793
+ capture**. An ID scopes the stop to that target; a console primary's syslog
794
+ companion is stopped too. Other apps' captures are unaffected by a targeted
795
+ stop. `keepApp=false` also terminates the app.
503
796
 
504
797
  ## Usage
505
798
 
@@ -524,7 +817,9 @@ xcodebug action=syslog processName=MyApp
524
817
  # incremental reads (cursor-based)
525
818
  xcodebug action=logs limit=200
526
819
  xcodebug action=logs grep=MySDK
820
+ xcodebug action=logs grep=MySDK times=true
527
821
  xcodebug action=wait match="DataPacket" timeoutSeconds=30
822
+ xcodebug action=wait match="sync (done|failed)" regex=true timeoutSeconds=30
528
823
 
529
824
  xcodebug action=status
530
825
  xcodebug action=stop keepApp=true
@@ -568,6 +863,19 @@ is written to disk and delivered to live subscribers but not retained for
568
863
  and captures reconnecting after a bridge failure are not evicted. Older capture
569
864
  IDs leave `logs`/`status`, while their retained disk segments remain available.
570
865
 
866
+ A busy app fills that buffer in seconds, so a filtered read does not stop at it.
867
+ `logs grep=...` and `wait` also search for lines missing from memory, including
868
+ oversized lines between retained entries. They wait for writes through the
869
+ scan's cursor before reading disk; cancellation interrupts that work. The reply
870
+ reports how many lines were searched on disk and how many are unavailable.
871
+ An unfiltered `logs` returns the newest lines as before and
872
+ names the log file for the rest.
873
+
874
+ `regex=true` makes `grep` and `match` regular expressions, so one `wait` can
875
+ cover both outcomes of a step: `match="sync (done|failed)"`. `times=true`
876
+ prefixes each returned line with the host time it arrived, for lining the log
877
+ up with a test runner's own output.
878
+
571
879
  ### `syslog`: attach without relaunching
572
880
 
573
881
  `launch` restarts the app because `devicectl --console` has to start it. When the
@@ -585,7 +893,8 @@ only comes from the console bridge, per the table at the top.
585
893
 
586
894
  ### Pushing logs into the conversation
587
895
 
588
- `push` controls whether new lines are mirrored into the session:
896
+ In native pi/omp, `push` controls whether new lines are mirrored into the session.
897
+ The MCP adapter accepts only `off`; Claude Code and Codex use `logs`/`wait`.
589
898
 
590
899
  - `context` (default) — new lines are queued for the next turn (does not start one).
591
900
  - `off` — pull with `logs`/`wait` only.
@@ -614,8 +923,16 @@ drain-timeout error in capture status, and completes shutdown; pending logs may
614
923
  be truncated.
615
924
 
616
925
  The bundle id separates apps, and the timestamp includes milliseconds to
617
- separate runs. Segment limits apply per capture: old runs are not automatically
618
- deleted from disk when their capture IDs leave the in-memory history.
926
+ separate runs. Segment limits apply per capture. What xcodebug itself says while
927
+ a bridge is down - why the capture ended, each reattach - is appended to the same
928
+ file, so a log that stops also says why. A crash report copied from the device
929
+ lands beside the logs as `crash-<unique-id>-<name>.ips`. When the app PID is
930
+ known, a report without that PID is not retained.
931
+
932
+ Logs are kept for 30 days after their last write. The first `build`, `launch` or
933
+ `syslog` of a session deletes older `build-`, `console-`, `syslog-` and
934
+ `pod-install-` logs and `crash-*.ips` reports from this directory, and nothing
935
+ else in it.
619
936
 
620
937
  A successful build clears `<agentDir>/logs/xcodebug/archive/` first, so snapshots
621
938
  from a previous binary cannot be mistaken for the run that is starting.
package/archive.ts CHANGED
@@ -61,6 +61,35 @@ export async function clearArchives(workDir: string): Promise<{ removed: number;
61
61
  return { removed, freedBytes };
62
62
  }
63
63
 
64
+ /** The files this extension writes: build, capture and pod install logs, and pulled crash reports. */
65
+ const OWN_LOG = /^(?:build|console|syslog|pod-install|crash)-.+\.(?:log(?:\.\d+)?|ips)$/;
66
+
67
+ /**
68
+ * Delete this extension's logs that nothing has written to for `maxAgeMs`.
69
+ *
70
+ * Nothing else ever removes them, and they add up to hundreds of megabytes in
71
+ * a few weeks. Age since the last write is the whole test: a capture still
72
+ * running keeps its log fresh, and a file xcodebug did not name is left alone.
73
+ */
74
+ export async function pruneLogs(logDir: string, maxAgeMs: number): Promise<void> {
75
+ let entries: string[];
76
+ try {
77
+ entries = await readdir(logDir);
78
+ } catch {
79
+ return;
80
+ }
81
+ const cutoff = Date.now() - maxAgeMs;
82
+ for (const name of entries) {
83
+ if (!OWN_LOG.test(name)) continue;
84
+ const path = join(logDir, name);
85
+ try {
86
+ if ((await stat(path)).mtimeMs < cutoff) await rm(path, { force: true });
87
+ } catch {
88
+ // A log that cannot be removed is not worth failing a run over.
89
+ }
90
+ }
91
+ }
92
+
64
93
  /** Recursive size of a file or directory, in bytes. */
65
94
  async function sizeOf(path: string): Promise<number> {
66
95
  const info = await stat(path);