xcodebug 1.1.2 → 1.2.1

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/GUIDE.md CHANGED
@@ -4,6 +4,14 @@ Task-oriented walkthrough. [README.md](README.md) is the authoritative reference
4
4
  for every parameter, the change-detection rules and the capture internals; this
5
5
  file only shows the flows you will actually type.
6
6
 
7
+ The `/xcodebug` examples use the native pi/omp command or the installed Claude
8
+ Code skill. In Codex, replace `/xcodebug` with `$xcodebug`. Claude Code and Codex
9
+ need both the MCP connection and the shared skill; follow
10
+ [README.md § Install the manual entry point](README.md#install-the-manual-entry-point).
11
+ Enter these commands in the client's chat input. A bare `/xcodebug` (`$xcodebug`
12
+ in Codex) builds as needed, installs, launches and starts capturing with defaults.
13
+ Use `/xcodebug status` (`$xcodebug status` in Codex) to inspect current captures.
14
+
7
15
  Debug a real iOS device: build, install, launch, and read the app's console
8
16
  (stdout/stderr + os_log) inside the agent session. No jailbreak, no LLDB attach,
9
17
  no paid account.
@@ -20,9 +28,11 @@ model must answer — not a log filter.
20
28
 
21
29
  ## Two surfaces
22
30
 
23
- **Slash command** (for humans)
31
+ **User entry point** (native command in pi/omp; installed skill in Claude Code/Codex)
24
32
 
