xclog Reference (iOS Simulator Console Capture)

xclog captures iOS simulator console output by combining

simctl launch --console

log stream --style json

Binary Location

${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

list

launch

App already running?

launch

attach

# 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

xclog list

Reading Preferences

Before running

xclog list

.axiom/preferences.yaml

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

If the file exists and contains a

simulator

deviceUDID

bundleId

xclog list

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

If the file doesn't exist or the

simulator

xclog list

If the saved

deviceUDID

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

xclog list

1. 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.
2. Read

   .axiom/preferences.yaml

   if it exists (to preserve other keys)
3. Update the

   simulator:

   section with

   device

   ,

   deviceUDID

   , and

   bundleId

4. Write the merged YAML back using the Write tool

Write the same

simulator:

Commands

list — Discover Installed Apps

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

Output (JSON lines):

{"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.

# 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.

# 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.

# 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

log collect

When to use

show

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)

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

"print"

"stderr"

"os_log"

"debug"

"default"

"info"

"error"

"fault"

com.example.MyApp

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

Human-Readable Mode

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

Options Reference

--device <udid>

booted

--device-udid <udid>

--output <file>

--human

--no-color

--filter <regex>

--subsystem <name>

--max-lines <n>

--timeout <duration>

30s

5m

--last <duration>

5m

Coverage by Source

print()

debugPrint()

NSLog()

os_log()

Logger

launch

attach

show

Logger

Use

launch

attach

Note:

launch

attach

Error Behavior

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

simctl launch: ...

xclog list

xcrun simctl list devices booted

could not parse PID from simctl output

invalid filter regex

--filter

invalid subsystem

com.example.MyApp

Interpreting Output

Filtering by Level

os_log levels indicate severity. For crash diagnosis, focus on

error

fault

Note:

--filter

${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

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

Common Subsystem Patterns

com.apple.network

com.apple.coredata

com.apple.swiftui

com.apple.uikit

Workflow: Diagnose a Runtime Crash

1. xclog list

   → find bundle ID

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

   → start capture (this restarts the app — expected)
3. Reproduce the crash in the simulator
4. Read

   /tmp/crash.log

   and filter for errors:

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

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

If the crash is intermittent, increase bounds:

--timeout 120s --max-lines 1000

Workflow: Investigate Silent Failure

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

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

Resources

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