xclog Reference (iOS Simulator Console Capture)

xclog captures iOS simulator console output by combining

simctl launch --console

(print/debugPrint/NSLog) with

log stream --style json

(os_log/Logger). Single binary, no dependencies.

Binary Location

bash

${CLAUDE_PLUGIN_ROOT}/bin/xclog

When to Use

Runtime crashes — capture what the app logged before crashing
Silent failures — network calls, data operations that fail without UI feedback
Debugging print() output — see what the app is printing to stdout/stderr
os_log analysis — structured logging with subsystem, category, and level filtering
Automated log capture —
```
--timeout
```
and
```
--max-lines
```
for bounded collection

Critical Best Practices

Check
.axiom/preferences.yaml
first. If no saved preferences, run

list

before

launch

to discover the correct bundle ID.

App already running?

launch

will terminate it and relaunch. Use

attach

if you need to preserve current state (os_log only — no print() capture).

bash

# 1. FIRST: Check .axiom/preferences.yaml for saved device and bundle ID
# 2. If no preferences: Discover installed apps
${CLAUDE_PLUGIN_ROOT}/bin/xclog list

# 3. Find the target app's bundle_id from output
# 4. THEN: Launch with the correct bundle ID (restarts app)
${CLAUDE_PLUGIN_ROOT}/bin/xclog launch com.example.MyApp --timeout 30s --max-lines 200

# OR: Attach to running app without restarting (os_log only)
${CLAUDE_PLUGIN_ROOT}/bin/xclog attach MyApp --timeout 30s --max-lines 200

Preferences

Axiom saves simulator preferences to

.axiom/preferences.yaml

in the project root. Check this file before running
xclog list
— if preferences exist, use the saved device and bundle ID directly.

Reading Preferences

Before running

xclog list

, read

.axiom/preferences.yaml

yaml

simulator:
  device: iPhone 16 Pro
  deviceUDID: 1A2B3C4D-5E6F-7890-ABCD-EF1234567890
  bundleId: com.example.MyApp

If the file exists and contains a

simulator

section, use the saved

deviceUDID

and

bundleId

for xclog commands. Skip

xclog list

unless the user asks for a different app or the saved values fail.

bash

${CLAUDE_PLUGIN_ROOT}/bin/xclog launch <bundleId> --device <deviceUDID> --timeout 30s --max-lines 200

If the file doesn't exist or the

simulator

section is missing, fall back to

xclog list

discovery.

If the saved

deviceUDID

is not found among available simulators (xclog or simctl fails), fall back to discovery and save the new selection.

If the YAML is malformed, warn the developer and fall back to discovery. Do not overwrite a malformed file.

Writing Preferences

After a successful

xclog launch

or when the user selects a target app from

xclog list

output, save the device and bundle ID:

If
```
.axiom/
```
doesn't exist, create it. Then check
```
.gitignore
```
: if the file exists, check if any line matches
```
.axiom/
```
exactly — if not, append
```
.axiom/
```
on a new line. If
```
.gitignore
```
doesn't exist, create it with
```
.axiom/
```
as its content.
Read
```
.axiom/preferences.yaml
```
if it exists (to preserve other keys)
Update the
```
simulator:
```
section with
```
device
```
,
```
deviceUDID
```
, and
```
bundleId
```
Write the merged YAML back using the Write tool

Write the same

simulator:

structure shown in Reading Preferences above.

Commands

list — Discover Installed Apps

bash

${CLAUDE_PLUGIN_ROOT}/bin/xclog list
${CLAUDE_PLUGIN_ROOT}/bin/xclog list --device <udid>

Output (JSON lines):

json

{"bundle_id":"com.example.MyApp","name":"MyApp","version":"1.2.0"}
{"bundle_id":"com.apple.mobilesafari","name":"Safari","version":"18.0"}

launch — Full Console Capture

Launches the app and captures ALL output: print(), debugPrint(), NSLog(), os_log(), Logger.

bash