25
33
  ```text
34
+ /xcodebug
35
+ /xcodebug status
26
36
  /xcodebug launch scheme=MyApp
27
37
  /xcodebug logs grep=MySDK
28
38
  /xcodebug stop
@@ -40,20 +50,45 @@ The 14 actions and their parameters are tabulated in
40
50
  [README.md § Usage](README.md#usage). Two of them differ from what the name
41
51
  suggests, so they are repeated here:
42
52
 
43
- - `stop` closes **every running capture** (the console bridge and its syslog
44
- companion, plus any other app still streaming). Pass `captureId=` to close one.
45
- `keepApp=true` is the default and leaves the app running.
53
+ - `stop` without `captureId` closes **every running capture**. With an ID, it
54
+ stops that target; stopping a console primary also stops its syslog companion.
55
+ Other apps' captures are unaffected by a targeted stop. `keepApp=true` is the
56
+ default and leaves the app running.
46
57
  - `restart` replays the last launch of this session — device, scheme, goal and
47
58
  the `command=` it carried — and forces a rebuild.
48
59
 
49
60
  ## How logs reach the conversation
50
61
 
51
- `push` decides whether new lines are mirrored into the session: `context`
62
+ In pi/omp, `push` decides whether new lines are mirrored into the session: `context`
52
63
  (default, queued for the next turn), `off` (pull with `logs`/`wait`), `wake`
53
64
  (starts a turn). A device console is a firehose; each push carries at most 80
54
65
  lines and reports how many older lines it dropped. Narrow it with `match`, e.g.
55
66
  `action=launch match=MySDK push=wake`.
56
67
 
68
+ Claude Code and Codex use pull reads through MCP: `logs` for an incremental read,
69
+ or `wait` for an expected line. `push=context` and `push=wake` are refused there;
70
+ installing the skill does not add background log delivery.
71
+
72
+ For a live display in Claude Code, install the **separate** `xcodebug-live` Mod
73
+ using [the one-time installation recipe](README.md#install-once-for-ordinary-claude-sessions).
74
+ It then loads with ordinary `claude` startup. The MCP connection and shared
75
+ skill alone do not load it. Confirm `xcodebug-live@skills-dir` in
76
+ `claude plugin list`, then restart Claude and check `/plugin` and `/mcp`.
77
+
78
+ Keep the `xcodebug` MCP server pointed at the same updated checkout or installed
79
+ package as the Mod.
80
+
81
+ The band shows build/install/launch phases, including the rebuild within
82
+ `restart`, even when a capture is already running. Capture continues in the
83
+ background; after the operation finishes, fails, or is cancelled, the band
84
+ returns to the running capture's line count and latest four console lines.
85
+ It refreshes once a second, between turns too, while an operation or capture is
86
+ running, then clears and stops reading; an idle session makes no reads. It does
87
+ not send those lines to the model; use `logs`/`wait`
88
+ for analysis.
89
+ See [Claude Code live display](README.md#claude-code-live-display) for version
90
+ requirements, upgrade/disable steps and missing-display troubleshooting.
91
+
57
92
  ## Running a command alongside a capture
58
93
 
59
94
  ### What it is for
@@ -195,19 +230,26 @@ xcodebug action=await command="cd /repo && npm run test:weather"
195
230
  Every capture is mirrored to
196
231
  `<agentDir>/logs/xcodebug/<mode>-<bundleId>-<YYYY-MM-DD_HH-mm-ss-SSS>.log`.
197
232
 
198
- `agentDir` comes from the host (`ctx.agentDir`, else the parent of the session
199
- directory), so each brand writes under its own prefix (`.pi` / `.omp` / `.omo` /
200
- `.senpi`); the extension hardcodes none of them. The bundle id is in the name
201
- because several apps are debugged in one session, and the timestamp carries
202
- milliseconds because relaunching the same app within a second would otherwise
203
- interleave two runs in one file. The in-memory ring buffer keeps the last 20k
204
- lines; the file on disk is complete.
233
+ In pi/omp, `agentDir` comes from the host (`ctx.agentDir`, else the parent of the
234
+ session directory), so each brand writes under its own prefix (`.pi` / `.omp` /
235
+ `.omo` / `.senpi`). MCP defaults to `~/.xcodebug`, overridden by
236
+ `XCODEBUG_AGENT_DIR`. The bundle id separates apps, and the timestamp includes
237
+ milliseconds to separate runs.
238
+
239
+ Memory retains at most 20k lines and 4 MiB of text. Disk logging rotates through
240
+ the base path plus `.1` and `.2`, retaining three segments targeting 50 MiB each;
241
+ older segments are overwritten. Complete lines are kept, so a single oversized
242
+ line can exceed a segment's target size. Shutdown allows two seconds to drain
243
+ pending writes; a drain timeout can truncate logs. Neither memory nor disk is
244
+ a lossless archive of the whole run. See [retention](README.md#reading-logs-from-a-cursor)
245
+ and [disk files](README.md#files) for details and the `logFiles` path list.
205
246
 
206
247
  ## Three rules of use
207
248
 
208
- 1. **Stop once the log has answered the question.** A capture left running only
209
- keeps flooding the session.
249
+ 1. **Stop once the log has answered the question.** A capture left running keeps
250
+ consuming capture resources; native push modes also keep sending log batches.
210
251
  2. **Do not stop while the user has not acted yet.** Silence there means "not
211
252
  tried yet", not "finished" — say what to tap and keep listening.
212
- 3. **A capture ends on its own when the app process exits.** Do not reconnect a
213
- run whose app the user deliberately closed.
253
+ 3. **A console capture ends when the app process is confirmed gone.** Its syslog
254
+ companion is stopped too. A standalone `syslog` capture is not bound to the
255
+ app's lifetime and keeps reconnecting; stop it explicitly when finished.
package/README.md CHANGED
@@ -27,8 +27,8 @@ it as a package or drop the directory in place.
27
27
  pi install npm:xcodebug
28
28
  pi install npm:xcodebug -l # project scope: .pi/settings.json
29
29
 
30
- # pin a version, or install from a checkout
31
- pi install npm:xcodebug@1.0.0
30
+ # explicitly select the latest release, or install from a checkout
31
+ pi install npm:xcodebug@latest
32
32
  pi install /path/to/xcodebug
33
33
  ```
34
34
 
@@ -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
- npm i -g xcodebug # >= 1.1.0, the first release that ships mcp/
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,51 @@ codex mcp list # xcodebug bun …
92
92
  claude mcp list # xcodebug: … ✔ Connected
