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/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
@@ -180,6 +215,7 @@ xcodebug action=restart # after editing: rebuild + relaunch +
180
215
  xcodebug action=logs limit=200
181
216
  xcodebug action=logs grep=MySDK
182
217
  xcodebug action=wait match="DataPacket" timeoutSeconds=30
218
+ xcodebug action=wait match="sync (done|failed)" regex=true # either outcome, one wait
183
219
 
184
220
  # wrap up
185
221
  xcodebug action=status
@@ -195,19 +231,32 @@ xcodebug action=await command="cd /repo && npm run test:weather"
195
231
  Every capture is mirrored to
196
232
  `<agentDir>/logs/xcodebug/<mode>-<bundleId>-<YYYY-MM-DD_HH-mm-ss-SSS>.log`.
197
233
 
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.
234
+ In pi/omp, `agentDir` comes from the host (`ctx.agentDir`, else the parent of the
235
+ session directory), so each brand writes under its own prefix (`.pi` / `.omp` /
236
+ `.omo` / `.senpi`). MCP defaults to `~/.xcodebug`, overridden by
237
+ `XCODEBUG_AGENT_DIR`. The bundle id separates apps, and the timestamp includes
238
+ milliseconds to separate runs.
239
+
240
+ Memory retains at most 20k lines and 4 MiB of text. Disk logging rotates through
241
+ the base path plus `.1` and `.2`, retaining three segments targeting 50 MiB each;
242
+ older segments are overwritten. Complete lines are kept, so a single oversized
243
+ line can exceed a segment's target size. Shutdown allows two seconds to drain
244
+ pending writes; a drain timeout can truncate logs. Neither memory nor disk is
245
+ a lossless archive of the whole run. See [retention](README.md#reading-logs-from-a-cursor)
246
+ and [disk files](README.md#files) for details and the `logFiles` path list.
247
+
248
+ A filtered read (`logs grep=`, `wait`) looks in those files for the lines memory
249
+ has dropped and says in its reply that it did. Logs are deleted 30 days after
250
+ their last write.
205
251
 
206
252
  ## Three rules of use
207
253
 
208
- 1. **Stop once the log has answered the question.** A capture left running only
209
- keeps flooding the session.
254
+ 1. **Stop once the log has answered the question.** A capture left running keeps
255
+ consuming capture resources; native push modes also keep sending log batches.
210
256
  2. **Do not stop while the user has not acted yet.** Silence there means "not
211
257
  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.
258
+ 3. **A console capture ends when the app process is confirmed gone.** Its syslog
259
+ companion is stopped too, and `status` says why it ended and where the crash
260
+ report is, if the device wrote one. A standalone `syslog` capture is not
261
+ bound to the app's lifetime and keeps reconnecting; stop it explicitly when
262
+ finished.