Skip to main content
Alter Actions are customizable AI workflows that let you create specialized assistants for specific tasks. Combine AI instructions, voice triggers, tools, and conditional execution to automate anything on your Mac.

​
What is an Alter Action?

An Alter Action is an advanced automation that combines:
  • AI Instructions - System prompts defining how the AI behaves
  • Triggers - Voice commands, hotkeys, or conditional execution
  • Context - Access to selected text, files, active applications
  • Tools - Configured integrations with your Mac and 2000+ external services
  • Output - How results are displayed (markdown, code, inline insertion)
Think of an Alter Action as a “specialized AI assistant” customized for a specific task.

​
Opening the Action Editor

​
Method 1: Menu Bar (Fastest)

  1. Click the Alter menu icon in the menu bar (top right)
  2. Select Action Editor
Menu Bar

​
Method 2: Options Menu

  1. Open Alter window
  2. Click ⋯ (three dots) in top right
  3. Select Action Editor
Options Menu

​
Method 3: Keyboard Shortcut

Press ⌘⇧E (Command + Shift + E) to open the Action Editor directly
The keyboard shortcut is the fastest method once you’ve memorized it.

​
Action Editor Walkthrough

The Action Editor has 7 main sections, each controlling different aspects of your action. Use the left panel to navigate between tabs.

​
1. General Settings

Configure basic metadata and execution context. General Tab Fields:
  • Name - Human-readable action name (e.g., “Code Explainer”)
  • Description - What this action does (optional)
  • Category - Organize actions by type (code, productivity, business, etc.)
  • Workspace - Assign to a specific workspace (optional)
  • Include Profile - Include user profile information in AI context
Visibility Options:
  • Show only when running - Action only appears if an app is running
  • Show only when active - Action only appears if an app has focus
  • Workspace context - Choose which workspace(s) see this action
Each action gets a unique UUID automatically.

​
2. System Prompt

Define AI instructions and parameters for the model. System Prompt Tab System Prompt - Core AI instructions describing the AI’s behavior and expertise. Example:
Parameters - Define input fields users can customize before execution (text input, dropdown selections, etc.).

​
3. User Prompt

Template for the user-facing prompt that gets sent to the AI. User Prompt Tab Using Context Variables: Wrap variables in {{ }} to insert dynamic content:
Available Context Variables:
  • {{ textSelection }} - Currently selected text
  • {{ filePath }} - Path to selected file
  • {{ clipboard }} - Clipboard contents
  • Custom parameters you defined in System Prompt

​
4. When to Show

Control when and where this action appears. When to Show Tab Visibility Conditions:
  • Installed Applications - Show action only in specific apps (VSCode, Xcode, Safari, etc.)
  • Application is running - Action requires the app to be running
  • Application has focus - Action only works when app is in foreground
  • Web browser tab contains - Show action when browsing specific domains
  • Has content - Show action only when context is available

​
5. Automation

Configure execution behavior, schedules, and background processing. Automation Tab Fields:
  • Background Job - Run action in background without showing UI
  • Schedules - Execute action at specific times (e.g., “Every Monday at 9 AM”)
  • Quick Action - Execute the next “Quick Action” automatically after this completes
Use this for action chaining: first action → output → next action executes automatically.

​
6. Tools

Scope which tools are available for this action. Tools Tab Tool Configuration:
  • Disable Tools - Toggle off individual tools to restrict functionality
  • When empty: All tools are available
  • When configured: Only selected tools are available
Ask Anything defaults (beta100+): The built-in Ask Anything action enables Flow, Computer Use, and Ask User out of the box. Customize or duplicate it if you want a narrower tool set. Memory: Link the Memory tool when an action should read saved facts or search prior chats and meetings. Memory is not enabled for every action by default. See Memory and Manage Memory. The built-in Memory Catch-Up action ships with Memory already linked. It is Alter’s trusted way to bootstrap Memory from the last 30 days of chats and meetings—recommended when you first enable Memory or want to backfill recent history. See Memory Catch-Up. Coding tools (post-beta106): The fastest path is a Marketplace coding agent — download from Tools Manager → Marketplace → Browse (for example the live ChatGPT Agent) and run it once; Alter enables the required coding integration on first use. Alternatively, under Local Tools → Coding, connect ChatGPT, Cursor, OpenCode, and/or Claude in Tools Manager first, then scope which providers each action may use — for example a release action might enable Cursor only. Coding sessions run asynchronously; results return to the originating conversation. See Coding tools. Why Scope Tools?
  • Reduce AI decision overhead (focus on relevant tools)
  • Speed up action execution
  • Improve security (limit what actions can access)

​
7. Model

Select AI model, thinking effort, and creativity level. Model Tab Fields:
  • Model — Searchable picker grouped into Current, Favorites, and Other models. Leave empty to use the user’s default model setting, or pin a specific model for this action.
    • Each row shows context length, vision support, and favorites
    • When the model supports it, adjust Thinking effort (Low, Balanced, Max) inline
  • Temperature - Adjust creativity vs. precision
    • 0.0 - Deterministic (consistent, predictable)
    • 0.5 - Balanced (default)
    • 1.0 - Creative (unpredictable, exploratory)