93
93
  ```
94
94
 
95
+ ### Install the manual entry point
96
+
97
+ Connecting MCP makes the tool available to the model; it does not register a
98
+ `/xcodebug` command in either client. The shared
99
+ [xcodebug skill](skills/xcodebug/SKILL.md) adds an explicit entry point:
100
+ `/xcodebug` in Claude Code, `$xcodebug` in Codex, or Codex's `/skills` picker.
101
+
102
+ Both clients can read the same skill directory through user-level symlinks:
103
+
104
+ ```bash
105
+ XCODEBUG_DIR="/absolute/path/to/xcodebug" # a checkout containing the skill
106
+ # For an npm package that includes the skill, use this instead:
107
+ # XCODEBUG_DIR="$(npm root -g)/xcodebug"
108
+
109
+ (
110
+ source="$XCODEBUG_DIR/skills/xcodebug"
111
+ test -f "$source/SKILL.md" || { printf 'Skill not found: %s\n' "$source/SKILL.md" >&2; exit 1; }
112
+ for dest in "$HOME/.agents/skills/xcodebug" "$HOME/.claude/skills/xcodebug"; do
113
+ if test -e "$dest" || test -L "$dest"; then
114
+ if ! test -L "$dest" || ! test "$dest" -ef "$source"; then
115
+ printf 'Existing skill path: %s; inspect it before installing.\n' "$dest" >&2
116
+ exit 1
117
+ fi
118
+ fi
119
+ done
120
+ mkdir -p "$HOME/.agents/skills" "$HOME/.claude/skills" || exit 1
121
+ for dest in "$HOME/.agents/skills/xcodebug" "$HOME/.claude/skills/xcodebug"; do
122
+ test -L "$dest" || ln -s "$source" "$dest" || exit 1
123
+ done
124
+ )
125
+ ```
126
+
127
+ If the installed package does not contain `skills/xcodebug/SKILL.md`, use a
128
+ checkout that contains it. The commands check both target paths before installing,
129
+ skip symlinks already pointing to this skill, and stop on other existing files,
130
+ directories or symlinks, including broken links.
131
+ Keep the checkout or npm package at the linked path. Updating that source updates
132
+ the shared skill for both clients.
133
+
134
+ Start a new Claude Code or Codex session after installing. The skill uses the
135
+ MCP connection already configured above; it does not start a separate server or
136
+ replace the native pi command. Both manual and model-selected invocation remain
137
+ available. See the clients' [Claude Code skill documentation](https://code.claude.com/docs/en/skills)
138
+ and [Codex skill documentation](https://learn.chatgpt.com/docs/build-skills).
139
+
95
140
  ### Use
96
141
 
97
142
  Start the client **in the project directory**. The server inherits its cwd, and
@@ -102,7 +147,32 @@ cd ~/myapp # holds the .xcworkspace or .xcodeproj
102
147
  codex # or: claude
103
148
  ```
104
149
 
105
- Then ask for the outcome; the model calls the tool:
150
+ Enter these in the client's chat input, not in your shell, after installing the skill:
151
+
152
+ | Operation | Claude Code | Codex |
153
+ |---|---|---|
154
+ | Build, install and launch with defaults | `/xcodebug` | `$xcodebug` |
155
+ | Show capture status | `/xcodebug status` | `$xcodebug status` |
156
+ | Check the toolchain | `/xcodebug doctor` | `$xcodebug doctor` |
157
+ | List devices | `/xcodebug devices` | `$xcodebug devices` |
158
+ | Build, install and launch | `/xcodebug launch scheme=MyApp` | `$xcodebug launch scheme=MyApp` |
159
+ | Read filtered logs | `/xcodebug logs grep="Weather Sync" limit=100` | `$xcodebug logs grep="Weather Sync" limit=100` |
160
+ | Wait for an event | `/xcodebug wait match="sync complete" timeoutSeconds=30` | `$xcodebug wait match="sync complete" timeoutSeconds=30` |
161
+ | Rebuild and rerun the last launch | `/xcodebug restart` | `$xcodebug restart` |
162
+ | Stop capture, leave the app running | `/xcodebug stop` | `$xcodebug stop` |
163
+
164
+ A bare skill invocation calls `{"action":"launch"}`: it builds as needed, installs,
165
+ launches and starts capturing using the server's project/device defaults. Use
166
+ `status` to inspect captures without launching. An explicit action maps directly
167
+ to MCP arguments: `logs grep="Weather Sync" limit=100`
168
+ becomes `{"action":"logs","grep":"Weather Sync","limit":100}`. The skill keeps
169
+ quoted strings, numeric and boolean parameters, and JSON arrays/objects in their
170
+ tool-schema types. Add `captureId=...` to read or stop a specific capture.
171
+
172
+ The skill is a model instruction, not a direct RPC command: the model makes the
173
+ tool call and the client's permission rules still apply. It should execute the
174
+ requested action and report its result, rather than just explain how to do it.
175
+ Natural-language goals can also select the skill:
106
176
 
107
177
  ```text
108
178
  Build and launch on my device, then show me the console.
@@ -119,21 +189,167 @@ action=status captures, line counts, log paths
119
189
  action=stop close every running capture
120
190
  ```
