Workflows

Workflows Guide

Workflows are the heart of Clipboard Recast’s automation capabilities. This guide will help you master workflow creation and configuration.

What Are Workflows?

Workflows are automation rules that define:

• When to process clipboard content (trigger conditions)
• What actions to perform (one or more transformation steps)
• How to process it (manual vs automatic, with optional branching logic)

Accessing Workflows

Open the Workflows window:

• Press Cmd+R
• Or click menu bar icon → Workflows…

Creating a Workflow

Step 1: Click “Add Workflow”

Click the Add Workflow button in the Workflows window.

Step 2: Configure Basic Settings

Name: Give your workflow a descriptive name

• Examples: “Explain Code”, “Debug Errors”, “Fix Email Grammar”

Enabled: Check to activate the workflow

• Unchecked workflows won’t appear in actions menu
• Useful for temporarily disabling workflows

Step 3: Set Trigger Conditions

Trigger Type: Choose what content type activates this workflow

Available trigger types:

• Code: Detects programming code (keywords, syntax, indentation)
• Error: Detects error messages and stack traces
• URL: Detects web addresses (http/https links)
• Text: Matches general text (use keywords to refine)
• Screenshot: Triggers on clipboard images or desktop screenshots
• JSON: Detects JSON-formatted data
• XML: Detects XML-formatted data
• Markdown: Detects Markdown-formatted text
• HTML: Detects HTML content
• CSV: Detects comma-separated values
• Email: Detects email content
• File Path: Detects file system paths

Keywords (optional): Comma-separated words to match

• Works with any trigger type for additional filtering
• Example: “draft, email, message” matches text containing any of these words
• Case-insensitive matching
• Leave empty to match all content of that type

Step 4: Add Workflow Steps

Each workflow can have one or more steps. Each step performs an action on the content.

Available Actions (36+ total)

AI Processing (9 actions)

• Explain: Simplify and explain content in plain terms
• Summarize: Extract key points and main ideas
• Translate: Convert to English (or specify language in custom prompt)
• Fix Grammar: Correct spelling and grammar mistakes
• Simplify: Make text more accessible and readable
• Search Solutions: Find fixes for error messages and bugs
• Generate Code: Create code from natural language descriptions
• Improve: Optimize and enhance content quality
• Custom AI Prompt: Define your own prompt for specialized tasks

System Actions (9 actions)

• Open in Browser: Opens URLs in default browser
• Open in Preview: Opens images in Preview app
• Reveal in Finder: Shows file in Finder
• Open File: Opens file with default application
• Compose Email: Opens email client with content
• Show Notification: Displays a system notification
• Copy to Clipboard: Copies step output to clipboard
• Fetch URL Content: Fetches and extracts content from URL
• Exclude from History: Prevents item from being saved to clipboard history

File Actions (3 actions)

• Save to Folder: Saves content to a custom folder
• Save to Desktop: Saves content to Desktop
• Save to Downloads: Saves content to Downloads folder

Text Manipulation (6 actions)

• Convert to UPPERCASE: Converts all text to uppercase
• Convert to lowercase: Converts all text to lowercase
• Convert to snake_case: Converts text to snake_case format
• Convert to camelCase: Converts text to camelCase format
• Count Words: Counts number of words in text
• Count Characters: Counts number of characters in text

Encoding/Decoding (4 actions)

• Base64 Encode: Encodes text to Base64
• Base64 Decode: Decodes Base64 to text
• URL Encode: URL encodes text (percent encoding)
• URL Decode: Decodes URL encoded text

Developer Tools (6 actions)

• Format JSON: Pretty-prints JSON with indentation
• Minify JSON: Compacts JSON by removing whitespace
• Format XML: Pretty-prints XML with indentation
• Generate UUID: Generates a new UUID
• Timestamp to Date: Converts Unix timestamp to readable date
• Date to Timestamp: Converts date to Unix timestamp

Format Conversion (6 actions)