# Basic launch (JSON output, runs until app exits or Ctrl-C)
${CLAUDE_PLUGIN_ROOT}/bin/xclog launch com.example.MyApp

# Bounded capture (recommended for LLM use)
${CLAUDE_PLUGIN_ROOT}/bin/xclog launch com.example.MyApp --timeout 30s --max-lines 200

# Filter by subsystem
${CLAUDE_PLUGIN_ROOT}/bin/xclog launch com.example.MyApp --subsystem com.example.MyApp.networking

# Filter by regex
${CLAUDE_PLUGIN_ROOT}/bin/xclog launch com.example.MyApp --filter "error|warning|crash"

# Save to file
${CLAUDE_PLUGIN_ROOT}/bin/xclog launch com.example.MyApp --output /tmp/console.log --timeout 60s

attach — Monitor Running Process

Attaches to a running process via os_log only. Does NOT capture print()/debugPrint(). Simulator only.

bash

# By process name
${CLAUDE_PLUGIN_ROOT}/bin/xclog attach MyApp --timeout 30s

# By PID
${CLAUDE_PLUGIN_ROOT}/bin/xclog attach 12345 --max-lines 100

# Filter for errors only
${CLAUDE_PLUGIN_ROOT}/bin/xclog attach MyApp --filter "(?i)error|fault"

show — Historical Log Search (Simulator + Physical Device)

Searches recent logs without needing proactive capture. Works with both simulator and connected physical devices.

bash

# Simulator: show last 5 minutes of MyApp logs
${CLAUDE_PLUGIN_ROOT}/bin/xclog show MyApp --last 5m --max-lines 200

# Simulator: show last 10 minutes, errors only
${CLAUDE_PLUGIN_ROOT}/bin/xclog show MyApp --last 10m --max-lines 100 --filter "(?i)error|fault"

# Physical device: collect and show logs (device must be connected + unlocked)
${CLAUDE_PLUGIN_ROOT}/bin/xclog show MyApp --device-udid 00008101-... --last 5m --max-lines 200

# By PID
${CLAUDE_PLUGIN_ROOT}/bin/xclog show 12345 --last 2m

Physical device workflow:

show --device-udid

runs

log collect

to pull a log archive from the device over USB, then parses it locally. The device must be connected and unlocked.

When to use
show
vs
attach
:

```
show
```
— "What just happened?" (post-mortem, no setup needed)
```
attach
```
— "What's happening now?" (live streaming, must be running before the event)

Output Format

Default output is JSON lines (one JSON object per line).

JSON Schema (Default)

json

{
  "time": "10:30:45.123",
  "source": "os_log",
  "level": "error",
  "subsystem": "com.example.MyApp",
  "category": "networking",
  "process": "MyApp",
  "pid": 12345,
  "text": "Connection failed: timeout"
}

Field	Type	Present	Description
time	string	Always	HH:MM:SS.mmm timestamp
source	string	Always	`"print"` , `"stderr"` , or `"os_log"`
level	string	os_log only	`"debug"` , `"default"` , `"info"` , `"error"` , `"fault"`
subsystem	string	os_log only	Reverse-DNS subsystem (e.g. `com.example.MyApp` )
category	string	os_log only	Log category within subsystem
process	string	os_log only	Process binary name
pid	int	os_log only	Process ID
text	string	Always	The log message content

Fields not applicable to a source are omitted (not null).

Human-Readable Mode

bash

${CLAUDE_PLUGIN_ROOT}/bin/xclog attach MyApp --human
${CLAUDE_PLUGIN_ROOT}/bin/xclog attach MyApp --human --no-color

Options Reference

Option	Default	Description
`--device <udid>`	`booted`	Target simulator UDID
`--device-udid <udid>`	none	Physical device UDID (show command)
`--output <file>`	stdout	Also write to file
`--human`	off	Human-readable colored output
`--no-color`	off	Disable ANSI colors (--human mode)
`--filter <regex>`	none	Filter lines by Go regex
`--subsystem <name>`	none	Filter os_log by subsystem
`--max-lines <n>`	0 (unlimited)	Stop after n lines
`--timeout <duration>`	0 (unlimited)	Stop after duration (e.g. `30s` , `5m` )
`--last <duration>`	`5m`	How far back to search (show command)