121
191
 
192
+ If the entry point is missing, check the symlink and restart the client. If the
193
+ skill is found but the MCP tool is missing, check `claude mcp list` or Codex's
194
+ `/mcp`; installing the skill alone does not connect MCP. A `Called
195
+ xcodebug.xcodebug` line is a tool-call record, not a command to type.
196
+
197
+ Capture IDs, cursors and the last launch belong to one MCP server process.
198
+ Claude Code and Codex each start their own server, so a capture created in one
199
+ client cannot be read or stopped in the other. Stay in the same client session
200
+ for `launch` → `logs`/`wait` → `restart`/`stop`.
201
+
202
+ ### Claude Code live display
203
+
204
+ The live band needs three separate components: the `xcodebug` MCP server runs
205
+ the actions, the [shared skill](#install-the-manual-entry-point) provides
206
+ `/xcodebug`, and the `xcodebug-live` Mod draws above the prompt. Connecting MCP
207
+ or installing the skill alone does **not** load the Mod.
208
+
209
+ #### Prerequisites
210
+
211
+ Use Claude Code **2.1.323 or later** in an interactive terminal. Choose a checkout
212
+ or installed package that contains both the Mod and the updated MCP adapter:
213
+
214
+ ```bash
215
+ XCODEBUG_DIR=/path/to/xcodebug
216
+ # For an npm package containing this feature:
217
+ # XCODEBUG_DIR="$(npm root -g)/xcodebug"
218
+ claude --version
219
+ test -f "$XCODEBUG_DIR/claude/.claude-plugin/plugin.json"
220
+ test -f "$XCODEBUG_DIR/mcp/server.ts"
221
+ ```
222
+
223
+ If either file check fails, use a checkout containing the Mod and its updated
224
+ MCP adapter. Keep the MCP registration named `xcodebug` and point it at
225
+ `mcp/server.ts` from this same
226
+ root, using Bun. Follow [Set up](#set-up-once-per-machine) to register it, or
227
+ inspect an existing registration with `claude mcp get xcodebug`.
228
+
229
+ #### Install once for ordinary Claude sessions
230
+
231
+ Claude loads personal skills-directory plugins on startup. The display plugin
232
+ uses its own path, separate from the `xcodebug` skill. Run this in your shell
233
+ after setting `XCODEBUG_DIR` above:
234
+
235
+ ```bash
236
+ (
237
+ source="$XCODEBUG_DIR/claude"
238
+ dest="$HOME/.claude/skills/xcodebug-live"
239
+ test -f "$source/.claude-plugin/plugin.json" || {
240
+ printf 'Missing Mod manifest: %s\n' "$source" >&2
241
+ exit 1
242
+ }
243
+ if test -e "$dest" || test -L "$dest"; then
244
+ test -L "$dest" && test "$dest" -ef "$source" || {
245
+ printf 'Existing plugin path: %s\n' "$dest" >&2
246
+ exit 1
247
+ }
248
+ else
249
+ mkdir -p "$(dirname "$dest")" && ln -s "$source" "$dest" || exit 1
250
+ fi
251
+ )
252
+ ```
253
+
254
+ This skips a correct existing link and refuses to overwrite another file,
255
+ directory, wrong link or broken link. Keep the source directory in place.
256
+ Check discovery, then start a new session normally:
257
+
258
+ ```bash
259
+ claude plugin list # xcodebug-live@skills-dir, enabled
260
+ claude
261
+ ```
262
+
263
+ If this plugin was previously disabled, enable it with
264
+ `claude plugin enable xcodebug-live@skills-dir`. In the new session, `/plugin`
265
+ should list it and `/mcp` should show `xcodebug` connected. The official
266
+ [personal plugin loading rules](https://code.claude.com/docs/en/plugins/create#make-a-plugin-load-in-every-session)
267
+ describe this installation mechanism.
268
+
269
+ #### Use and expected display
270
+
271
+ From your app's working directory, use the installed skill in the same Claude
272
+ session:
273
+
274
+ ```text
275
+ /xcodebug launch scheme=MyApp
276
+ /xcodebug status
277
+ /xcodebug logs limit=100
278
+ /xcodebug stop
279
+ ```
280
+
281
+ During build, install, launch, and the rebuild within `restart`, the band shows
282
+ the current phase and elapsed time. An operation's phase takes priority over
283
+ an existing capture; capture continues in the background. When the operation
284
+ finishes, fails, or is cancelled, the band returns to the running capture's
285
+ line count and latest four log lines.
286
+
287
+ It refreshes every second, between turns too, from a build, install, launch,
288
+ restart, syslog or await call until no operation or capture is running, then
289
+ clears and stops reading. A session that starts or reloads the Mod reads once
290
+ and resumes a capture already running. Calls that only read or end something
291
+ (`doctor`, `devices`, `changes`, `status`, `logs`, `wait`, `stop`, `terminate`)
292
+ do not start it unless they carry a `command`, and an idle session makes no
293
+ reads. An empty band is normal in
294
+ that idle state. Build
295
+ percentages are estimates; installation shows elapsed time, not an installation
296
+ percentage. These lines are displayed to you without entering model context
297
+ or starting model turns; use `logs`/`wait` when Claude needs to analyze them.
298
+
299
+ The Mod calls the read-only `xcodebug_ui` tool on the existing connection once
300
+ when a display starts. That in-memory read bypasses the action queue, so a
301
+ build or `wait` cannot block it. A tool call runs the session's `PreToolUse`
302
+ and `PostToolUse` hooks, so the reads after it come from a file instead: the
303
+ server keeps the same snapshot in `~/.xcodebug/ui/<pid>.json`, names it in the
304
+ `xcodebug_ui` answer and removes it when it exits; one left by a server that
305
+ was killed is removed by the next server to start. Each call that starts a
306
+ display asks the server again, as does a file that is missing or stops
307
+ changing; with an older server that names no file the Mod calls the tool on
308
+ every read. After three failed reads in a row it
309
+ stops and clears the band until the next such call. Reading does not change the
310
+ active capture or log cursors, and request progress still stops when its
311
+ originating call returns. No second server is started. The Mod leaves an
312
+ existing statusLine alone;
313
+ Codex does not load this Claude-only Mod.
314
+
315
+ #### If the band is missing
316
+
317
+ 1. Run `claude plugin list` and check `/plugin` in the affected session.
318
+ `xcodebug-live` must be loaded; seeing the `/xcodebug` skill or a connected
319
+ MCP server does not establish that. Check `/plugin`'s Errors tab if loading
320
+ failed. Safe mode, disabled Mods/hooks or managed settings can prevent it.
321
+ 2. Check `/mcp` for the server named exactly `xcodebug`. An unavailable band or
322
+ unknown `xcodebug_ui` tool usually means a missing connection or an older
323
+ adapter. Inspect `claude mcp get xcodebug` to check the path.
324
+ 3. Use `/xcodebug status` to check that a capture is running in this session.
325
+ Captures in another client/session cannot populate this band's snapshot.
326
+ With no running capture or published phase, the band is intentionally empty.
327
+ 4. After updating the package, changing the server path or installing the Mod,
328
+ restart Claude so both components load together. `/reload-plugins` can reload
329
+ the Mod's files but does not restart the existing MCP server. `-p` sessions
330
+ do not draw the band.
331
+
332
+ To disable the persistent display, run
333
+ `claude plugin disable xcodebug-live@skills-dir` and restart Claude; enable it
334
+ again with the matching `enable` command. Capturing and the shared skill
335
+ remain available without the display.
336
+
122
337
  ### What differs from pi
123
338
 
124
339
  | | pi / omp / omo | Claude Code / Codex |
125
340
  |---|---|---|
126
341
  | 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 |
342
+ | manual entry point | native `/xcodebug` | shared skill: `/xcodebug` in Claude, `$xcodebug` in Codex |
343
+ | status line, widget | yes | Claude: optional live Mod above; otherwise request progress when rendered |
344
+ | `push` | mirrors new lines into the session | `off` only; `context` and `wake` refused |
129
345
  | capture state | in the session | in the server process |
130
346
  | lifetime | the session | the client process |
131
347
 
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.
348
+ - **The adapter refuses `push=context` and `push=wake`.** It does not implement
349
+ background log delivery into model context. Read with `action=logs` or
350
+ `action=wait`; these pull reads are separate from the Claude Mod's user-visible
351
+ display. Cursor reads exclude earlier indices, but a limited read can omit
352
+ lines; see [Reading logs from a cursor](#reading-logs-from-a-cursor).
137
353
  - **Captures end with the client.** The server is a child of Codex/Claude, so
138
354
  quitting the client stops the bridges. Relaunch next session.
139
355
 
@@ -141,6 +357,40 @@ Logs land in `~/.xcodebug/logs/xcodebug/`, or under `XCODEBUG_AGENT_DIR` when se
141
357
  Every response also reports the exact path, so the model can read the file once a
142
358
  run is over.
143
359
 
360
+ ## Xcode's own MCP
361
+
362
+ Xcode 27.1 ships an MCP server of its own (`xcrun mcpbridge`) with 54 tools:
363
+ workspace and project editing, build/run/stop, tests, previews, the debugger,
364
+ build settings, String Catalogs, crash and performance reports, and device
365
+ interaction (tap, swipe, screenshot, UI hierarchy). One of those tools does the
366
+ same job as this extension, so pick deliberately rather than registering both by
367
+ habit:
368
+
369
+ ```bash
370
+ claude mcp add --transport stdio xcode -- xcrun mcpbridge
371
+ codex mcp add xcode -- xcrun mcpbridge
372
+ ```
373
+
374
+ Xcode asks for permission the first time an agent opens a project;
375
+ `xcrun mcp-server status` reports what has been granted.
376
+
377
+ `GetConsoleOutput` is the one that overlaps, and it is not a substitute:
378
+
379
+ | | Xcode `GetConsoleOutput` | xcodebug |
380
+ |---|---|---|
381
+ | source | the launch session `RunProject` created | any capture this extension started |
382
+ | positioning | `tailLimit` only - the last N lines | a cursor per capture; `since` resumes exactly |
383
+ | already-running app | only apps Xcode launched | `syslog` attaches without a relaunch |
384
+
385
+ So: **Xcode for anything that drives the IDE or the screen, xcodebug for the log
386
+ stream.** `GetConsoleOutput` answers "what did the last 500 lines say"; this
387
+ extension answers "what arrived since cursor 1694" - including from an app that
388
+ nobody launched from Xcode.
389
+
390
+ `RunProject` and `DeviceInteractionInstallAndRun` also build, install and launch.
391
+ They target whatever run destination Xcode has selected; `launch` takes a udid
392
+ directly.
393
+
144
394
  ## Requirements
145
395
 
146
396
  | Need | Why |
@@ -245,12 +495,14 @@ run. Set `installPods=false` to skip it deliberately.
245
495
  ## One-shot: `/xcodebug <what to verify>`
246
496
 
247
497
  ```text
248
- /xcodebug 验证天气添加城市
498
+ /xcodebug verify adding a city in Weather
249
499
  ```
250
500
 
251
501
  Detects the workspace from the current directory (walking up, so a nested cwd
252
- works), rebuilds when the tree changed, installs, launches, and streams the
253
- console into this session. The phrase is a goal for the model, not a log filter.
502
+ works), rebuilds when the tree changed, installs, launches, and starts capturing.
503
+ Native pi/omp can push logs into the conversation; Claude Code and Codex use
504
+ `logs`/`wait` pull reads through MCP. The optional Claude Mod displays a console
505
+ tail to the user, not to the model. The phrase is a goal, not a log filter.
254
506
 
255
507
  - **CocoaPods vs plain project** is decided by `Podfile`/`Podfile.lock`: a
256
508
  CocoaPods project uses its `.xcworkspace`, a plain project its `.xcodeproj`.
@@ -312,7 +564,7 @@ what the app does while **a person** drives the phone: slow to reproduce and
312
564
  never quite identical twice.
313
565
 
314
566
  ```text
315
- /xcodebug 分析天气添加城市 command="cd /repo && npm run test:weather"
567
+ /xcodebug analyze adding a city in Weather command="cd /repo && npm run test:weather"
316
568
  ```
317
569
 
318
570
  | Without `command=` | With `command=` |
@@ -335,7 +587,7 @@ That single line does the whole linkage run:
335
587
  2. run the shell line to completion (blocking);
336
588
  3. stop the capture it was watching;
337
589
  4. report the exit code, the app-side cursor, and the log path - with the
338
- phrase `分析天气添加城市` attached as the goal the analysis must answer.
590
+ phrase `analyze adding a city in Weather` attached as the goal the analysis must answer.
339
591
 
340
592
  `command=` is a **second phase appended to the main action**, never an action of
341
593
  its own. That ordering is the point: a command is only meaningful when the app is
@@ -356,7 +608,7 @@ xcodebug action=await command="cd /repo && npm run test:weather"
356
608
  /xcodebug await command="cd /repo && npm run test:weather" timeoutSeconds=900
357
609
  ```
358
610
 
359
- A bare `/xcodebug` (or `/xcodebug 分析xxx`) has **no deadline**: it launches,
611
+ A bare `/xcodebug` (or `/xcodebug analyze <scenario>`) has **no deadline**: it launches,
360
612
  streams, and waits for you. Nothing stops it except `stop`, a new launch of the
361
613
  same app, or the app exiting.
362
614
 
@@ -440,32 +692,36 @@ app (a curl, a fixture import, a codegen step) has no such constraint.
440
692
 
441
693
  Verification is a loop: run, read the log, conclude, stop, edit the code, run
442
694
  again. Each `launch` or `syslog` retires the previous cycle's capture for that same
443
- app **before** the new bridge starts, so the two never push the same app's lines
444
- into one conversation; other apps keep streaming, so several apps can be
445
- debugged in one session.
695
+ app **before** the new bridge starts, avoiding duplicate capture streams for that
696
+ app; other apps' captures are preserved, so several apps can be debugged in one
697
+ session.
446
698
 
447
- - **Stop once the log has answered the question.** Keeping a capture alive after
448
- the conclusion only floods the session.
699
+ - **Stop once the log has answered the question.** Keeping a capture alive consumes
700
+ resources; with native push enabled, it also keeps sending log batches.
449
701
  - **Do not stop while the user has not acted yet.** Silence there means nothing
450
702
  has been tried, not that the run is over: say what to do on the phone and keep
451
703
  listening.
452
- - A capture ends on its own when the app process exits. A run whose app the user
453
- deliberately closed is not reconnected.
704
+ - A console capture ends when the app process is confirmed gone, and its syslog
705
+ companion is stopped too. A standalone `syslog` capture is not bound to the
706
+ app's lifetime and keeps reconnecting; stop it explicitly when finished.
454
707
  - A dropped console bridge otherwise reconnects indefinitely. An inconclusive
455
708
  probe (USB unplugged, `devicectl` timeout) is **not** treated as "the app exited".
456
709
  - `idevicesyslog` can go silent with its process still alive; a 30s watchdog kills
457
710
  it and the exit hook reattaches. Reattachment has exactly one owner, so the
458
711
  watchdog and the exit hook can never both assume the other is handling it.
459
- - After 60s with no new lines the run says so once and keeps capturing.
460
- - A footer line and a widget above the editor show the live state, e.g.
461
- `📖 xcodebug · capturing · 7895 lines · 42s · /xcodebug stop to end`, plus the
462
- last few log lines and how many channels are streaming.
463
- - Pushed log batches are **hidden from the transcript** (`display: false`) but
464
- still delivered to the model, which is the only consumer that needs every
465
- line. The screen keeps one status line instead of a wall of log frames.
466
- - `/xcodebug stop` (or `action=stop`) closes **every running capture** - the
467
- console bridge and its syslog companion, plus any other app still streaming.
468
- Pass `captureId=` to close one. `keepApp=false` also terminates the app.
712
+ - In native pi/omp push modes, after 60s with no new lines the run says so once
713
+ and keeps capturing. MCP users use `logs`/`wait` to inspect quiet captures.
714
+ - In pi/omp, a footer line and a widget above the editor show the live state,
715
+ e.g. `📖 xcodebug · capturing · 7895 lines · 42s · /xcodebug stop to end`, plus
716
+ recent log lines and the number of streaming channels. Claude Code can instead
717
+ load the [live display Mod](#claude-code-live-display).
718
+ - Native pushed log batches are **hidden from the transcript** (`display: false`)
719
+ but delivered to the model, subject to the per-batch limit. MCP does not push
720
+ batches; the Claude Mod's display does not add logs to model context.
721
+ - `/xcodebug stop` (or `action=stop`) without `captureId` closes **every running
722
+ capture**. An ID scopes the stop to that target; a console primary's syslog
723
+ companion is stopped too. Other apps' captures are unaffected by a targeted
724
+ stop. `keepApp=false` also terminates the app.
469
725
 
470
726
  ## Usage
471
727
 
@@ -509,9 +765,50 @@ xcodebug action=await command="cd /repo && npm run test:weather"
509
765
  /xcodebug await command="cd /repo && npm run test:weather"
510
766
  ```
511
767
 
768
+ ### Reading logs from a cursor
769
+
770
+ Every `logs` read returns a cursor: the latest absolute line index in that
771
+ capture. Pass it as `since` to exclude lines at or before that index. Reads
772
+ return the newest matching lines up to `limit`; if the response says older
773
+ lines were omitted, advancing to its cursor skips those lines too.
774
+
775
+ ```text
776
+ xcodebug action=logs since=0 limit=2
777
+ 2 line(s) (1692 older omitted) · cursor 1694
778
+
779
+ xcodebug action=logs since=1694
780
+ (no new lines since 1694; capture cursor is 1694)
781
+
782
+ xcodebug action=logs since=1694 limit=3
783
+ 3 line(s) (6135 older omitted) · cursor 7832
784
+ ```
785
+
786
+ Each capture retains at most 20k lines and 4 MiB of text in memory (counted as
787
+ UTF-16 bytes, excluding object overhead). A line larger than that text budget
788
+ is written to disk and delivered to live subscribers but not retained for
789
+ `logs`. The session keeps the most recent 10 ended captures; active captures
790
+ and captures reconnecting after a bridge failure are not evicted. Older capture
791
+ IDs leave `logs`/`status`, while their retained disk segments remain available.
792
+
793
+ ### `syslog`: attach without relaunching
794
+
795
+ `launch` restarts the app because `devicectl --console` has to start it. When the
796
+ app is already running and the state you want to observe would not survive a
797
+ restart, attach instead:
798
+
799
+ ```text
800
+ xcodebug action=syslog processName=MyApp
801
+ ```
802
+
803
+ This runs `idevicesyslog -p <ProcessName>` and leaves the app running. It needs
804
+ `idevicesyslog` from libimobiledevice (`action=doctor` reports whether it is
805
+ present), and it reads the device log for that process - `print` output still
806
+ only comes from the console bridge, per the table at the top.
807
+
512
808
  ### Pushing logs into the conversation
513
809
 
514
- `push` controls whether new lines are mirrored into the session:
810
+ In native pi/omp, `push` controls whether new lines are mirrored into the session.
811
+ The MCP adapter accepts only `off`; Claude Code and Codex use `logs`/`wait`.
515
812
 
516
813
  - `context` (default) — new lines are queued for the next turn (does not start one).
517
814
  - `off` — pull with `logs`/`wait` only.
@@ -523,14 +820,25 @@ useful, e.g. `xcodebug action=launch match=MySDK push=wake`.
523
820
 
524
821
  ### Files
525
822
 
526
- Every capture also writes a full log to
527
- `<agentDir>/logs/xcodebug/<mode>-<bundleId>-<YYYY-MM-DD_HH-mm-ss-SSS>.log`, so
528
- nothing is lost when the in-memory ring buffer (20k lines) rolls over.
529
-
530
- The app's bundle id is part of the name because several apps are debugged in
531
- one session; the timestamp carries milliseconds so a relaunch of the same app
532
- cannot reuse the previous run's file (files are opened in append mode, so a
533
- collision would interleave two runs with no way to tell them apart).
823
+ Every capture writes timestamped logs under
824
+ `<agentDir>/logs/xcodebug/<mode>-<bundleId>-<YYYY-MM-DD_HH-mm-ss-SSS>.log`.
825
+ It rotates through that base path plus `.1` and `.2`, replacing the oldest
826
+ segment after three segments. Each segment targets 50 MiB and keeps complete
827
+ lines (a single larger line may exceed that size). Logging continues after
828
+ rotation; it no longer stops at the first 50 MiB. Capture status details list
829
+ successfully opened paths in chronological order as `logFiles`; `logFile` stays
830
+ the stable base path. Reconnecting appends to the current segment.
831
+
832
+ Disk writes apply backpressure to both capture pipes, so a slow disk pauses
833
+ ingestion instead of accumulating an unlimited write queue. After the bridge
834
+ exits, capture shutdown allows up to two seconds for the pipes and pending file
835
+ writes to drain. If they remain blocked, it destroys the streams, reports a
836
+ drain-timeout error in capture status, and completes shutdown; pending logs may
837
+ be truncated.
838
+
839
+ The bundle id separates apps, and the timestamp includes milliseconds to
840
+ separate runs. Segment limits apply per capture: old runs are not automatically
841
+ deleted from disk when their capture IDs leave the in-memory history.
534
842
 
535
843
  A successful build clears `<agentDir>/logs/xcodebug/archive/` first, so snapshots
536
844
  from a previous binary cannot be mistaken for the run that is starting.