Debug Workflows

Debug Workflows

Advanced debugging techniques to diagnose and resolve issues.

Viewing Application Logs

Using Console.app

1. Open Console.app (in Applications/Utilities)
2. In the search field, enter: ClipboardRecast
3. Filter by Process to see only Clipboard Recast logs
4. Look for error messages or warnings

Common Log Messages

Normal Operation:

ClipboardRecast: Started clipboard monitoring
ClipboardRecast: Clipboard changed, content type: code
ClipboardRecast: Workflow matched: Explain Code
ClipboardRecast: AI request successful

Error Conditions:

ClipboardRecast: Failed to get API response: Invalid API key
ClipboardRecast: Network error: Connection timeout
ClipboardRecast: No workflows matched for content type: text

Debugging Workflows

Test Workflow Matching

1. Open Workflows window
2. Create a test workflow:
   • Name: “Test”
   • Trigger: Text
   • Action: Explain
   • Auto-trigger: ✗ (disabled)
3. Copy some text
4. Press Cmd+Shift+A
5. Check if “Test” appears in menu

Debug Content Type Detection

Copy different content types and check what’s detected:

Code:

def hello():
    print("world")

Error:

Error: Connection refused
    at connect (net.js:123)

URL:

https://example.com

Text:

Just plain text

Debugging API Issues

Test API Connection

Create a simple workflow and try each action:

1. Explain
2. Summarize
3. Translate

If one fails but others work, the issue is action-specific.

Verify API Key

1. Visit provider’s dashboard
2. Check key is valid and not revoked
3. Verify account has credits/quota
4. Check key permissions

Test with curl

Test your API key directly:

Claude:

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: YOUR_KEY" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-4-5","messages":[{"role":"user","content":"test"}],"max_tokens":100}'

OpenAI:

curl https://api.openai.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4","messages":[{"role":"user","content":"test"}]}'

Debugging Screenshot Issues

Test Screenshot Detection

1. Take screenshot (Cmd+Shift+4)
2. Open Console.app
3. Search for “ClipboardRecast”
4. Look for messages like:

   ClipboardRecast: New screenshot detected: Screenshot 2026-01-27...
   ClipboardRecast: Added screenshot to history

Verify Screenshot Naming

Screenshots must match this pattern:

• Screenshot YYYY-MM-DD at H.MM.SS AM.png
• Screen Shot YYYY-MM-DD at H.MM.SS AM.png

Test Vision API

Create a screenshot workflow and manually trigger it:

1. Take screenshot
2. Press Cmd+Shift+A
3. Select vision-capable action
4. Check Console.app for API response

Debugging Performance Issues

Monitor CPU Usage

1. Open Activity Monitor
2. Find ClipboardRecast process
3. Check CPU percentage
4. Normal: <1% when idle, <10% when processing

Monitor Memory Usage

Normal memory usage: 15-25 MB If much higher: possible memory leak

Monitor Network Traffic

Use Activity Monitor → Network tab to see API calls:

• Each transformation makes 1-2 API requests
• Check for excessive requests
• Auto-trigger workflows make frequent requests

Advanced Debugging

Enable Verbose Logging

Detailed logging options:

1. Check Console.app for application logs
2. Monitor file system access
3. Use macOS diagnostic tools

Check UserDefaults

Settings are stored in UserDefaults:

defaults read com.clipboardrecast.app

Reset Settings

If settings are corrupted:

defaults delete com.clipboardrecast.app

Then relaunch and reconfigure.

Clean Reinstall

1. Quit Clipboard Recast
2. Delete app from Applications
3. Remove settings:

   defaults delete com.clipboardrecast.app

4. Reinstall app
5. Reconfigure settings

Collecting Debug Information

When reporting issues, collect:

1. Console logs: Export from Console.app
2. System info: macOS version, app version
3. Settings: Provider, model (hide API key!)
4. Steps to reproduce: What you did before error
5. Error message: Exact error text
6. Workflow config: Export or screenshot

Common Debug Scenarios

Scenario: Workflow triggers but action fails

Debug steps:

1. Check Console.app for API error
2. Test API key with curl
3. Try different model
4. Verify content type matches action

Scenario: Screenshot not analyzed

Debug steps:

1. Verify screenshot saved to Desktop
2. Check Console for “screenshot detected” message
3. Verify provider supports vision
4. Check model is vision-capable
5. Test with manual trigger

Scenario: Auto-trigger not working

Debug steps:

1. Verify “Auto-process clipboard changes” enabled
2. Check workflow has “Auto-trigger” enabled
3. Test content type detection
4. Check Console for matching messages
5. Try manual trigger to isolate issue

Next Steps

• Common Issues: Quick fixes
• Privacy & Security: Security concerns