Alter remembers thinking effort per model across Hub, QuickHub, and the Action Editor.
Use ⌘F in the Action Editor sidebar to search actions. Click the filter icon to narrow by background jobs, schedules, warnings, modified actions, or Folders (action categories). Folder filters include All and None shortcuts.

​
8. Gateways

Choose the exact gateway connections that can use this action. Every configured Buzz, Discord, and Telegram gateway has its own toggle, so two accounts on the same platform can have different access.
Buzz gateway (internal) — Buzz appears only in internal Alter builds for the dev team. See Buzz gateway (internal).
Availability — Gateway toggles: The bundled Ask Anything action initially appears on all compatible gateways. Custom actions start local-only until you enable one or more gateway toggles. Changing any toggle saves an explicit list of gateway connections, so a gateway added later does not inherit that action automatically. On Gateways, parameterless actions (no input fields) run immediately when picked from Choose action; parameterized actions wait for the user’s next message. Scheduled gateway delivery — When an action runs on a schedule, enable Start scheduled conversations on a gateway, choose an enabled Discord, Telegram, or Buzz (internal) gateway, then pick a Destination (channel, chat, or Buzz stream). Alter posts the action’s opening response there instead of only running locally. Buzz gateways can also set a Default scheduled destination in Settings → Integrations → Gateways. See Gateways for setup, chat commands, scheduled delivery, and gateway settings.

​
Best Practices

Clear Names

“Code Explainer” describes what it does. Avoid generic names like “Action 1”.

Specific Prompts

Be detailed with AI instructions. Generic prompts produce generic outputs.

Scope Tools

Enable only the tools your action needs. Reduces overhead and improves speed.

Use Context Variables

{{ textSelection }} always works. Manual copy/paste is error-prone.

Conditional Visibility

“Code Explainer” only in VSCode + Xcode reduces menu clutter.

Test Before Sharing

Test with real data before deploying to your team.

​
Common Action Examples

​
Example 1: Code Explainer

Setup:
  • Name: Explain Code
  • Category: code
  • Installed Apps: VSCode, Xcode
  • System Prompt: You are an expert programmer who explains code clearly
  • User Prompt: Please explain this code:\n\n{{ textSelection }}
  • Consumer: markdown
  • Temperature: 0.5

​
Example 2: Email Draft Creator

Setup:
  • Name: Draft Email
  • Category: productivity
  • When to Show: Mail app active
  • System Prompt: You are a professional business communicator
  • User Prompt: Transform this into a professional email:\n\n{{ textSelection }}
  • Tools: Enable only Mail
  • Consumer: in-place
  • Temperature: 0.6

​
Example 3: Scheduled Daily Brief

Setup:
  • Name: Daily Brief
  • Category: productivity
  • Automation: Schedule for 9:00 AM daily
  • Background Job: Enabled
  • System Prompt: Generate a daily brief of priorities

​
Voice Triggers

Assign voice hotkeys to trigger actions hands-free:
1

System Settings

Go to Settings > Voice Triggers
2

Add Trigger

Click + Add Trigger
3

Select Action

Choose action from dropdown
4

Assign Phrase

Enter trigger phrase (e.g., “explain” for Code Explainer)
5

Save

Click Save and you’re ready
Usage: Hold voice hotkey + say trigger phrase → Action executes with current context

​
x-callback-url Integration

Trigger Alter actions from any application using special URLs. This enables powerful cross-app automation workflows.

​
What is x-callback-url?

x-callback-url is an inter-app communication protocol that lets applications trigger actions in each other through formatted URLs.
  • Inbound - Trigger Alter actions from other apps (Shortcuts, Notes, Safari, etc.)
  • Outbound - Create links in Alter that open other apps (Bear, OmniFocus, Drafts, etc.)

​
Getting Your Action’s Callback URL

1

Open Action Editor

Press ⌘⇧E
2

Select Action

Choose the action you want to expose
3

Go to General

Navigate to General tab
4

Find URL Callback

Look for “URL Callback” section
5

Copy URL

Copy the alter:// URL
Format:

​
Triggering Alter Actions from Other Apps

Example 1: Web Search from Safari
Example 2: Code Explainer with Input
Example 3: Using in Apple Shortcuts
  1. Create a new Shortcut
  2. Add “Open URL” action
  3. Paste your alter:// URL
  4. Run the shortcut to trigger the action

​
Use Cases

Trigger action from Calendar → Generate meeting notes → Create email draft
Notion button → Trigger Alter action → Update task status
Copy text → Trigger action with callback → Open result in external app (no manual copying needed)

​
Keyboard Shortcuts

​
Troubleshooting

  • Check When to Show settings
  • Verify app is running/active (if configured)
  • Ensure action is enabled
  • Review System Prompt — be more specific
  • Adjust Temperature (lower for precision, higher for creativity)
  • Check User Prompt — ensure variables are correct
  • Verify hotkey is configured in Settings
  • Check microphone permissions
  • Test with manual trigger first
  • Go to Tools tab
  • Verify tools aren’t disabled
  • Check system permissions for the tool
Ready to build? Open Alter, press ⌘⇧E, and start creating your first action! Want to automate across apps? Use x-callback-urls to trigger actions from Safari, Shortcuts, Notes, or any app that supports URL schemes.