axiom-xclog-ref

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

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

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

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.

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

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: structure shown in Reading Preferences above.

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 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)

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

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

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

# 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

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 and repeat.

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