Peekaboo MCP

# 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 ```bash # 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: ```bash 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: ```bash 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: ```bash # 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: ```bash # 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: ```bash # 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: ```bash # 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: ```swift 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 ```bash # Get PID for scripting PID=$(peekaboo list apps --json-output | 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 ```bash # List all running apps with PIDs peekaboo list apps # Find specific app peekaboo list apps | grep -i safari ``` ### Window Management ```bash # List windows for an app peekaboo list windows --app Safari # Focus specific window peekaboo window focus --app Safari --window-title "GitHub" ``` ### Cross-Space Operations ```bash # 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 Reference](../README.md#commands) - Full command documentation - [Agent Integration](./agent-integration.md) - Using Peekaboo with AI agents - [Scripting Guide](./scripting.md) - Automation examples