Coverage by Source

Swift API	launch	attach	show
`print()`	yes	no	no
`debugPrint()`	yes	no	no
`NSLog()`	yes	yes	yes
`os_log()`	yes	yes	yes
`Logger`	yes	yes	yes

	Simulator	Physical Device
`launch`	yes	no
`attach`	yes	no
`show`	yes	yes
`Logger`	yes	yes

Use
launch
for full coverage.

attach

is for monitoring already-running processes.

Note:

launch

terminates any existing instance of the app before relaunching. If the app is already running and you don't want to restart it, use

attach

(os_log only).

Error Behavior

xclog prints errors to stderr and exits with code 1. Common errors:

Error	Cause	Fix
`simctl launch: ...`	Bad bundle ID or no booted simulator	Run `xclog list` to verify bundle ID; check `xcrun simctl list devices booted`
`could not parse PID from simctl output`	App failed to launch	Check the app builds and runs in the simulator
`invalid filter regex`	Bad `--filter` pattern	Check Go regex syntax (similar to RE2)
`invalid subsystem`	Subsystem contains spaces or special characters	Use reverse-DNS format: `com.example.MyApp` (alphanumeric, dots, underscores, hyphens only)

Interpreting Output

Filtering by Level

os_log levels indicate severity. For crash diagnosis, focus on

error

and

fault

Note:

--filter

matches against the message text, not the JSON output. To filter by level, use jq:

bash

${CLAUDE_PLUGIN_ROOT}/bin/xclog launch com.example.MyApp --timeout 30s 2>/dev/null | jq -c 'select(.level == "error" or .level == "fault")'

For text-based filtering,

--filter

works on message content:

bash

# Filter messages containing "error" or "failed" (case-insensitive)
${CLAUDE_PLUGIN_ROOT}/bin/xclog launch com.example.MyApp --filter "(?i)error|failed"

Common Subsystem Patterns

Subsystem	What it indicates
`com.apple.network`	URLSession / networking layer
`com.apple.coredata`	Core Data / persistence
`com.apple.swiftui`	SwiftUI framework
`com.apple.uikit`	UIKit framework
App's own subsystem	Application-level logging

Workflow: Diagnose a Runtime Crash

```
xclog list
```
→ find bundle ID

xclog launch <bundle-id> --timeout 60s --max-lines 500 --output /tmp/crash.log

→ start capture (this restarts the app — expected)

Reproduce the crash in the simulator

Read

/tmp/crash.log

and filter for errors:

jq 'select(.level == "error" or .level == "fault")' /tmp/crash.log

Check the last few lines before the stream ended (crash point)

If the crash is intermittent, increase bounds:

--timeout 120s --max-lines 1000

and repeat.

Workflow: Investigate Silent Failure

xclog launch <bundle-id> --subsystem com.example.MyApp --timeout 30s

Trigger the failing operation
Look for error-level messages in the app's subsystem
Cross-reference with network or data subsystems if app logs are silent

Resources

Skills: axiom-xcode-debugging, axiom-performance-profiling, axiom-lldb

axiom-xclog-ref

NPX Install

Tags

SKILL.md Content

xclog Reference (iOS Simulator Console Capture)

Binary Location

When to Use

Critical Best Practices

Preferences

Reading Preferences

Writing Preferences

Commands

list — Discover Installed Apps

launch — Full Console Capture

attach — Monitor Running Process

show — Historical Log Search (Simulator + Physical Device)

Output Format

JSON Schema (Default)

Human-Readable Mode

Options Reference

Coverage by Source

Error Behavior

Interpreting Output

Filtering by Level

Common Subsystem Patterns

Workflow: Diagnose a Runtime Crash

Workflow: Investigate Silent Failure

Resources