xcodebug
Build, install and launch an iOS app on a physical device and read its console inside the agent session (pi / omp extension)
Package details
Install xcodebug from npm and Pi will load the resources declared by the package manifest.
$ pi install npm:xcodebug- Package
xcodebug- Version
1.2.4- Published
- Nov 20, 2026
- Downloads
- 1,432/mo · 554/wk
- Author
- codebaby555
- License
- MIT
- Types
- extension
- Size
- 342.7 KB
- Dependencies
- 0 dependencies · 2 peers
Pi manifest JSON
{
"skills": [],
"extensions": [
"./index.ts"
]
}Security note
Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.
README
xcodebug
Drive a physical iOS device from the agent session: build/install/launch with Xcode, then read the app's console output (stdout/stderr + os_log) inside the session.
No jailbreak, no LLDB attach, no paid account. It uses the tooling Xcode itself ships with:
| What Xcode's console shows | How xcodebug gets it |
|---|---|
print / NSLog / os_log |
xcrun devicectl device process launch --console |
| os_log in the console | OS_ACTIVITY_DT_MODE=YES on that launch |
| an app you don't want to restart | idevicesyslog -p <ProcessName> (optional) |
| build + install | xcodebuild + xcrun devicectl device install app |
devicectl --console needs the app to be launched by it, so launch restarts
the app. syslog attaches to an already-running process instead.
Install
The extension is a directory with index.ts plus a pi manifest; either install
it as a package or drop the directory in place.
# from npm (writes to ~/.pi/agent/settings.json)
pi install npm:xcodebug
pi install npm:xcodebug -l # project scope: .pi/settings.json
# explicitly select the latest release, or install from a checkout
pi install npm:xcodebug@latest
pi install /path/to/xcodebug
Upgrading from xcodebug-extension: the package was renamed, so both names
register the same xcodebug tool and the loader refuses to start the second one
(Tool "xcodebug" conflicts with ...). Remove the old package first:
pi remove npm:xcodebug-extension
pi install npm:xcodebug
Or copy the directory into the global extensions dir, which the engine discovers on startup:
<agentDir>/extensions/xcodebug/index.ts
<agentDir> is whatever the host resolves (~/.omo/agent under OmO,
~/.omp/agent under omp, ~/.senpi/agent under senpi, ~/.pi/agent under
upstream pi): xcodebug is a generic pi extension and names no brand.
Restart the session afterwards. Neither pi nor omp reloads an already-loaded
extension: pi has no reload command at all, and omp's /reload-plugins only
clears plugin discovery, not the imported module graph. Editing index.ts while
a session is running therefore has no effect on that session.
Claude Code and Codex (MCP)
The shared actions reach both clients through MCP. mcp/server.ts loads
index.ts with a stub host and serves the tool it registers, so it exposes the
same actions and arguments as the pi extension rather than a parallel
implementation. Claude Code can also load the optional native display below.
Set up (once per machine)
npm i -g xcodebug@latest # installs the latest published release
codex mcp add xcodebug -- bun "$(npm root -g)/xcodebug/mcp/server.ts"
claude mcp add --scope user xcodebug -- bun "$(npm root -g)/xcodebug/mcp/server.ts"
Working from a checkout instead? Point both at mcp/server.ts in the repo:
codex mcp add xcodebug -- bun /path/to/xcodebug/mcp/server.ts
claude mcp add --scope user xcodebug -- bun /path/to/xcodebug/mcp/server.ts
Bun is required (bun.sh). The sources are TypeScript, and Node
refuses to strip types for files under node_modules
(ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING) - which is exactly where npm
installs the package, so node cannot start an installed copy. Bun loads the
same file from either location, so one command covers both.
Check that the client picked it up:
codex mcp list # xcodebug bun …
claude mcp list # xcodebug: … ✔ Connected
After installing the package, run the setup command once to register the MCP server when missing and add the timeout without replacing an existing xcodebug command or argument list:
xcodebug-setup-codex
From a checkout, use node bin/xcodebug-setup-codex.mjs. The command uses the
Codex app-server config API available in current Codex releases. It registers
xcodebug with Bun if it is missing, writes tool_timeout_sec = 4200 only when
that field is absent, and preserves an existing custom timeout. On Codex CLI
0.171.0 or later it also enables features.tui_extensions_statusline = true
and selects the xcodebug statusline provider when the user selection is missing
or default. Existing custom providers are preserved with a warning. Older or
unrecognized CLI versions receive a warning instead. It checks the
running service with codex app-server daemon version and warns if its
appServerVersion is too old or cannot be verified. Saving configuration does
not upgrade the service; setup never updates or restarts a daemon automatically.
The command warns about project-level xcodebug overrides and existing server
paths pointing elsewhere, but preserves the registration and project files.
Setup saves these fields together with one version-checked config/batchWrite
request.
If another process edits the user configuration during setup, Codex rejects
stale writes; rerun setup after that edit rather than overwrite a new selection.
It does not run automatically during npm install because package installation
should not silently modify a user's Codex configuration. See the live display
section below for provider selection. For manual setup on supported CLI and
app-server versions, merge these fields into existing tables rather than add
duplicate table headers:
[features]
tui_extensions_statusline = true
[tui]
status_line_provider = { server = "xcodebug", tool = "xcodebug_ui" }
[mcp_servers.xcodebug]
tool_timeout_sec = 4200
The timeout leaves room for the default 15-minute pod install, 15-minute build and 30-minute command budgets, plus device operations. Increase it if you pass larger timeouts. This does not change xcodebug's stage deadlines or Codex's separate status-line resource read deadline.
Claude Code needs no setting for this. Its default limit on a tool call is about 28 hours. It also ends a call to a stdio server that has sent neither a reply nor a progress notification for 30 minutes; this server sends progress once a second to a client that asks for it.
Cancelling an MCP request aborts that request. On SIGINT, SIGTERM or detected stdout loss, the server stops accepting work, cancels admitted requests and then cleans up captures. Closing only stdin lets admitted requests finish and sends their replies; a silent lost reader cannot be distinguished from this until stdout closes or a write fails.
To run npm test from a checkout, use Node.js 22.18 or later and put Bun on PATH
for the stdio integration tests.
Codex live display (experimental)
Both Codex CLI and the connected app server must be 0.171.0 or later. Setup
enables the feature persistently and selects xcodebug for a missing or default
provider. Alternatively start Codex with codex --enable tui_extensions_statusline.
If setup reports an older running
service, finish active Codex tasks and captures before running
codex app-server daemon update --from-cli --yes, then
codex app-server daemon restart. Opening a new TUI alone does not upgrade it.
Start a new Codex session after setup or after updating the service or MCP
server. If setup preserved another custom provider, open /statusline, enter
Choose a status line provider, then select xcodebug_ui
(xcodebug / xcodebug_ui). Codex 0.171.0 discovers providers from
the user configuration. A project-level override of the same MCP server name
can make the provider unavailable; remove the override or use a distinct name.
Codex 0.171.0 has a five-second provider discovery deadline. If the global MCP inventory stalls, the picker can show only the default provider even though xcodebug itself is available. Specify the provider directly for one session:
codex -c 'tui.status_line_provider={server="xcodebug",tool="xcodebug_ui"}'
Setup persists the provider selection for missing/default user settings. To replace another custom provider explicitly, use the manual settings above. Provider selection is supported configuration, not an MCP server setting. See Codex's provider configuration and discovery deadline.
The footer shows the current operation or capture and its latest log line. It
refreshes even between tool calls and clears when no operation or capture is
active. This is a display preview, not a log stream into the conversation; use
action=logs or action=wait for log evidence.
Long status text is shortened in the footer without changing the command or
its output.
Install the manual entry point
Connecting MCP makes the tool available to the model; it does not register a
/xcodebug command in either client. The shared
xcodebug skill adds an explicit entry point:
/xcodebug in Claude Code, $xcodebug in Codex, or Codex's /skills picker.
Native pi/omp needs only the extension, not this skill or an MCP connection.
Both hosts register extensions: ["./index.ts"]; pi.skills: [] disables pi's
package skill loading. The shared skill lives under mcp/skills/, outside the
root skills/ directory that omp scans independently of manifest fields.
Native /xcodebug runs
the registered extension handler directly; it does not ask the model to select
a skill. A normal model tool call uses the registered native xcodebug tool.
If pi/omp also discovers the shared user-level skill through .agents/skills
or .claude/skills, its instructions select that native tool before MCP.
This shared-skill selection is model-driven, not a substitute for the native
command's deterministic dispatch. The extension must be installed, enabled and
loaded in the session; explicitly disabling it is not overridden.
Both clients can read the same skill directory through user-level symlinks:
XCODEBUG_DIR="/absolute/path/to/xcodebug" # a checkout containing the skill
# For an npm package that includes the skill, use this instead:
# XCODEBUG_DIR="$(npm root -g)/xcodebug"
(
source="$XCODEBUG_DIR/mcp/skills/xcodebug"
legacy="$XCODEBUG_DIR/skills/xcodebug"
test -f "$source/SKILL.md" || { printf 'Skill not found: %s\n' "$source/SKILL.md" >&2; exit 1; }
for dest in "$HOME/.agents/skills/xcodebug" "$HOME/.claude/skills/xcodebug"; do
if test -e "$dest" || test -L "$dest"; then
if ! test -L "$dest" || { ! test "$dest" -ef "$source" && ! test "$(readlink "$dest")" = "$legacy"; }; then
printf 'Existing skill path: %s; inspect it before installing.\n' "$dest" >&2
exit 1
fi
fi
done
mkdir -p "$HOME/.agents/skills" "$HOME/.claude/skills" || exit 1
for dest in "$HOME/.agents/skills/xcodebug" "$HOME/.claude/skills/xcodebug"; do
if test -L "$dest" && test "$(readlink "$dest")" = "$legacy"; then
rm "$dest" || exit 1
fi
test -L "$dest" || ln -s "$source" "$dest" || exit 1
done
)
If the installed package does not contain mcp/skills/xcodebug/SKILL.md, use a
checkout that contains it. The commands check both target paths before installing,
skip symlinks already pointing to this skill, and migrate links to this checkout's
old skills/xcodebug source. They stop on other existing files, directories or
symlinks, including unrelated broken links. After updating an older checkout or
upgrading an npm package that used the old root skills/ path, rerun these
commands to relink both clients; npm upgrade alone does not migrate those links.
Keep the checkout or npm package at the linked path. Once relinked, updates to
the maintained source update the shared skill for both clients.
Start a new Claude Code or Codex session after installing. The skill uses the MCP connection already configured above in those clients; it does not start a separate server. Native pi/omp uses its extension command and native tool instead. Both manual and model-selected invocation remain available. See the clients' Claude Code skill documentation and Codex skill documentation.
Use
Start the client in the project directory. The server inherits its cwd, and that directory is the project root every action resolves against.
cd ~/myapp # holds the .xcworkspace or .xcodeproj
codex # or: claude
Enter these in the client's chat input, not in your shell, after installing the skill:
| Operation | Claude Code | Codex |
|---|---|---|
| Build, install and launch with defaults | /xcodebug |
$xcodebug |
| Show capture status | /xcodebug status |
$xcodebug status |
| Check the toolchain | /xcodebug doctor |
$xcodebug doctor |
| List devices | /xcodebug devices |
$xcodebug devices |
| Build, install and launch | /xcodebug launch scheme=MyApp |
$xcodebug launch scheme=MyApp |
| Read filtered logs | /xcodebug logs grep="Weather Sync" limit=100 |
$xcodebug logs grep="Weather Sync" limit=100 |
| Wait for an event | /xcodebug wait match="sync complete" timeoutSeconds=30 |
$xcodebug wait match="sync complete" timeoutSeconds=30 |
| Rebuild and rerun the last launch | /xcodebug restart |
$xcodebug restart |
| Stop capture, leave the app running | /xcodebug stop |
$xcodebug stop |
A bare skill invocation calls {"action":"launch"}: it builds as needed, installs,
launches and starts capturing using the server's project/device defaults. Use
status to inspect captures without launching. An explicit action maps directly
to MCP arguments: logs grep="Weather Sync" limit=100
becomes {"action":"logs","grep":"Weather Sync","limit":100}. The skill keeps
quoted strings, numeric and boolean parameters, and JSON arrays/objects in their
tool-schema types. Add captureId=... to read or stop a specific capture.
The skill is a model instruction, not a direct RPC command: the model makes the tool call and the client's permission rules still apply. It should execute the requested action and report its result, rather than just explain how to do it. Natural-language goals can also select the skill:
Build and launch on my device, then show me the console.
The actions that matter in this mode:
action=launch device=<udid> build + install + launch; the capture starts
action=logs since=0 incremental read - the cursor is per capture
action=logs grep=Weather narrow to one subsystem
action=wait match="..." block until a line appears
action=status captures, line counts, log paths
action=stop close every running capture
If the entry point is missing, check the symlink and restart the client. If the
skill is found but the MCP tool is missing, check claude mcp list or Codex's
/mcp; installing the skill alone does not connect MCP. A Called xcodebug.xcodebug line is a tool-call record, not a command to type.
Capture IDs, cursors and the last launch belong to one MCP server process.
Claude Code and Codex each start their own server, so a capture created in one
client cannot be read or stopped in the other. Stay in the same client session
for launch → logs/wait → restart/stop.
Claude Code live display
The live band needs three separate components: the xcodebug MCP server runs
the actions, the shared skill provides
/xcodebug, and the xcodebug-live Mod draws above the prompt. Connecting MCP
or installing the skill alone does not load the Mod.
Prerequisites
Use Claude Code 2.1.323 or later in an interactive terminal. Choose a checkout or installed package that contains both the Mod and the updated MCP adapter:
XCODEBUG_DIR=/path/to/xcodebug
# For an npm package containing this feature:
# XCODEBUG_DIR="$(npm root -g)/xcodebug"
claude --version
test -f "$XCODEBUG_DIR/claude/.claude-plugin/plugin.json"
test -f "$XCODEBUG_DIR/mcp/server.ts"
If either file check fails, use a checkout containing the Mod and its updated
MCP adapter. Keep the MCP registration named xcodebug and point it at
mcp/server.ts from this same
root, using Bun. Follow Set up to register it, or
inspect an existing registration with claude mcp get xcodebug.
Install once for ordinary Claude sessions
Claude loads personal skills-directory plugins on startup. The display plugin
uses its own path, separate from the xcodebug skill. Run this in your shell
after setting XCODEBUG_DIR above:
(
source="$XCODEBUG_DIR/claude"
dest="$HOME/.claude/skills/xcodebug-live"
test -f "$source/.claude-plugin/plugin.json" || {
printf 'Missing Mod manifest: %s\n' "$source" >&2
exit 1
}
if test -e "$dest" || test -L "$dest"; then
test -L "$dest" && test "$dest" -ef "$source" || {
printf 'Existing plugin path: %s\n' "$dest" >&2
exit 1
}
else
mkdir -p "$(dirname "$dest")" && ln -s "$source" "$dest" || exit 1
fi
)
This skips a correct existing link and refuses to overwrite another file, directory, wrong link or broken link. Keep the source directory in place. Check discovery, then start a new session normally:
claude plugin list # xcodebug-live@skills-dir, enabled
claude
If this plugin was previously disabled, enable it with
claude plugin enable xcodebug-live@skills-dir. In the new session, /plugin
should list it and /mcp should show xcodebug connected. The official
personal plugin loading rules
describe this installation mechanism.
Use and expected display
From your app's working directory, use the installed skill in the same Claude session:
/xcodebug launch scheme=MyApp
/xcodebug status
/xcodebug logs limit=100
/xcodebug stop
During build, install, launch, and the rebuild within restart, the band shows
the current phase and elapsed time. An operation's phase takes priority over
an existing capture; capture continues in the background. When the operation
finishes, fails, or is cancelled, the band returns to the running capture's
line count and latest four log lines.
It refreshes every second, between turns too, from a build, install, launch,
restart, syslog or await call until no operation or capture is running, then
clears and stops reading. A session that starts or reloads the Mod reads once
and resumes a capture already running. Calls that only read or end something
(doctor, devices, changes, status, logs, wait, stop, terminate)
do not start it unless they carry a command, and an idle session makes no
reads. An empty band is normal in
that idle state. Build
percentages are estimates; installation shows elapsed time, not an installation
percentage. These lines are displayed to you without entering model context
or starting model turns; use logs/wait when Claude needs to analyze them.
The Mod calls the read-only xcodebug_ui tool on the existing connection once
when a display starts. That in-memory read bypasses the action queue, so a
build or wait cannot block it. A tool call runs the session's PreToolUse
and PostToolUse hooks, so the reads after it come from a file instead: the
server keeps the same snapshot in ~/.xcodebug/ui/<pid>.json, names it in the
xcodebug_ui answer and removes it when it exits; one left by a server that
was killed is removed by the next server to start. Each call that starts a
display asks the server again, as does a file that is missing or stops
changing; with an older server that names no file the Mod calls the tool on
every read. After three failed reads in a row it
stops and clears the band until the next such call. Reading does not change the
active capture or log cursors, and request progress still stops when its
originating call returns. No second server is started. The Mod leaves an
existing statusLine alone;
Codex does not load this Claude-only Mod.
If the band is missing
- Run
claude plugin listand check/pluginin the affected session.xcodebug-livemust be loaded; seeing the/xcodebugskill or a connected MCP server does not establish that. Check/plugin's Errors tab if loading failed. Safe mode, disabled Mods/hooks or managed settings can prevent it. - Check
/mcpfor the server named exactlyxcodebug. An unavailable band or unknownxcodebug_uitool usually means a missing connection or an older adapter. Inspectclaude mcp get xcodebugto check the path. - Use
/xcodebug statusto check that a capture is running in this session. Captures in another client/session cannot populate this band's snapshot. With no running capture or published phase, the band is intentionally empty. - After updating the package, changing the server path or installing the Mod,
restart Claude so both components load together.
/reload-pluginscan reload the Mod's files but does not restart the existing MCP server.-psessions do not draw the band.
To disable the persistent display, run
claude plugin disable xcodebug-live@skills-dir and restart Claude; enable it
again with the matching enable command. Capturing and the shared skill
remain available without the display.
What differs from pi
| pi / omp / omo | Claude Code / Codex | |
|---|---|---|
| how the tool is exposed | registered in-process | MCP server process |
| manual entry point | native /xcodebug |
shared skill: /xcodebug in Claude, $xcodebug in Codex |
| status line, widget | yes | Claude live Mod or Codex status line, both opt-in |
push |
mirrors new lines into the session | off only; context and wake refused |
| capture state | in the session | in the server process |
| lifetime | the session | the client process |
- The adapter refuses
push=contextandpush=wake. It does not implement background log delivery into model context. Read withaction=logsoraction=wait; these pull reads are separate from both clients' live displays. Cursor reads exclude earlier indices, but a limited read can omit lines; see Reading logs from a cursor. - Captures end with the client. The server is a child of Codex/Claude. When the client closes the connection, the server finishes the call in progress, stops its captures and exits. On SIGINT or SIGTERM it stops at once, a build still running included. Relaunch next session.
Logs land in ~/.xcodebug/logs/xcodebug/, or under XCODEBUG_AGENT_DIR when set.
Every response also reports the exact path, so the model can read the file once a
run is over.
Xcode's own MCP
Xcode 27.1 ships an MCP server of its own (xcrun mcpbridge) with 54 tools:
workspace and project editing, build/run/stop, tests, previews, the debugger,
build settings, String Catalogs, crash and performance reports, and device
interaction (tap, swipe, screenshot, UI hierarchy). One of those tools does the
same job as this extension, so pick deliberately rather than registering both by
habit:
claude mcp add --transport stdio xcode -- xcrun mcpbridge
codex mcp add xcode -- xcrun mcpbridge
Xcode asks for permission the first time an agent opens a project;
xcrun mcp-server status reports what has been granted.
GetConsoleOutput is the one that overlaps, and it is not a substitute:
Xcode GetConsoleOutput |
xcodebug | |
|---|---|---|
| source | the launch session RunProject created |
any capture this extension started |
| positioning | tailLimit only - the last N lines |
a cursor per capture; since resumes exactly |
| already-running app | only apps Xcode launched | syslog attaches without a relaunch |
So: Xcode for anything that drives the IDE or the screen, xcodebug for the log
stream. GetConsoleOutput answers "what did the last 500 lines say"; this
extension answers "what arrived since cursor 1694" - including from an app that
nobody launched from Xcode.
RunProject and DeviceInteractionInstallAndRun also build, install and launch.
They target whatever run destination Xcode has selected; launch takes a udid
directly.
Requirements
| Need | Why |
|---|---|
| macOS + Xcode (command-line tools) | xcodebuild, xcrun devicectl |
idevicesyslog from libimobiledevice |
optional; only syslog and the dual-channel safety net |
| git | change detection; without a repo every run rebuilds |
| CocoaPods | optional; only projects with a Podfile |
| Bun | only for the MCP clients (Claude Code, Codex); pi runs the extension itself |
xcodebug action=doctor reports the Xcode toolchain, the capture tools, the
active config and the log directory.
Imports
The only engine import is a type import, erased at compile time:
import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
That is the official specifier; loaders also alias @code-yeongyu/senpi and the
@mariozechner/* names to the same module. typebox is the other dependency,
for tool parameter schemas. Everything else is node: built-ins.
The extension is written against the published types, and that is enforced:
it typechecks against @earendil-works/pi-coding-agent@1.4.0, whose
ExtensionContext carries only cwd and sessionManager and whose
ExtensionAPI has no cwd. Hosts that add more - ctx.agentDir, pi.cwd,
argumentHint on a command - are supported without depending on them:
if ("agentDir" in ctx) { /* host supplies it */ }
So the same file runs unchanged on every distribution, and a host that omits
those fields loses nothing: the project root falls back to ctx.cwd, and the
agent directory to the session directory's parent (every brand stores sessions at
<agentDir>/sessions/<encoded-cwd>), then to a *_CODING_AGENT_DIR environment
override. If none of those exist the extension fails naming what was missing
rather than writing logs to a guessed path.
Configure (optional)
.xcodebug.json in the project root:
{
"workspace": "MyApp.xcworkspace",
"scheme": "MyApp",
"configuration": "Debug",
"bundleId": "com.example.myapp",
"device": "My-iPhone",
"args": [],
"environment": {}
}
device may be a name, UDID, ECID or CoreDevice uuid. With one physical device
connected it can be omitted.
A file that is not valid JSON is an error, not an absent config: doctor reports
it, and every action that would read it refuses to run rather than use the
defaults the file was written to override. The actions that never read it -
devices, logs, wait, status, stop and await - still work.
Change detection and pod install
Every build and launch first inspects the working tree with
git status --porcelain -uall:
- Any change git reports forces a rebuild + relaunch, tracked or not and
whatever its type (
Podfile.rb, an.xcconfig, a new image): a build that is reused must not be older than what it was built from. The exceptions are the types no build reads - notes, logs, crash reports and patches (.md,.log,.ips,.patch,.diff) - so what a run leaves in the tree does not trigger a build. A run that writes files of other types into the repository, such as JSON results, does. - A new file inside a pod forces
pod install --no-repo-updatefirst, because the generated Pods project enumerates pod sources and will not compile a file it has never seen. Pod membership comes from the repo's own podspecsource_filesglobs, soPackages/FeatureX/Classes/**maps toFeatureX, etc. Podfile.lockout of step withPods/Manifest.lockalso forcespod install. That mismatch fails every target's "[CP] Check Pods Manifest.lock" phase with an error the user cannot act on from a build log.
pod install only ever runs in the directory that holds the container's own
Podfile (the workspace's parent). If there is none, the step is skipped and
the reason is reported - it never searches elsewhere, because that could
reinstall a different project's pods.
4. No change since this session last built the same scheme, configuration
and device reuses that build, for launch as well as build, instead of
rebuilding for minutes. The app is still installed and launched. Pass
force=true to rebuild. "No change" means all of:
- the same committed code and the same uncommitted changes. A commit, pull or
checkout rebuilds even though
git statusis clean again;git addalone does not; - the same files in every pod the workspace installs from a path outside the
repository (
:pathinPodfile.lock), whichgit statuscannot see; - the built
.appis as that build left it. Xcode, or anxcodebuildin another terminal, writes the same product path.
A build during which the tree changed is not reused, and its reply says so.
Inspect the decision without building: Use the same target and device options as the intended build. If the target cannot be resolved, the report cannot identify a reusable build. If pod install is needed, the preview assumes a rebuild until the updated tree is available.
xcodebug action=changes
2 build-relevant change(s)
M Packages/FeatureX/Classes/Weather/AddCityController.swift
fingerprint: 963e92a4
last build for this target: (none)
rebuild needed: yes
pod install needed: no
pod install runs once per change set (tracked by fingerprint), not on every
run. Set installPods=false to skip it deliberately.
One-shot: /xcodebug <what to verify>
/xcodebug verify adding a city in Weather
Detects the workspace from the current directory (walking up, so a nested cwd
works), rebuilds when the tree changed, installs, launches, and starts capturing.
Native pi/omp can push logs into the conversation; Claude Code and Codex use
logs/wait pull reads through MCP. Both clients offer an optional live preview
for the user. The phrase is a goal, not a log filter.
- CocoaPods vs plain project is decided by
Podfile/Podfile.lock: a CocoaPods project uses its.xcworkspace, a plain project its.xcodeproj. - The scheme defaults to the container's own name (
MyApp.xcworkspace->MyApp). That guess is checked once withxcodebuild -list; when it does not exist, the scheme files are read for the one declaringBuildableName = "*.app"(a workspace usually keeps its schemes in the sibling.xcodeproj). - The outcome reaches the session, including a failed build or install - not just a UI toast.
A leading action word is still honoured: /xcodebug logs, /xcodebug stop.
/xcodebug restart is the mid-run answer to "I just changed the code": it
rebuilds, reinstalls, relaunches and reattaches by replaying the last launch in
this session, so the phrase, device and scheme do not have to be retyped. It
forces the rebuild even though nothing about the invocation changed - the edited
code is the whole point - and it retires the previous capture for that app
through the same path as launch. The app identity parameters it remembers -
goal, bundleId, processName, device, scheme/workspace/project, configuration,
derivedDataPath, args, environment, push, match, dualChannel - are each
overridden by an explicit one (/xcodebug restart device=My-iPhone), so an
override is never silently ignored. installPods and timeoutSeconds are
per-invocation and always pass through. It remembers one launch - the most
recent - so after launching a second app, restart targets that second app.
The shell line a launch carried with command= is remembered too, and restart
runs it again after the relaunch - that is what closes the edit → restart → test
loop. Pass a new command="..." to override it, or command="" to clear it so
the next restart only rebuilds and relaunches.
command=: run a shell line alongside a capture
command= is a general primitive, not a test-runner hook: any shell line,
run to completion after the app is up, with the capture recording the whole time.
When it exits, the capture is stopped and you get the exit code plus the
app-side log for exactly that window. xcodebug knows nothing about the command's
contents - it never parses it, never assumes a framework.
That makes it the way to provoke something on the device and watch what the app does in response:
| You want to see... | command= runs |
|---|---|
| an automated case tapping through a flow | cd /repo && npm run test:weather |
| a backend event reaching the app | curl -X POST .../push -d @event.json |
| a file/dataset the app then consumes | ./scripts/import-fixtures.sh |
| a CLI driving the phone (deep link, locale, permission) | xcrun simctl ... / idevice* ... |
| a codegen or asset step whose output the app reloads | npm run codegen |
| a benchmark, then the log of that run | ./bench.sh --iterations 100 |
The app must already be running for this to mean anything, so command= is a
second phase appended to the main action - /xcodebug command="..." on its
own still launches first. Use action=await when the app is already up.
Worked case: the automation stands in for the user
The most common use is replacing a human's taps. A capture alone only records what the app does while a person drives the phone: slow to reproduce and never quite identical twice.
/xcodebug analyze adding a city in Weather command="cd /repo && npm run test:weather"
Without command= |
With command= |
|---|---|
| a person opens the weather page and adds a city | the case taps the same path |
| the log records whatever they happened to do | the log records exactly that path, every run |
| the agent waits for a human, then reads | the agent reads as soon as the case exits |
| "it worked when I tried it" | exit code + app-side log for the same run |
So the shape of a verification run is: goal (what to prove) + command (how to provoke it) + capture (what the app did). The exit code says whether the UI reached the expected state; the log says what the app did to get there - which is the part a test assertion cannot see.
The mechanics
That single line does the whole linkage run:
- build + install + launch the app, start the console capture;
- run the shell line to completion (blocking);
- stop the capture it was watching;
- report the exit code, the app-side cursor, and the log path - with the
phrase
analyze adding a city in Weatherattached as the goal the analysis must answer.
command= is a second phase appended to the main action, never an action of
its own. That ordering is the point: a command is only meaningful when the app is
already built, launched and being captured, so /xcodebug command="..." on its
own still launches first.
The two-step form remains available when the app is already up:
/xcodebug launch scheme=MyApp
/xcodebug await command="cd /repo && npm run test:weather"
# equivalent spellings
xcodebug action=launch command="cd /repo && npm run test:weather"
xcodebug action=await command="cd /repo && npm run test:weather"
/xcodebug await command="cd /repo && npm run test:weather" timeoutSeconds=900
A bare /xcodebug (or /xcodebug analyze <scenario>) has no deadline: it launches,
streams, and waits for you. Nothing stops it except stop, a new launch of the
same app, or the app exiting.
command is an opaque shell line handed to /bin/sh -lc; xcodebug knows
nothing about any test framework. Two consequences worth knowing:
- Quote the whole line.
command="cd /repo && npm run test". Unquoted, the slash command splits on whitespace before it reads the value and onlycdreaches the shell, so the run "succeeds" having run nothing - xcodebug now refuses that shape outright rather than guess. - Write
cd /repo && npm run test, nevercd /repo npm run test.cdtreats the trailing words as extra arguments and returns 0 without running anything, so the run looks like a pass. This one is inside a correctly quoted line, so xcodebug cannot detect it for you. - Let the repo pick its own config. A repo with several test configs will
fail with "No tests found" (exit 1) when run against the wrong one, which reads
exactly like a failing test. An npm script
(
"test:weather": "myrunner test --config myrunner-weather.config.ts") pins the right config once, where the repo already declares it.
What it reports: exit code, elapsed time, how many new lines the capture gained,
the log path, and the action=logs call (with the right since) that returns
the app side of that run. A non-zero exit is surfaced as an error, not as a
successful "run finished". Two things about the capture are reported when they
happened, because either one changes what the log means: that it was no longer
capturing when the command finished (with the reason, or the last line logged),
and that a console reattach relaunched the app during the run.
What the model does with it
The command's exit code answers "did the UI reach the expected state". The log answers "what did the app actually do", which no assertion can see. The cursor in the report is what makes the second half cheap:
awaited cd /repo && npm test · exit 0 · 125s
stopped console-mvq1bclw · 5568 new line(s) · <agentDir>/logs/xcodebug/console-...log
next: xcodebug action=logs captureId=console-mvq1bclw since=12428
That since= starts exactly where the case began, so the next call returns only
this run's app-side lines, not the 12k from launch:
xcodebug action=logs captureId=console-mvq1bclw since=12428 grep=Weather
14572 MySDK: Net | WeatherService pushCities(payload) count=4
14588 MySDK: Net | WeatherService pushCurrent(city="...") ok
Which is how "the case tapped add-city" becomes "the app pushed four cities". Two patterns that keep it small:
grep=narrows to the subsystem under test (a class name, a log prefix).wait match="..."blocks until an expected line appears, for the case where the assertion passes but the app's own path is what you need to see.
If the case fails, the same cursor still returns the app side, so the failure can be read from both ends: the assertion says where the UI stopped, the log says why.
Boundaries that keep it out of every other workflow:
awaitonly stops the capture it targets (captureId> the active capture). A second app under debug keeps streaming.- It never terminates the app (
stop keepApp=truesemantics), so the screen stays where the run left it. - It writes no capture state, so a later
launch/stop/logsis unaffected. - No timer or silence heuristic is involved: the process exiting is the only
automatic finish.
timeoutSeconds(default 1800) bounds the child process only; on timeout the child is killed and the capture is still stopped, and the result is reported as an error. - With no capture running,
awaitstill runs the command and reports the exit code instead of failing.
Prerequisite when the command drives the UI: the runner must not relaunch the
app. Many UI-test fixtures terminate and relaunch the app before every test
unless autoAppLaunch: false is set, which kills the very launch xcodebug is
capturing. Set it in the config the run uses. When it happens anyway, the capture
ends there and says the app was restarted outside it; it does not relaunch over
the runner's instance. A command that does not touch the app (a curl, a fixture
import, a codegen step) has no such constraint.
Run semantics
Verification is a loop: run, read the log, conclude, stop, edit the code, run
again. Each launch or syslog retires the previous cycle's capture for that same
app before the new bridge starts, avoiding duplicate capture streams for that
app; other apps' captures are preserved, so several apps can be debugged in one
session.
- Stop once the log has answered the question. Keeping a capture alive consumes resources; with native push enabled, it also keeps sending log batches.
- Do not stop while the user has not acted yet. Silence there means nothing has been tried, not that the run is over: say what to do on the phone and keep listening.
- When the initial process-table query succeeds, a dual-channel launch runs console app-PID discovery before connecting the syslog companion. An explicit stop during that step does not leave a new companion running.
- A console capture ends when the app process is confirmed gone, and its syslog
companion is stopped too. It records why -
the app exited, with the last line logged, which is devicectl's ownApp terminated due to signal 9.when the app was killed - in the log file, instatus, and under laterlogsreads. If the device wrote a crash report for the app, it is copied next to the log and its path is reported the same way. A standalonesyslogcapture is not bound to the app's lifetime and keeps reconnecting; stop it explicitly when finished. - An interrupted
wait,await, orlaunchwithcommandjoins the existing exit-diagnostic job (launch identity and report collection) before replying. A matching report supplies its system termination namespace, code and explanation, plus its local path, in the reply and follow-up details (terminationReason,crashReport). The report search can add time after the line-wait or command deadline; caller cancellation still interrupts it. A missing report or missing termination data is reported as unavailable, not replaced with a guessed cause. A verified App PID is required before a report can supply termination evidence; unknown identity is reported explicitly without promoting another instance's candidate report. Reattach-generation checks prevent an older search from overwriting the newly launched instance's report. Natural process exit registers that job before pipe/writer drain. Identity is taken from this console launch's own--json-outputresult (result.process.processIdentifier), not a late same-name process-table snapshot. Each bridge start owns a fresh result file, removed after reading; result identity and reattach-generation checks keep old jobs out of new runs. A missing, malformed or unsuccessful launch result remains unverified; an automatic reattach will not terminate an unverified running instance.waitjoins both identity and report collection. When a command exits, its capture and queued reconnect are stopped before awaiting that independent job; confirmed termination likewise cancels reconnect without cancelling collection. - A dropped console bridge whose app is still running is reattached, retrying
for as long as it takes. devicectl attaches a console only by launching, so
with the default
terminateExistinga reattach restarts the app and its state is gone: the log says so andstatuscounts the relaunches. An inconclusive probe (USB unplugged,devicectltimeout) is retried without relaunching. If the current PID is known but capture ownership cannot be verified, a reattach that would terminate the running app is skipped. - If the instance running is not the one this capture launched - another
session, a test runner or the user relaunched the app - the capture ends and
leaves that instance alone. Reattaching would terminate it. The session that
did the relaunching is told as well: its
launchreply notes that the app was already running and not started by it. idevicesyslogcan go silent with its process still alive; a 30s watchdog kills it and the exit hook reattaches. Reattachment has exactly one owner, so the watchdog and the exit hook can never both assume the other is handling it.- In native pi/omp push modes, after 60s with no new lines the run says so once
and keeps capturing. MCP users use
logs/waitto inspect quiet captures. - In pi/omp, a footer line and a widget above the editor show the live state,
e.g.
📖 xcodebug · capturing · 7895 lines · 42s · /xcodebug stop to end, plus recent log lines and the number of streaming channels. Claude Code can instead load the live display Mod. Codex can enable the experimental status line. - Native pushed log batches are hidden from the transcript (
display: false) but delivered to the model, subject to the per-batch limit. MCP does not push batches; neither MCP live display adds logs to model context. /xcodebug stop(oraction=stop) withoutcaptureIdcloses every running capture. An ID scopes the stop to that target; a console primary's syslog companion is stopped too. Other apps' captures are unaffected by a targeted stop.keepApp=falsealso terminates the app.
Usage
xcodebug action=devices
xcodebug action=doctor
xcodebug action=changes
xcodebug action=changes force=true
# build + install + launch, then stream the console
xcodebug action=launch scheme=MyApp
# build only
xcodebug action=build scheme=MyApp
# install an already-built .app without rebuilding
xcodebug action=install appPath=/path/to/App.app
# already-running app, no restart
xcodebug action=syslog processName=MyApp
# incremental reads (cursor-based)
xcodebug action=logs limit=200
xcodebug action=logs grep=MySDK
xcodebug action=logs grep=MySDK times=true
xcodebug action=wait match="DataPacket" timeoutSeconds=30
xcodebug action=wait match="sync (done|failed)" regex=true timeoutSeconds=30
xcodebug action=status
xcodebug action=stop keepApp=true
xcodebug action=terminate
# force a rebuild even when the tree is unchanged
xcodebug action=launch force=true
# skip the automatic pod install deliberately
xcodebug action=launch installPods=false
# edited the code mid-run: rebuild + relaunch the same app, same device, same goal
xcodebug action=restart
# run any shell line to completion, then stop the capture and hand back the log
xcodebug action=await command="cd /repo && npm run test:weather"
/xcodebug await command="cd /repo && npm run test:weather"
Reading logs from a cursor
Every logs read returns a cursor: the latest absolute line index in that
capture. Pass it as since to exclude lines at or before that index. Reads
return the newest matching lines up to limit; if the response says older
lines were omitted, advancing to its cursor skips those lines too.
xcodebug action=logs since=0 limit=2
2 line(s) (1692 older omitted) · cursor 1694
xcodebug action=logs since=1694
(no new lines since 1694; capture cursor is 1694)
xcodebug action=logs since=1694 limit=3
3 line(s) (6135 older omitted) · cursor 7832
Each capture retains at most 20k lines and 4 MiB of text in memory (counted as
UTF-16 bytes, excluding object overhead). A line larger than that text budget
is written to disk and delivered to live subscribers but not retained for
logs. The session keeps the most recent 10 ended captures; active captures
and captures reconnecting after a bridge failure are not evicted. Older capture
IDs leave logs/status, while their retained disk segments remain available.
A busy app fills that buffer in seconds, so a filtered read does not stop at it.
logs grep=... and wait also search for lines missing from memory, including
oversized lines between retained entries. They wait for writes through the
scan's cursor before reading disk; cancellation interrupts that work. The reply
reports how many lines were searched on disk and how many are unavailable.
An unfiltered logs returns the newest lines as before and
names the log file for the rest.
regex=true makes grep and match regular expressions, so one wait can
cover both outcomes of a step: match="sync (done|failed)". times=true
prefixes each returned line with the host time it arrived, for lining the log
up with a test runner's own output.
syslog: attach without relaunching
launch restarts the app because devicectl --console has to start it. When the
app is already running and the state you want to observe would not survive a
restart, attach instead:
xcodebug action=syslog processName=MyApp
This runs idevicesyslog -p <ProcessName> and leaves the app running. It needs
idevicesyslog from libimobiledevice (action=doctor reports whether it is
present), and it reads the device log for that process - print output still
only comes from the console bridge, per the table at the top.
Pushing logs into the conversation
In native pi/omp, push controls whether new lines are mirrored into the session.
The MCP adapter accepts only off; Claude Code and Codex use logs/wait.
context(default) — new lines are queued for the next turn (does not start one).off— pull withlogs/waitonly.wake— new lines start a turn.
A device console is a firehose; the push carries at most 80 lines per tick and
reports how many older lines it dropped. Combine it with match to keep it
useful, e.g. xcodebug action=launch match=MySDK push=wake.
Files
Every capture writes timestamped logs under
<agentDir>/logs/xcodebug/<mode>-<bundleId>-<YYYY-MM-DD_HH-mm-ss-SSS>.log.
It rotates through that base path plus .1 and .2, replacing the oldest
segment after three segments. Each segment targets 50 MiB and keeps complete
lines (a single larger line may exceed that size). Logging continues after
rotation; it no longer stops at the first 50 MiB. Capture status details list
successfully opened paths in chronological order as logFiles; logFile stays
the stable base path. Reconnecting appends to the current segment.
Disk writes apply backpressure to both capture pipes, so a slow disk pauses ingestion instead of accumulating an unlimited write queue. After the bridge exits, capture shutdown allows up to two seconds for the pipes and pending file writes to drain. If they remain blocked, it destroys the streams, reports a drain-timeout error in capture status, and completes shutdown; pending logs may be truncated.
Console launches also own a private .xcodebug-launch-* directory containing
launch.json and an owner.json marker with this extension's format, host PID
and creation time. The directory is mode 0700; the marker is mode 0600.
Result cleanup follows reading; raw metadata never enters the console log stream.
Ordinary stop leaves a pending result read available to exit diagnostics.
Session shutdown separately cancels those reads, blocks new bridge starts, and
allows up to three seconds per capture for pending startup, result cleanup and
log drainage, including older reattach results and captures evicted from visible
history. Blocked filesystem work or failed deletion is reported as incomplete
cleanup, including failures from captures already evicted from history.
Once cleanup settles, the session retains only the warning text for shutdown,
not the finished capture or its log buffer.
Residual result files may remain; task settlement alone is not proof of deletion.
The bundle id separates apps, and the timestamp includes milliseconds to
separate runs. Segment limits apply per capture. What xcodebug itself says while
a bridge is down - why the capture ended, each reattach - is appended to the same
file, so a log that stops also says why. A crash report copied from the device
lands beside the logs as crash-<unique-id>-<name>.ips. When the app PID is
known, a report without that PID is not retained.
Logs are kept for 30 days after their last write. The first build, launch or
syslog of a session deletes older build-, console-, syslog- and
pod-install- logs and crash-*.ips reports from this directory. The same
retention window applies to residual launch-result directories, but only when
the ownership marker is valid, the host PID is definitely absent, and the
directory and all known files are old. Active or uncertain owners, unmarked
legacy directories, malformed markers, symlinks and extra entries are retained.
Pruning removes only validated owner.json / launch.json files and an empty
directory, never recursively deleting a directory based on its prefix.
A successful build clears <agentDir>/logs/xcodebug/archive/ first, so snapshots
from a previous binary cannot be mistaken for the run that is starting.
Device archiving is off
Pulling the device unified log on a timer is disabled. Measured on an 18-minute
run it cost ~208 MB per snapshot (each covers the whole previous hour) with no
reader, and it cannot serve its stated purpose: log show --archive ... | grep MySDK returns nothing, because NSLog/print never enters the unified log.
Only framework records (RunningBoard, CFNetwork, WebKit) come back, so a dropped
console bridge is recovered by reconnecting, not by replaying an archive.