Peekaboo/docs/application-resolving.md

summary	read_when
Review Application Resolution in Peekaboo guidance	planning work related to application resolution in peekaboo debugging or extending features described here

Application Resolution in Peekaboo

This document explains how Peekaboo resolves applications across all commands that accept an application parameter.

Overview

Peekaboo supports multiple ways to identify and target applications:

• Application Name - Human-readable name (e.g., "Safari", "Google Chrome")
• Bundle ID - Unique application identifier (e.g., "com.apple.Safari")
• Process ID (PID) - Numeric process identifier
• Fuzzy Matching - Partial name matching for convenience

Command Line Parameters

Most commands that work with applications support two parameters:

• --app - Application name, bundle ID, or PID in format "PID:12345"
• --pid - Direct process ID as a number

Examples

# By application name
peekaboo image --app Safari

# By bundle ID
peekaboo window close --app com.apple.Safari

# By PID using --app parameter
peekaboo menu list --app "PID:12345"

# By PID using --pid parameter
peekaboo app quit --pid 12345

# Both parameters (when they refer to the same app)
peekaboo window focus --app Safari --pid 12345

Resolution Methods

1. Application Name

The most common method - uses the localized application name:

peekaboo image --app "Google Chrome"
peekaboo window list --app TextEdit

Features:

• Case-insensitive matching
• Supports spaces in names
• Uses localized names (what you see in the UI)

2. Bundle Identifier

More precise than names, bundle IDs are unique:

peekaboo app launch --app com.microsoft.VSCode
peekaboo window close --app com.google.Chrome

Features:

• Exact matching only
• Always lowercase
• Guaranteed unique per application

3. Process ID (PID)

Direct process targeting using numeric IDs:

# Using --pid parameter
peekaboo app quit --pid 67890

# Using --app parameter with PID: prefix
peekaboo window focus --app "PID:67890"

# Finding PIDs
peekaboo list apps  # Shows all PIDs

Features:

• Most precise targeting method
• Works even if app name is unknown
• Useful for scripting and automation

4. Fuzzy Name Matching

Peekaboo supports partial name matching for convenience:

# Matches "Visual Studio Code"
peekaboo image --app "visual"
peekaboo image --app "code"
peekaboo image --app "studio"

# Matches "Google Chrome"
peekaboo window list --app chrome

Algorithm:

1. First tries exact match (case-insensitive)
2. Then tries "contains" match
3. Prioritizes running applications
4. Falls back to installed applications

Lenient Parameter Handling

Peekaboo is designed to be forgiving with parameters, especially for AI agents that might provide redundant information.

Allowed Redundancy

These are all valid and equivalent:

# Redundant PID specifications
peekaboo window close --app "PID:12345" --pid 12345

# Name and PID for same app
peekaboo image --app Safari --pid 67890  # If PID 67890 is Safari

Conflict Detection

These will produce errors:

# Different PIDs
peekaboo window close --app "PID:12345" --pid 67890

# Name doesn't match PID
peekaboo image --app Safari --pid 12345  # If PID 12345 is Chrome

Implementation Details

ApplicationResolvable Protocol

All commands with application parameters conform to the ApplicationResolvable protocol:

protocol ApplicationResolvable {
    var app: String? { get }
    var pid: Int32? { get }
}

This ensures consistent behavior across all commands.

Resolution Priority

When both --app and --pid are provided:

1. Validate they refer to the same application
2. Prefer the more readable format (name/bundle) for operations
3. Use PID for precise targeting when needed

Error Messages

Clear error messages help users understand issues:

• "No application found with name 'Safarii'" - Typo in name
• "Application 'Safari' is not running" - App not launched
• "Process with PID 12345 not found or terminated" - Invalid PID
• "Application mismatch: --app 'Safari' does not match PID 12345 (Chrome)" - Conflict

Best Practices

For Users

1. Use names for readability: --app Safari is clearer than --app "PID:12345"
2. Use PIDs for precision: When scripting or targeting specific instances
3. Use bundle IDs for reliability: When app names might be ambiguous

For Scripts

# Get PID for scripting
PID=$(peekaboo list apps --json | jq '.applications[] | select(.app_name=="Safari") | .pid')
peekaboo window close --pid $PID

# Or use bundle ID
peekaboo app launch --app com.apple.Safari

For AI Agents

AI agents can safely:

• Provide both --app and --pid if unsure
• Use PID format in either parameter
• Mix formats as needed

The lenient validation ensures the command works if the parameters are consistent.

Common Patterns

Finding Applications

# List all running apps with PIDs
peekaboo list apps

# Find specific app
peekaboo list apps | grep -i safari

Window Management

# List windows for an app
peekaboo list windows --app Safari

# Focus specific window
peekaboo window focus --app Safari --window-title "GitHub"

Cross-Space Operations

# Move window to current space (finds app by any method)
peekaboo space move-window --app Terminal --to-current
peekaboo space move-window --pid 12345 --to 2

Troubleshooting

Application Not Found

Symptoms:

• "Application 'X' not found"
• "No running application matches 'X'"

Solutions:

1. Check spelling: peekaboo list apps
2. Try partial name: --app chrome instead of --app "Google Chrome"
3. Use bundle ID: --app com.google.Chrome
4. Use PID directly: Find with list apps, then use --pid

PID Issues

Symptoms:

• "Process with PID X not found"
• "Invalid PID format"

Solutions:

1. Verify PID is current: peekaboo list apps
2. Check format: --app "PID:12345" needs quotes and prefix
3. Use --pid 12345 for direct numeric PIDs

Multiple Matches

Symptoms:

• Fuzzy matching finds wrong app
• Multiple apps with similar names

Solutions:

1. Use full name: --app "Visual Studio Code" not --app code
2. Use bundle ID for precision
3. Use PID for exact targeting

See Also

• Command index - Full command documentation
• Agent chat - Using Peekaboo with AI agents
• Automation guide - Scripting and automation patterns