• Markdown to HTML: Converts Markdown to HTML
• HTML to Markdown: Converts HTML to Markdown
• JSON to YAML: Converts JSON to YAML format
• YAML to JSON: Converts YAML to JSON format
• Escape HTML: Escapes HTML special characters
• Unescape HTML: Unescapes HTML entities

MCP Tools (dynamic)

• Tools from connected MCP servers appear in the action list
• Format: ServerName: tool_name
• Examples: Filesystem: read_file, GitHub: create_issue, Slack: send_message
• See MCP Servers for setup and configuration

Step 5: Enable Auto-Trigger (Optional)

Auto-trigger when matched: Check to process automatically

When enabled:

• ✅ Workflow runs automatically when content matches
• ✅ No need to press Cmd+Shift+A
• ⚠️ Sends content to AI immediately (for AI actions)

When disabled:

• Workflow appears in actions menu when content matches
• You manually select it from the menu
• More control over when to process

Step 6: Save

Click Save to create the workflow.

Multi-Step Workflows

Workflows support multiple steps that execute sequentially, with each step’s output becoming the input for the next step.

Creating Multi-Step Workflows

1. Add your first step (action)
2. Click Add Step to add additional steps
3. Configure each step with its action and settings
4. Steps execute in order from top to bottom

Example: Clean and Translate

A workflow that fixes grammar first, then translates:

Step 1: Fix Grammar
Step 2: Translate

The text is first grammar-corrected, then the corrected text is translated.

Example: Format and Save JSON

Step 1: Format JSON
Step 2: Save to Downloads

The JSON is pretty-printed, then saved to your Downloads folder.

Conditional Branching

Workflows support conditional branching, allowing different paths based on the output of previous steps.

Condition Types

• Always: Always execute this branch
• Text contains: Execute if output contains specific text
• Text doesn’t contain: Execute if output doesn’t contain specific text
• Content type is: Execute if content matches a specific type
• Length greater than: Execute if text length exceeds threshold
• Length less than: Execute if text length is below threshold
• Image width >: Execute if image width exceeds threshold
• Image height >: Execute if image height exceeds threshold
• URL matches pattern: Execute if URL contains pattern
• Custom expression: Advanced expressions with variables

Custom Expressions

For advanced conditional logic, use custom expressions with these variables:

• length - Character count of the text
• width - Image width in pixels
• height - Image height in pixels
• type - Content type name
• contains('text') - Returns true if output contains the text

Example expressions:

• length > 500 - Execute if text is longer than 500 characters
• contains('error') - Execute if output contains “error”
• width > 1920 - Execute if image is wider than 1920 pixels

Branching Flow Control

Each step with branches can be configured to:

• Continue after branch: Continue to the next step after branch executes
• Stop after branch: End workflow execution after branch completes

Example Workflows

Example 1: Explain Code (Manual)

Perfect for: Understanding unfamiliar code

Name: Explain Code
Enabled: ✓
Trigger Type: Code
Steps: Explain
Auto-trigger: ✗
Keywords: (leave empty)

How to use:

1. Copy code
2. Press Cmd+Shift+A
3. Select “Explain Code”

Example 2: Auto-Debug Errors

Perfect for: Quick error solutions

Name: Debug Errors
Enabled: ✓
Trigger Type: Error
Steps: Search Solutions
Auto-trigger: ✓
Keywords: (leave empty)

How to use:

1. Copy error message
2. Wait 2 seconds
3. Solution appears automatically

Example 3: Fix Email Grammar (Keyword-Based)

Perfect for: Email writing

Name: Fix Email Grammar
Enabled: ✓
Trigger Type: Text
Steps: Fix Grammar
Auto-trigger: ✗
Keywords: draft, email, message, letter

How to use:

1. Copy text containing “draft”, “email”, “message”, or “letter”
2. Press Cmd+Shift+A
3. “Fix Email Grammar” appears in menu
4. Select it

Example 4: Auto-Open GitHub URLs

Perfect for: Quickly opening GitHub links

Name: Auto-open GitHub URLs
Enabled: ✓
Trigger Type: URL
Steps: Open in Browser
Auto-trigger: ✓
Keywords: github.com

