Claude-skill-registry gj-tool

Build, run, test, and debug GrooveTech apps (Orchestrator, Pfizer, GMP, Media Server). Use gj commands - never construct xcodebuild commands manually.

install

source · Clone the upstream repo

git clone https://github.com/majiayu000/claude-skill-registry

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/majiayu000/claude-skill-registry "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/data/gj-tool" ~/.claude/skills/majiayu000-claude-skill-registry-gj-tool && rm -rf "$T"

manifest: skills/data/gj-tool/SKILL.md

source content

gj Tool Skill

This skill is for GrooveTech Xcode projects. Use

gj

for all build/run/test operations.

Quick Reference

# Build & Run
gj run <app>              # Build + run + stream logs
gj run --device <app>     # Build + run on physical AVP device
gj run --ext <app>        # Run with extension/AVPStreamKit logs
gj run --clean <app>      # Clean build then run
gj build <app>            # Build only (no launch)
gj launch <app>           # Launch only (skip build)

# Logs & Debugging
gj logs <app> "pattern"   # Search logs (use as assertions)
gj crash <app>            # View latest crash log (.ips) - first 80 lines
gj crash <app> --full     # Show complete crash log with full backtrace
gj crash <app> --list     # List all crash logs
gj crash <app> --open     # Open crash in Console.app
gj diagnose <app>         # **USE THIS FIRST** - diagnose ANY crash/termination
gj diagnose <app> <log>   # Diagnose specific log file

# UI Automation (Simulator only; NOT ms. Tap automation reliable on iOS simulator only.)
gj ui screenshot <app>    # Capture screenshot
gj ui describe <app>      # Dump accessibility tree
gj ui tap-button <app> "label"  # Tap by accessibility label (iOS simulator only)
gj ui tap <app> x y       # Tap at coordinates (iOS simulator only)
gj ui home <app>          # Press Digital Crown (visionOS)

# Testing
gj test P0                # E2E connection tests
gj test --list            # List available tests

# Management
gj stop <app>             # Stop log streaming
gj clear <app>            # Clear logs and screenshots
gj status                 # Show simulators, devices, streams
gj devices                # List connected AVP devices

# Utilities
gj tui [app]              # Interactive log viewer (TUI)
gj sessions [path]        # CASS TUI for agent history

Apps:

orchestrator

(o),

pfizer

(p),

gmp

(g),

ms

(s),

all

(a)

⚠️ Known Limitations

visionOS Tap Automation is Broken

gj ui tap

and

gj ui tap-button

do not work on visionOS apps (Pfizer, GMP). The visionOS simulator reports incorrect accessibility frames (all elements at position 0,0).

Working on visionOS:

```
gj ui screenshot <app>
```
✓
```
gj ui home <app>
```
✓
```
gj run <app>
```
✓
```
gj logs <app>
```
✓

Not working on visionOS:

```
gj ui tap <app> x y
```
✗
```
gj ui tap-button <app> "label"
```
✗

Workaround: Manual testing in Simulator.app, or rely on log assertions.

See:

gj-tool/KNOWN_ISSUES.md

for full details.

macOS Media Server UI Automation (Not Supported)

gj ui ... ms

is not supported (UI commands are simulator-only). To trigger CloudSync, use the Media Server UI manually, then verify with

gj logs ms "CloudSync"

Device Logging: OSLog Not Captured

When running on physical devices via

gj run --device <app>

, only

print()

statements appear in device logs. OSLog entries are NOT captured (they go to the unified logging system, not stdout).

Workaround: Add

print()

alongside OSLog for device-visible diagnostics:

log.info("Download speed: \(speed)MB/s")
print("📊 Download speed: \(speed)MB/s")  // Visible via gj logs

Simulator runs capture both OSLog and print() normally.

Testing Philosophy

Prefer quick validation over full E2E tests during iteration.

Need to verify something?
├── Quick check?      → gj logs <app> "pattern"
├── Visual check?     → gj ui screenshot <app>
├── Test interaction? → gj ui tap-button + gj logs (Orchestrator only)
├── Full validation?  → gj test P0
└── Pre-commit?       → gj test all

Using Logs as Assertions

# ASSERT: Connection established (output should exist)
gj logs orchestrator "tcp_connection_established"

# ASSERT: No errors (output should be empty)
gj logs orchestrator "error"

Debugging Crashes & Unexpected Terminations

ALWAYS start with

gj diagnose

- it queries system logs and identifies the crash type even when the app log ends abruptly.

# FIRST: Run diagnose to get crash evidence from system logs
gj diagnose <app>         # Diagnoses most recent log
gj diagnose <app> <log>   # Diagnose specific log file

# What diagnose shows:
# - CRASH CONFIRMED (AMFI/corpse evidence from system logs)
# - Crash type: fatal 309 = EXC_RESOURCE, EXC_BREAKPOINT, etc.
# - Rate-limit warnings (no .ips when too many crashes)
# - Errors before crash from app log
# - Related .ips crash reports

# If diagnose shows EXC_BREAKPOINT and there's an .ips file:
gj crash <app> --full     # Full backtrace from .ips

# Search runtime logs for errors
gj logs <app> "error"
gj logs <app> "fatal"

Common crash types:

```
EXC_BREAKPOINT
```
→ Code assertion/trap, .ips file has backtrace
```
EXC_RESOURCE (fatal 309)
```
→ System killed for resource limits, often rate-limited (no .ips)

Full Documentation

Doc	Location	Contents
Comprehensive agent guide	`gj-tool/docs/AGENT-INSTRUCTIONS.md`	Testing philosophy, accessibility labels, workflows
Quick reference	`~/.agent-config/docs/gj-tool.md`	Command reference
UI automation	`~/.agent-config/docs/ui-automation.md`	AXe integration, finding labels
Known issues	`gj-tool/KNOWN_ISSUES.md`	visionOS limitations

For detailed accessibility labels and testing workflows, read

docs/AGENT-INSTRUCTIONS.md

in the gj-tool repo.

If gj Not Found

cd "/Users/dalecarman/Groove Jones Dropbox/Dale Carman/Projects/dev/gj-tool"
./install.sh
gj version  # Expected: 1.5.0