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 +65 -16
- package/README.md +364 -47
- package/archive.ts +29 -0
- package/capture.ts +212 -16
- package/changes.ts +113 -15
- package/claude/.claude-plugin/plugin.json +6 -0
- package/claude/hooks/hooks.json +3 -0
- package/claude/hooks/register.js +113 -0
- package/claude/tests/live.test.ts +321 -0
- package/devices.ts +74 -3
- package/index.ts +518 -113
- package/mcp/server.ts +141 -17
- package/package.json +6 -1
- package/skills/xcodebug/SKILL.md +89 -0
- package/xcode.ts +84 -4
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
|
-
**
|
|
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
|
|
44
|
-
|
|
45
|
-
`keepApp=true` is the
|
|
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
|
|
199
|
-
directory), so each brand writes under its own prefix (`.pi` / `.omp` /
|
|
200
|
-
`.senpi`)
|
|
201
|
-
|
|
202
|
-
milliseconds
|
|
203
|
-
|
|
204
|
-
lines
|
|
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
|
|
209
|
-
|
|
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
|
|
213
|
-
|
|
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.
|