How to use:

1. Copy a GitHub URL
2. URL automatically opens in browser

Example 5: Analyze Screenshots

Perfect for: Understanding UI/errors in screenshots

Name: Analyze Screenshot
Enabled: ✓
Trigger Type: Screenshot
Steps: Explain
Auto-trigger: ✓
Keywords: (leave empty)

How to use:

1. Take screenshot (Cmd+Shift+4)
2. Wait 2-3 seconds
3. AI automatically analyzes image
4. View explanation

Example 6: Multi-Step JSON Processing

Perfect for: Developers working with JSON APIs

Name: Format and Save JSON
Enabled: ✓
Trigger Type: JSON
Steps:
  1. Format JSON
  2. Save to Downloads
Auto-trigger: ✗

How to use:

1. Copy JSON data
2. Press Cmd+Shift+A
3. JSON is formatted and saved to Downloads

Example 7: Developer Workflow with Branching

Perfect for: Processing code differently based on content

Name: Smart Code Processor
Enabled: ✓
Trigger Type: Code
Steps:
  1. Explain
  2. Branch: If output contains "error" → Search Solutions
Auto-trigger: ✗

How to use:

1. Copy code
2. Press Cmd+Shift+A
3. Code is explained, and if errors are mentioned, solutions are searched

Example 8: Auto-Save Screenshots to Folder

Perfect for: Organizing screenshots automatically

Name: Auto-save Screenshots
Enabled: ✓
Trigger Type: Screenshot
Steps: Save to Folder (path: ~/Screenshots/Clipboard)
Auto-trigger: ✓

How to use:

1. Take any screenshot
2. Screenshot is automatically saved to your custom folder

Managing Workflows

Editing a Workflow

1. Select workflow in the table
2. Click Edit Workflow
3. Make changes
4. Click Save

Deleting a Workflow

1. Select workflow in the table
2. Click Delete Workflow
3. Confirm deletion

Enabling/Disabling Workflows

1. Select workflow in the table
2. Click Edit Workflow
3. Toggle the Enabled checkbox
4. Click Save

Or just delete and recreate when needed.

Viewing Workflow Details

The workflows table shows:

• Name: Workflow name
• Trigger: Content type that activates it
• Action: What transformation it performs
• Keywords: Keywords it matches (if any)
• Auto: Whether auto-trigger is enabled (✓ or -)
• Enabled: Whether workflow is active (✓ or -)

Auto-Processing Master Switch

The “Auto-process clipboard changes” checkbox at the top of the Workflows window is a master switch:

• Checked: Auto-trigger workflows can run automatically
• Unchecked: All workflows require manual trigger, even if auto-trigger is enabled

This is useful for:

• Temporarily disabling all auto-processing
• Testing workflows manually before enabling auto
• Preventing accidental processing of sensitive content

Workflow Matching Logic

Priority System

When you copy content:

1. Clipboard Recast detects content type
2. Finds all enabled workflows matching that type
3. Checks keywords (for Text type)
4. Shows matching workflows in actions menu
5. If auto-trigger is enabled and master switch is on → runs automatically

Multiple Matches

If multiple workflows match:

• All appear in the actions menu (manual trigger)
• Only first matching auto-trigger workflow runs (automatic)
• You can manually select any matching workflow

No Matches

If no workflows match:

• Default actions still available in menu
• Useful for ad-hoc transformations

Custom Prompts (Advanced)

When using Custom action, you can define your own prompt:

1. Select Custom as action
2. Enter your prompt in the text field
3. Use {content} as placeholder for clipboard content
4. Example: “Translate the following to Spanish: {content}”

Custom prompts give you unlimited flexibility for specialized tasks.

Best Practices

1. Start with Manual Workflows

Before enabling auto-trigger:

• Create workflow with auto-trigger disabled
• Test it several times manually
• Verify results meet expectations
• Then enable auto-trigger

2. Use Specific Keywords

For Text triggers:

• Add keywords to narrow matching
• Avoid generic words that match too often
• Use 3-5 specific keywords per workflow

3. Organize Your Workflows

Create focused workflows:

• One workflow per specific task
• Clear, descriptive names
• Don’t create too many auto-trigger workflows

4. Balance Auto and Manual

Good balance:

• 1-2 auto-trigger workflows for routine tasks
• 5-10 manual workflows for controlled actions
• Prevents overwhelming auto-processing

5. Consider API Costs

Each transformation uses AI provider credits:

• Auto-trigger workflows cost money on every match
• Monitor usage on high-frequency auto-trigger workflows
• Use manual triggers for expensive operations

6. Test Before Committing

Always test new workflows:

1. Create with auto-trigger off
2. Try 3-5 times manually
3. Adjust as needed
4. Then consider enabling auto-trigger

Troubleshooting Workflows

Workflow Not Appearing in Menu

Check:

• Is workflow enabled?
• Does content type match trigger?
• Do keywords match (for Text type)?
• Is master auto-process switch on?

Auto-Trigger Not Working

Check:

• Is “Auto-process clipboard changes” checked?
• Is workflow’s “Auto-trigger when matched” enabled?
• Does content actually match trigger conditions?
• Are you waiting long enough (1-2 seconds)?

Wrong Workflow Triggering

Solution:

• Make Text triggers more specific with keywords
• Disable auto-trigger on broader workflows
• Check trigger type matches content accurately

Results Not What Expected

Solution:

• Try a different AI provider
• Use Custom action with specific prompt
• Adjust your workflow’s action type
• Provide more specific content

Advanced Workflow Strategies

Multi-Step Chains

Instead of creating separate workflows, use multi-step workflows:

1. Add “Simplify” as step 1
2. Add “Fix Grammar” as step 2
3. Content flows through both transformations automatically

Context-Specific Workflows

Create workflows for specific contexts:

• “Fix Code Comments” (Code + keywords: “comment, todo, note”)
• “Summarize Article” (URL + auto-trigger)
• “Explain Error” (Error + manual trigger)

Language-Specific Workflows

Create workflows for different programming languages:

• “Explain Python” (Code + keywords: “def, import, python”)
• “Explain JavaScript” (Code + keywords: “function, const, let”)
• Gives you tailored explanations

Developer Utility Workflows

Create workflows for common developer tasks:

• “Encode for URL” (Text → URL Encode)
• “Decode Base64” (Text → Base64 Decode)
• “Generate UUID” (Any → Generate UUID)
• “Format Config” (JSON → Format JSON → Save to Folder)

Conditional Processing

Use branching for smart workflows:

• If text is long (>1000 chars) → Summarize first, then explain
• If JSON contains “error” → Search Solutions
• If image is large (width > 1920) → Show notification before processing

MCP-Powered Workflows

With MCP servers connected, create powerful integrations:

• “Error → GitHub Issue” (Error trigger → Search Solutions → MCP: GitHub create_issue)
• “Code → Save to Project” (Code trigger → MCP: Filesystem write_file)
• “Text → Slack Summary” (Text trigger → Summarize → MCP: Slack send_message)
• “URL → Research” (URL trigger → MCP: Brave Search → Summarize)

See MCP Servers for detailed MCP workflow examples.

Default Workflows

Clipboard Recast comes with 8 pre-configured workflows:

1. Explain Code - Manual, Code trigger
2. Find Error Solutions - Auto, Error trigger
3. Fix Grammar - Manual, Text trigger
4. Summarize Long Text - Manual, Text trigger
5. Auto-open GitHub URLs - Auto (disabled), URL + “github.com” keyword
6. Auto-save Screenshots - Auto (disabled), Screenshot trigger
7. Reveal File Paths - Auto (disabled), Filepath trigger
8. Save JSON to Downloads - Auto (disabled), JSON trigger

Next Steps

• Usage Guide: Learn how workflows integrate with usage
• Keyboard Shortcuts: Speed up workflow access
• Configuration: Optimize AI provider settings