# Create a chat completion
Source: https://docs.alterhq.com/api-reference/create-a-chat-completion

openapi.json post /v1/chat/completions



# Create a completion
Source: https://docs.alterhq.com/api-reference/create-a-completion

openapi.json post /v1/completions



# List available models
Source: https://docs.alterhq.com/api-reference/list-available-models

openapi.json get /v1/models



# API Gateway & Router Service
Source: https://docs.alterhq.com/api-router/api-gateway

Use Alter as an OpenAI-compatible API endpoint for model routing

Alter provides an OpenAI-compatible endpoint you can use as a single Router across providers.

<Warning>
  **Intended use:** API Router is for personal usage, lightweight utilities, and low-volume projects. It is **not** intended to run high-throughput agentic systems (for example code agents, OpenClaw-style systems) or production services for other users.
</Warning>

## What you get

* One endpoint for many model providers
* Centralized billing through Alter
* `Provider#Model-name` model IDs
* Compatibility with OpenAI-style tools and SDKs

## Quick setup

### 1) Generate an API key

1. Open Alter Settings (`⌘ ,`)
2. Go to **Router**
3. Under **Alter API Keys**, click **Add New Key**
4. Copy the key (`sk-...`)

### 2) Use the endpoint

Primary endpoint:

```text theme={null}
https://alterhq.com/api
```

Some clients require `/v1`:

```text theme={null}
https://alterhq.com/api/v1
```

### 3) List available models

```bash theme={null}
curl https://alterhq.com/api/models \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Model naming format

Use this format when selecting a model:

```text theme={null}
Provider#Model-name
```

Examples:

* `OpenAI#gpt-5`
* `Claude#claude-sonnet-4-6`
* `Gemini#gemini-2.5-pro`
* `Alter#best`

## Split guides

To keep this page focused, advanced topics are in dedicated guides:

* [API Router for Development](/api-router/development)
* [API Router Operations & Troubleshooting](/api-router/operations)
* [App Integrations with API Router](/api-router/app-integrations)
* [Set Up TypingMind with Alter API](/api-router/typingmind)

## Related Docs

* [API Router Overview](/references/api-router-overview)
* [API Model Reference](/references/api-model-names)
* [Settings - Router](/how-to/settings-guide#router-settings)
* [Settings - API Keys](/how-to/settings-guide#api-keys-settings)


# App Integrations with API Router
Source: https://docs.alterhq.com/api-router/app-integrations

Connect third-party apps to Alter API Router

Use these guides when integrating external apps with Alter API Router.

## Integration guides

<CardGroup>
  <Card title="TypingMind" icon="plug" href="/api-router/typingmind">
    Configure a custom OpenAI Chat Completions model in TypingMind using Alter endpoint and headers.
  </Card>

  <Card title="Msty.ai" icon="plug" href="/api-router/msty">
    Set Alter endpoint, API key, and model ID format in Msty.ai.
  </Card>

  <Card title="General Setup Pattern" icon="book-open" href="/api-router/api-gateway">
    Base URL, API key handling, and model ID format used by most OpenAI-compatible apps.
  </Card>
</CardGroup>

## Integration checklist

1. Set base URL to `https://alterhq.com/api` (or `/v1` if required)
2. Set auth header to `Authorization: Bearer YOUR_API_KEY`
3. Use model IDs in `Provider#Model-name` format
4. Run a model list call before first request

## Related

* [API Router Overview](/references/api-router-overview)
* [API Model Reference](/references/api-model-names)


# API Router for Development
Source: https://docs.alterhq.com/api-router/development

Use Alter API Router from SDKs and custom code

Use Alter as an OpenAI-compatible backend in your own apps.

## Python (OpenAI SDK)

```python theme={null}
from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://alterhq.com/api/v1"
)

response = client.chat.completions.create(
    model="OpenAI#gpt-5",
    messages=[{"role": "user", "content": "What is machine learning?"}]
)

print(response.choices[0].message.content)
```

## JavaScript (OpenAI SDK)

```javascript theme={null}
import OpenAI from 'openai'

const openai = new OpenAI({
  apiKey: 'YOUR_API_KEY',
  baseURL: 'https://alterhq.com/api/v1',
  dangerouslyAllowBrowser: true
})

const completion = await openai.chat.completions.create({
  model: 'OpenAI#gpt-5',
  messages: [{ role: 'user', content: 'Hello!' }]
})

console.log(completion.choices[0].message.content)
```

## LangChain (Python)

```python theme={null}
from langchain_openai import ChatOpenAI

chat = ChatOpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://alterhq.com/api/v1",
    model="OpenAI#gpt-5"
)

response = chat.invoke("What is AI?")
print(response.content)
```

## Direct cURL

```bash theme={null}
curl https://alterhq.com/api/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "OpenAI#gpt-5",
    "messages": [{"role": "user", "content": "What is machine learning?"}]
  }'
```

## Supported parameters

* `model` (required)
* `messages` (required)
* `temperature`
* `max_tokens`
* `top_p`
* `frequency_penalty`
* `presence_penalty`

## Related

* [API Gateway & Router Service](/api-router/api-gateway)
* [API Router Operations & Troubleshooting](/api-router/operations)
* [API Model Reference](/references/api-model-names)


# Set Up Msty.ai with Alter API
Source: https://docs.alterhq.com/api-router/msty

Connect Msty.ai to Alter API Router with endpoint and API key configuration

Use this guide to connect Msty.ai to Alter API Router.

## Open Provider Configuration

In Msty.ai, open the provider/model configuration screen where you set:

* API endpoint (base URL)
* API key
* model selection

## 1) API Key

Paste your Alter key in the API key field:

`sk-...`

Generate a key in Alter via `Settings` -> `Router` -> `Alter API Keys`.

## 2) Inference Endpoint

Set the endpoint to:

```text theme={null}
https://alterhq.com/api/v1
```

## 3) Fetch and pick a model

Click **Fetch models** in Msty.ai after setting endpoint + API key.

Msty.ai will load the available Alter models so you can pick one from the list.
You do not need to type model IDs manually.

<img alt="Msty.ai endpoint and API key setup" />

## Verify Connection

1. Save settings in Msty.ai
2. Send a simple prompt
3. If it fails, verify endpoint, API key, then click **Fetch models** again

## Related

* [API Model Reference](/references/api-model-names)
* [API Router for Development](/api-router/development)
* [API Router Operations & Troubleshooting](/api-router/operations)


# API Router Operations & Troubleshooting
Source: https://docs.alterhq.com/api-router/operations

Model selection, limits, reliability, and common fixes for Alter API Router

## Model selection quick guide

**Speed**

* `Alter#light`
* `OpenAI#gpt-5-nano`
* `Gemini#gemini-2.5-flash-lite`

**Quality**

* `Alter#best`
* `OpenAI#gpt-5`
* `Gemini#gemini-2.5-pro`
* `Claude#claude-sonnet-4-6`

**Coding**

* `OpenAI#gpt-5`
* `Mistral#codestral-2501`
* `Claude#claude-sonnet-4-6`

**Web search**

* `Perplexity#sonar`
* `Perplexity#sonar-pro`

## Usage limits

Under fair use:

* Daily limit: `200` requests/day
* After limit: throttled to `1 request / 10 minutes`
* For steady higher volume: top up budget

<Note>
  API Router is designed for personal and low-volume workloads. For multi-user products or heavy agentic traffic, use dedicated provider infrastructure.
</Note>

## Common issues

### Models not listed

* Manually set the model to `Provider#Model-name`
* Verify API key is valid
* Check client supports model listing endpoints

### Authentication errors

* Confirm `Authorization: Bearer YOUR_API_KEY`
* Confirm endpoint is `https://alterhq.com/api` or `/api/v1`
* Confirm your account is active

### Connection issues

* Use an OpenAI-compatible client
* Verify network access to `alterhq.com`

### High latency

* Try lighter models (`OpenAI#gpt-5-nano`, `Alter#light`)
* Use streaming for long outputs

## Best practices

1. Keep API keys in env vars (never hardcode)
2. Monitor request volume and error rates
3. Match model capability to task complexity
4. Implement retries with backoff
5. Use lower-cost models for routine workloads

## Related

* [API Gateway & Router Service](/api-router/api-gateway)
* [API Router for Development](/api-router/development)
* [Models Not Listed in API Gateway](/common-issues/models-not-listed-in-api-gateway)


# Set Up TypingMind with Alter API
Source: https://docs.alterhq.com/api-router/typingmind

Connect TypingMind to Alter API Router using OpenAI Chat Completions format

Use this guide to add Alter as a custom provider in TypingMind.

## Open Custom Model Setup

In TypingMind, go to:

`Settings` -> `Models` -> `+ Add Custom Model`

## 1) Basic Configuration

Set the fields as follows:

* `Name`: `Alter`
* `API Type`: `OpenAI Chat Completions API`
* `Endpoint URL`: `https://alterhq.com/api/v1/chat/completions`
* `Model ID`: choose one from the supported IDs below
* `Context Length`: default value, or any value you prefer

<img alt="TypingMind basic configuration" />

## 2) Authentication

In the Authentication section:

* `Authentication Type`: `No authentication`

Note: We will pass the API key manually via Custom Headers in the next step.

## 3) Advanced Configuration (Required)

Expand `Advanced` at the bottom, then add a Custom Header pair:

* `Key` (left): `Authorization`
* `Value` (right): `Bearer <YOUR_API_KEY>`

Replace `<YOUR_API_KEY>` with your real Alter API key.
Make sure there is one space between `Bearer` and your key.

<img alt="TypingMind authorization header" />

## Supported Model IDs

Copy the Model ID exactly as shown.

### Claude (Anthropic)

* `Claude#claude-3-5-sonnet-latest`
* `Claude#claude-3-7-sonnet-20250219`
* `Claude#claude-3-opus-20240229`
* `Claude#claude-3-haiku-20240307`

### OpenAI

* `OpenAI#gpt-4o`
* `OpenAI#gpt-4o-mini`
* `OpenAI#chatgpt-4o-latest`
* `OpenAI#gpt-4-turbo`

### Gemini (Google)

* `Gemini#gemini-2.0-flash-001`
* `Gemini#gemini-2.0-flash-lite-001`
* `Gemini#gemini-1.5-pro`
* `Gemini#gemini-1.5-flash`

### DeepSeek and Others (via Providers)

* `Together#deepseek-ai/DeepSeek-R1`
* `Together#deepseek-ai/DeepSeek-V3`
* `Groq#deepseek-r1-distill-llama-70b`
* `Perplexity#sonar-pro`

<Tip>
  Need current model availability? Check [API Model Reference](/references/api-model-names).
</Tip>


# Calendar
Source: https://docs.alterhq.com/apps-tools/calendar

What Alter can do with Apple Calendar local tools

Alter can help you manage events in Apple Calendar from chat.

## What it supports

* List calendars and events
* Create events
* Update event details
* Remove events

## Best workflow

* [Manage your schedule with Alter](/workflows/manage-calendar-with-alter)

## Setup and troubleshooting

* [Use Tool Manager](/how-to/tool-manager-guide)
* [Tools Not Working](/common-issues/tool-not-working)


# Overview
Source: https://docs.alterhq.com/apps-tools/computer-use

Screen-based automation and extraction with Computer Use tools

Computer Use gives Alter a UI execution layer for desktop workflows. It can inspect windows, interact with UI elements, and pace multi-step flows.

## Tool set

* [Get Active App Context](/apps-tools/computer-use-get-active-app-context)
* [Perform](/apps-tools/computer-use-perform)
* [Wait](/apps-tools/computer-use-wait)
* [Scroll](/apps-tools/computer-use-scroll)

## Typical flow

1. Read current UI state with **Get Active App Context**.
2. Trigger UI actions with **Perform**.
3. Use **Scroll** when the target element is off-screen.
4. Add **Wait** between steps for loading or state transitions.

## Best workflow

* [Summarize your X feed with Computer Use](/workflows/summarize-x-feed-with-computer-use)

## Setup and troubleshooting

* [Settings](/how-to/settings-guide)
* [Manage tools](/how-to/tool-manager-guide)
* [Tools Not Working](/common-issues/tool-not-working)


# Get Active App Context
Source: https://docs.alterhq.com/apps-tools/computer-use-get-active-app-context

Capture active window content and OCR text for Computer Use workflows

Use this tool to read what is currently visible in an app or browser window before taking action.

## What it does

* Retrieves content from the active app window by default.
* Accepts optional `windowID` (`pid/title`) to target a specific window.
* Returns extracted text content.
* Adds OCR text from screenshots when useful.

## Common uses

* Read page or app state before clicking.
* Extract visible content for summaries.
* Build a stable context before multi-step automation.

## Input

* `windowID` (optional): target a specific window from `list_windows`.

## Good pairing

* [Perform](/apps-tools/computer-use-perform)
* [Scroll](/apps-tools/computer-use-scroll)
* [Wait](/apps-tools/computer-use-wait)


# Perform
Source: https://docs.alterhq.com/apps-tools/computer-use-perform

Run click, fill, and shortcut actions against UI elements

Use this tool to execute concrete UI interactions after you identify targets with Get Active App Context.

## Supported actions

* `click`: click a target element.
* `fill`: enter text into a text field or textarea.
* `shortcut`: send keyboard shortcuts (for example `cmd+c`, `ctrl+shift+t`).

## Inputs

* `elementID` (required for `click` and `fill`): element ID from Get Active App Context output.
* `text` (required for `fill`): value to insert in the target input.
* `shortcut` (required for `shortcut`): shortcut string.
* `windowID` (optional): target a specific window (`pid/title`) instead of the active one.

## Notes

* Element IDs expire with UI changes and session timing. Re-read context if an element is no longer valid.
* For background window targeting, use the same `windowID` across context read and perform steps.

## Good pairing

* [Get Active App Context](/apps-tools/computer-use-get-active-app-context)
* [Wait](/apps-tools/computer-use-wait)


# Scroll
Source: https://docs.alterhq.com/apps-tools/computer-use-scroll

Scroll active app windows in Computer Use flows

Use Scroll when target content is outside the current viewport.

## What it does

* Scrolls in the frontmost app window.
* Supports direction: `up`, `down`, `left`, `right`.
* Runs for a timed duration.

## Inputs

* `seconds` (optional): duration to scroll (default 3, max 3600).
* `direction` (optional): `up`, `down`, `left`, or `right` (default `down`).

## Typical use

* Bring hidden elements into view before calling Perform.
* Continue page traversal before re-reading with Get Active App Context.

## Good pairing

* [Get Active App Context](/apps-tools/computer-use-get-active-app-context)
* [Perform](/apps-tools/computer-use-perform)
* [Wait](/apps-tools/computer-use-wait)


# Wait
Source: https://docs.alterhq.com/apps-tools/computer-use-wait

Pause execution between Computer Use actions

Use Wait to add timing gaps between UI actions when pages, dialogs, or app states need time to update.

## What it does

* Pauses execution for a given number of seconds.
* Accepts numeric values and enforces a valid range.

## Input

* `seconds` (required): positive number of seconds to pause (max 3600).

## Typical use

* Add a short wait after navigation.
* Pause after submit/click before reading context again.
* Stabilize multi-step flows where UI renders asynchronously.

## Good pairing

* [Perform](/apps-tools/computer-use-perform)
* [Get Active App Context](/apps-tools/computer-use-get-active-app-context)


# Contacts
Source: https://docs.alterhq.com/apps-tools/contacts

What Alter can do with Apple Contacts local tools

Alter can help maintain contact data in Apple Contacts.

## What it supports

* Find and list contacts
* Create contacts
* Update contacts
* Delete contacts with confirmation

## Best workflow

* [Manage contacts with Alter](/workflows/manage-contacts-with-alter)

## Setup and troubleshooting

* [Use Tool Manager](/how-to/tool-manager-guide)
* [Tools Not Working](/common-issues/tool-not-working)


# DEVONthink
Source: https://docs.alterhq.com/apps-tools/devonthink

Set up Alter as your AI provider in DEVONthink

[DEVONthink](https://www.devontechnologies.com/apps/devonthink) is a professional document and information manager for Mac and iOS. It stores your documents as data in easy-to-backup databases where you can structure, organize, and work with them. DEVONthink uses AI to see connections between documents, suggest categories, and assist in searching your databases.

<Info>
  This integration lets you use **Alter as your AI provider** in DEVONthink. It's available to anyone with an Alter subscription.

  Alter provides an OpenAI-compatible API endpoint — learn more about [API pricing](/references/pricing-faq) and [available models](/references/api-model-names).
</Info>

## What it supports

* AI-powered search and querying across your DEVONthink database
* Smart sorting and organization with AI
* Content summarization and extraction
* Integration with generative AI via OpenAI-compatible providers

## Setup Alter with DEVONthink

1. Open **DEVONthink** and go to **Settings**
2. Navigate to the **AI** tab
3. Under **Provider**, select **OpenAI Compatible**
4. Enter your Alter credentials:
   * **API Key**: Your Alter API key
   * **Endpoint**: `https://alterhq.com/api/v1/chat/completions`
5. Click the **Refresh** button to load available models

<img alt="DEVONthink Alter setup" />

## Known issue

DEVONthink has a bug where the model list may not appear after clicking **Refresh**. If this happens:

1. Quit DEVONthink completely
2. Reopen DEVONthink
3. Go back to **Settings** > **AI**
4. The available Alter models should now appear in the list

## Recommended settings

After selecting your model, you can adjust the context window for better performance with longer documents. A max output tokens of **16,000 tokens** is recommended for most use cases.

## Learn more

* [DEVONthink AI documentation](https://www.devontechnologies.com/apps/devonthink/ai)
* [DEVONthink automation](https://www.devontechnologies.com/apps/devonthink/automation)
* [DEVONthink support](https://www.devontechnologies.com/support/support)


# Overview
Source: https://docs.alterhq.com/apps-tools/integrations-overview

Understand local tools and external integrations in Alter

Alter supports two integration paths:

* Local tools that act directly in your Mac apps.
* External services that connect through APIs.

## Choose the right integration type

* Use local tools when you want fast, private actions on your Mac.
* Use external integrations when you need cross-app automation.

## Local tools

Local tools run in your environment and are best for daily execution.

<CardGroup>
  <Card title="Free to use" icon="gift">
    Local tools are included.
  </Card>

  <Card title="Private by default" icon="shield">
    Local workflows stay on your Mac.
  </Card>

  <Card title="App control" icon="command">
    Alter can execute app actions, not only summarize data.
  </Card>

  <Card title="Offline-friendly" icon="wifi-off">
    Many local actions work without external services.
  </Card>
</CardGroup>

### Enable local tools

<Steps>
  <Step title="Open Tool Manager">
    In Alter, open the three-dot menu and select **Tools Manager**.
  </Step>

  <Step title="Enable only what you need">
    Turn on the relevant local tools for the workflow you are running.
  </Step>

  <Step title="Test with one prompt">
    Run a small prompt to confirm permissions and expected behavior.
  </Step>
</Steps>

## External integrations

External integrations connect Alter with services such as Slack, Notion, and GitHub.

* Use these when your workflow spans multiple systems.
* Enable only the services required for your current task.

## Popular workflow entry points

<CardGroup>
  <Card title="Manage calendar" icon="calendar" href="/workflows/manage-calendar-with-alter">
    Plan and update your schedule from Alter.
  </Card>

  <Card title="Mail workflows" icon="mail" href="/workflows/manage-mail-with-alter">
    Draft replies and process inbox tasks.
  </Card>

  <Card title="Messages workflows" icon="message-circle" href="/workflows/send-messages-with-alter">
    Send and manage iMessages faster.
  </Card>

  <Card title="Computer Use workflow" icon="screen-share" href="/workflows/summarize-x-feed-with-computer-use">
    Extract and summarize visible UI content.
  </Card>
</CardGroup>

## Related pages

* [Tool Manager guide](/how-to/tool-manager-guide)
* [Integrations troubleshooting](/apps-tools/integrations-troubleshooting)
* [Mail app reference](/apps-tools/mail)


# Troubleshooting
Source: https://docs.alterhq.com/apps-tools/integrations-troubleshooting

Fix common integration and tool issues in Alter

Use this page when integrations are connected but not behaving as expected.

## Quick checks

1. Re-open **Tools Manager** and confirm the relevant tool is enabled.
2. Confirm your selected model supports tools.
3. Re-test with one simple prompt before running multi-step flows.

## Common issues

### Tool does not run

* Verify required input fields are present in your prompt.
* Disable unrelated tools to reduce routing ambiguity.
* Re-authenticate the integration if it uses external credentials.

### Assistant answers without using tools

* Switch to a tool-capable model.
* Ask with an explicit action request (for example, "create", "send", "add").

### Connection appears valid but calls fail

* Check account scope and app permissions in the provider.
* Retry with a minimal test action to isolate the failing step.

## Where to go next

* [Tool Manager guide](/how-to/tool-manager-guide)
* [Integrations overview](/apps-tools/integrations-overview)
* [Tools not working](/common-issues/tool-not-working)


# Mail
Source: https://docs.alterhq.com/apps-tools/mail

What Alter can do with Apple Mail local tools

Alter currently supports lightweight Apple Mail workflows focused on unread visibility and draft creation.

## What it supports

* Read unread email previews
* Create draft emails for review

## Best workflow

* [Check unread emails and draft replies](/workflows/manage-mail-with-alter)

## Setup and troubleshooting

* [Use Tool Manager](/how-to/tool-manager-guide)
* [Tools Not Working](/common-issues/tool-not-working)
* [Integrations overview](/apps-tools/integrations-overview)


# Maps
Source: https://docs.alterhq.com/apps-tools/maps

What Alter can do with Apple Maps local tools

Alter can help discover places and get routes with Apple Maps.

## What it supports

* Search places by name/address
* Find nearby places by category
* Get route directions

## Best workflow

* [Plan places and routes with Alter Maps](/workflows/plan-places-and-routes-with-alter-maps)

## Setup and troubleshooting

* [Use Tool Manager](/how-to/tool-manager-guide)
* [Tools Not Working](/common-issues/tool-not-working)


# Messages
Source: https://docs.alterhq.com/apps-tools/messages

What Alter can do with Apple Messages local tools

Alter can send outbound iMessages to valid recipients.

## What it supports

* Send iMessages to phone numbers or emails

## Best workflow

* [Send iMessages faster with Alter](/workflows/send-messages-with-alter)

## Setup and troubleshooting

* [Use Tool Manager](/how-to/tool-manager-guide)
* [Tools Not Working](/common-issues/tool-not-working)


# Notes
Source: https://docs.alterhq.com/apps-tools/notes

What Alter can do with Apple Notes local tools

Alter can create, search, and organize notes in Apple Notes.

## What it supports

* Search notes and read full content
* Create and update notes
* Create folders and move notes
* Remove notes

## Best workflow

* [Capture and organize notes with Alter](/workflows/manage-notes-with-alter)

## Setup and troubleshooting

* [Use Tool Manager](/how-to/tool-manager-guide)
* [Tools Not Working](/common-issues/tool-not-working)


# Reminders
Source: https://docs.alterhq.com/apps-tools/reminders

What Alter can do with Apple Reminders local tools

Alter can help you capture and maintain task lists in Apple Reminders.

## What it supports

* Create reminders and reminder lists
* List upcoming reminders
* Update reminders (date, status, list)
* Remove reminders

## Best workflow

* [Stay on top of tasks with Alter](/workflows/manage-reminders-with-alter)

## Setup and troubleshooting

* [Use Tool Manager](/how-to/tool-manager-guide)
* [Tools Not Working](/common-issues/tool-not-working)


# Custom Models Not Showing
Source: https://docs.alterhq.com/common-issues/custom-provider-not-showing

Fix missing OpenAI, Mistral, or local models in the model selector

<Note>
  **Important:** You need an API key from your provider (OpenAI, Mistral, etc.) before they will appear in Alter.
</Note>

## What's happening?

You've added your API key, but when you press `/` to see models:

* The **Custom** section is empty
* You don't see your provider's models
* You only see Alter Cloud models

## Common setup mistakes

<AccordionGroup>
  <Accordion icon="toggle-off" title="Custom Provider is turned off">
    Even with an API key entered, you need to enable custom providers:

    1. Open Alter Settings (`Cmd + ,`)
    2. Go to **API Keys** tab
    3. Find **Custom Provider** section
    4. Toggle **Enable Custom Provider** to ON
    5. You should see a ✓ next to "Custom Endpoint"
  </Accordion>

  <Accordion icon="link" title="Wrong endpoint format (especially for Azure)">
    **For most providers:** Just paste your API key – the endpoint is automatic

    **For Azure specifically**, you need the full URL:

    ```
    https://your-instance.openai.azure.com/openai/deployments/your-model-name/chat/completions?api-version=2024-02-15-preview
    ```

    Make sure your URL includes:

    * Your instance name
    * The deployment name
    * The api-version parameter
  </Accordion>

  <Accordion icon="key" title="Invalid or expired API key">
    Quick checks:

    * Did you copy the full key? (They usually start with `sk-`)
    * Has the key expired?
    * Do you have billing set up with the provider?
    * Did you accidentally include extra spaces?

    Try generating a new key from your provider's dashboard.
  </Accordion>
</AccordionGroup>

## Quick setup guide

<Steps>
  <Step title="Get your API key">
    * **OpenAI:** [https://platform.openai.com/api-keys](https://platform.openai.com/api-keys)
    * **Mistral:** [https://console.mistral.ai/api-keys/](https://console.mistral.ai/api-keys/)
    * **Gemini:** [https://aistudio.google.com/app/apikey](https://aistudio.google.com/app/apikey)
  </Step>

  <Step title="Enter it in Alter">
    1. Settings (`Cmd + ,`) → **API Keys**
    2. Select your provider from the dropdown
    3. Paste your key
    4. Toggle **Enable Custom Provider** ON
  </Step>

  <Step title="Check the model selector">
    1. Press `/` in the Alter prompt box
    2. Look for the **Custom** section
    3. You should see your provider's models listed
  </Step>
</Steps>

## Verify it's working

After setup:

1. Press `/` to open the model picker
2. Look for the **Custom** category
3. Select one of your custom models
4. Send a test message
5. **Success:** The model responds using your own API key!

<Tip>
  **Budget tip:** Using your own API key means you're billed directly by the provider. Monitor your usage on their dashboard to avoid surprises!
</Tip>

## Related help

* [How to use your own API key](/how-to/use-byok)
* [Choosing AI models](/how-to/choose-generative-model)


# Data missing after reinstall or cleanup
Source: https://docs.alterhq.com/common-issues/data-missing-after-reinstall

Understand why chats and transcripts can disappear after uninstalling Alter and what recovery options you may still have.

## What's happening?

After reinstalling Alter, you open the app and your chats, transcripts, or other local history are gone.

This often happens after:

* Using CleanMyMac or another uninstall utility
* Removing the app and related support files
* Downgrading by uninstalling first instead of replacing the app in `Applications`

## Why this happens

<Warning>
  Alter data is local-only. There is no cloud history restore for chats, transcripts, or other local app data.
</Warning>

If an uninstall tool deletes Alter's support files, it can remove the local database and transcript files along with the app.

## What you can check

1. Open the local data location from Alter settings if the shortcut is still available.
2. Check whether your Alter files are still present in `~/Library/Application Support/Alter`.
3. If you use Time Machine or another Mac backup, restore the missing Alter data from that backup.

## When recovery is unlikely

If the uninstall utility already removed the Alter support files and you do not have a separate backup, the missing chats and transcripts usually cannot be restored.

## How to avoid this next time

<Steps>
  <Step title="Do not uninstall before changing versions">
    Download the version you want from [alterhq.com/changelog](https://alterhq.com/changelog) and replace the app in `Applications`.
  </Step>

  <Step title="Back up local data first">
    Copy your Alter data to another location or make sure your normal Mac backup is current.
  </Step>

  <Step title="Avoid cleanup uninstallers for troubleshooting">
    Use a simple app replacement first. Cleanup tools are best only when you want a full reset.
  </Step>
</Steps>

## Related help

* [Reinstall or downgrade Alter safely](/how-to/reinstall-or-downgrade-alter)
* [Local data and privacy](/references/local-data-and-privacy)


# Keyboard Shortcut Not Working
Source: https://docs.alterhq.com/common-issues/hotkey-not-working

Fix hotkey issues when Alt+Space or your custom shortcut won't open Alter

<Note>
  **First, check the basics:** Is Alter actually running? Look for the Alter icon in your menu bar at the top of your screen.
</Note>

## What's happening?

You press your keyboard shortcut (default is `Alt + Space`), but:

* Nothing happens at all
* The quick menu doesn't appear
* It works in some apps but not others

<AccordionGroup>
  <Accordion icon="gear" title="Problem: Shortcut was changed">
    **Solution:** Check what your shortcut is actually set to

    1. Open Alter (click the menu bar icon if needed)
    2. Press `Cmd + ,` to open Settings
    3. Go to the **Defaults** tab
    4. Look at **Open notch keybinding** – this shows your current shortcut
    5. Press `Alt + Space` (or your preferred combo) to set it
  </Accordion>

  <Accordion icon="xmark" title="Problem: Another app is using the same shortcut">
    **Solution:** Find the conflict and change it

    Common apps that use `Alt + Space`:

    * Alfred
    * Raycast
    * Spotlight (sometimes)
    * Language switchers

    **Try a different shortcut:**

    * `Cmd + Shift + A`
    * `Ctrl + Option + Space`
    * `Fn + F12`

    Pick something you can easily remember and that no other app uses.
  </Accordion>

  <Accordion icon="lock" title="Problem: Permissions issue">
    **Solution:** Check Accessibility permissions

    Alter needs Accessibility permission to detect global hotkeys:

    1. Open **System Settings** → **Privacy & Security** → **Accessibility**
    2. Make sure **Alter** is in the list and enabled
    3. If it's grayed out, click the lock icon and enter your password
    4. Toggle Alter off, then back on
  </Accordion>
</AccordionGroup>

## Quick test

After making changes:

1. Click into any app (like Safari or Notes)
2. Press your shortcut (`Alt + Space` or whatever you set)
3. **Success:** The Alter notch/quick panel should appear immediately

<Tip>
  **Pro tip:** You can also open Alter by hovering your mouse over the notch at the top of your screen. This bypasses keyboard shortcuts entirely!
</Tip>

## Related help

* [All keyboard shortcuts](/references/shortcuts)
* [How to change your hotkey](/how-to/change-hotkey)


# Microphone Not Working
Source: https://docs.alterhq.com/common-issues/mic-not-transcribing

Fix voice input and dictation issues when Alter doesn't transcribe your speech

<Note>
  **Quick check:** Is your Mac's microphone working in other apps like Voice Memos? If not, this is a system issue, not an Alter issue.
</Note>

## What's happening?

You're holding the microphone button or pressing your voice hotkey, but:

* Nothing happens when you speak
* The dictation starts but no text appears
* The recording indicator shows but stays blank

## Common causes

<CardGroup>
  <Card title="Missing Permissions" icon="shield">
    Alter doesn't have permission to access your microphone
  </Card>

  <Card title="Wrong Voice Processor" icon="microphone">
    Local voice models aren't downloaded or configured
  </Card>

  <Card title="Language Mismatch" icon="language">
    Automatic language detection isn't working for your accent
  </Card>

  <Card title="Wrong Input Device" icon="speaker">
    Alter is using the wrong microphone or system default isn't working
  </Card>
</CardGroup>

## How to fix it

<Steps>
  <Step title="Check Microphone Permissions">
    1. Open **System Settings** on your Mac
    2. Go to **Privacy & Security** → **Microphone**
    3. Make sure **Alter** is enabled in the list
    4. If it's already on, try toggling it off and back on
  </Step>

  <Step title="Select the Right Input Device">
    By default, Alter uses your system default microphone, but macOS doesn't always handle this correctly:

    1. Look for the **control block** in Alter's interface (or check the menu bar)
    2. Click to open the device selector
    3. Choose your specific microphone from the list
    4. Try speaking again

    This fixes issues like:

    * Alter not picking up any audio despite permissions being granted
    * Meeting recordings capturing only the other participant and not you
    * Low quality or intermittent audio input
  </Step>

  <Step title="Verify Voice Processor Settings">
    1. In Alter, open **Settings** (`Cmd + ,`)
    2. Go to the **Dictation** tab
    3. Check that **Voice Processor** is set to:
       * **Cloud** (for best accuracy)
       * **Local (Apple)** (for privacy)
       * Or download a Whisper model if you want offline processing
  </Step>

  <Step title="Set Language Explicitly">
    If automatic detection isn't working:

    1. In **Settings** → **Dictation**
    2. Change **Dictation Language** from "Automatic" to your specific language
    3. Try dictating again
  </Step>

  <Step title="Test Both Modes">
    Try both ways of voice input:

    * **Hold to speak**: Hold `Fn` (or your voice hotkey), speak, then release
    * **Click to dictate**: Click the mic icon once to start, click again to finish
  </Step>
</Steps>

## Did it work?

Try this quick test:

1. Hold your voice hotkey (default is `Fn`)
2. Say "Hello, this is a test"
3. Release the key
4. **Success:** You should see "Hello, this is a test" appear in the prompt box

<Tip>
  **Still having issues?** Try restarting Alter after granting permissions. Sometimes macOS needs a fresh start to recognize new permissions.
</Tip>

## Related help

* [Dictation settings](/how-to/settings-guide#dictation)
* [How to change voice hotkey](/how-to/change-hotkey)


# API Gateway Won't List Models
Source: https://docs.alterhq.com/common-issues/models-not-listed-in-api-gateway

Fix empty model lists when connecting external apps to Alter's API

<Note>
  **Using the API Gateway?** This lets you use Alter's models in other apps like SillyTavern, NovelCrafter, or your own code.
</Note>

## What's happening?

You're trying to connect another app to Alter's API, but:

* The app connects but shows no available models
* You have to manually type model names
* Model requests fail unless you specify the exact name

## Why this happens

Many AI apps expect OpenAI's simple model format (like `gpt-5`), but Alter supports multiple providers. So we use a special format to identify which provider each model comes from.

## The solution

<Card title="Model Format: Provider#Model-name" icon="hashtag">
  Instead of just `gpt-5`, use: `OpenAI#gpt-5`

  The format is always: **Provider name** + **#** + **Model name**
</Card>

## Setup steps

<Steps>
  <Step title="Get your API credentials">
    1. Open Alter → Settings (`Cmd + ,`)
    2. Go to the **Router** tab
    3. Click **Add New Key** to generate an API key
    4. Copy the key (starts with `sk-...`)
    5. Note the endpoint: `https://alterhq.com/api`
  </Step>

  <Step title="Configure your external app">
    In the app you're connecting:

    * **Base URL:** `https://alterhq.com/api` (or try `https://alterhq.com/api/v1`)
    * **API Key:** Your generated key from step 1
  </Step>

  <Step title="Manually set the model">
    Since automatic listing might not work, manually enter a model:

    | Provider | Model Name  | Full ID                        |
    | -------- | ----------- | ------------------------------ |
    | OpenAI   | GPT-5       | `OpenAI#gpt-5`                 |
    | OpenAI   | GPT-5 Nano  | `OpenAI#gpt-5-nano`            |
    | Claude   | Sonnet 4    | `Claude#claude-sonnet-4-6`     |
    | Gemini   | 2.5 Pro     | `Gemini#gemini-2.5-pro`        |
    | Mistral  | Large       | `Mistral#mistral-large-latest` |
    | Alter    | Best Router | `Alter#best`                   |
  </Step>
</Steps>

## Test the connection

Try this simple test:

1. Send a chat completion request with model `OpenAI#gpt-5-nano`
2. **Success:** You should get a response back through Alter

If it works with one model, it will work with all of them – just change the model ID!

<Tip>
  **Pro tip:** The Alter API works exactly like OpenAI's API. If your app supports "OpenAI-compatible" endpoints, it will work with Alter.
</Tip>

## Still having issues?

* Make sure you're using a valid Alter API key (not your provider's key)
* Try both endpoints: `/api` and `/api/v1`
* Some apps cache the model list – try restarting the app after setup

## Related help

* [API Gateway full guide](/api-router/api-gateway)
* [List of all available models](/how-to/choose-generative-model)


# Tools Not Working
Source: https://docs.alterhq.com/common-issues/tool-not-working

Fix integrations when Alter won't use your connected tools and apps

<Note>
  **Quick check:** Does your chosen AI model support tools? Some smaller models don't have tool-calling capabilities.
</Note>

## What's happening?

You ask Alter to do something like "Send a message to John" or "Add a calendar event," but:

* The AI responds with text instead of taking action
* Nothing happens in the target app
* You get "I don't have access to that" or similar responses

## Why this happens

<CardGroup>
  <Card title="Model Doesn't Support Tools" icon="brain">
    Some AI models can't call tools – they only generate text
  </Card>

  <Card title="Tool Not Enabled" icon="toggle-off">
    The tool is available but not turned on in Tools Manager
  </Card>

  <Card title="Wrong Prompt Format" icon="message">
    The AI needs clear instructions about what tool to use and how
  </Card>

  <Card title="Global Tools Toggle Off" icon="toggle-off">
    All tools are disabled via the global toggle in Active Tools
  </Card>
</CardGroup>

## Step-by-step fix

<Steps>
  <Step title="Switch to a tool-capable model">
    Not all models can use tools. Try one of these:

    * **Alter Best** (our smart router)
    * **Gemini 2.0 Flash**
    * **Claude Sonnet**
    * **GPT-5**

    Press `/` in the prompt box to switch models.
  </Step>

  <Step title="Check the global tools toggle">
    In the Tools Manager, there's a master switch that can disable **all** tools at once:

    1. Click the **three dots** in Alter → **Tools Manager**
    2. Look for the global toggle in the **Active Tools** section
    3. Make sure it's turned **on** (enabled)

    If this is off, none of your individual tools will work even if they're enabled.
  </Step>

  <Step title="Enable the right tools">
    Once the global toggle is on, enable specific tools:

    1. In the Tools Manager, find the tool you want (Messages, Calendar, etc.)
    2. Toggle it **on**
    3. Check if it needs additional setup (like signing in)
  </Step>

  <Step title="Be explicit in your request">
    Instead of: *"Tell John I'm running late"*

    Try: *"Send a message to John Smith saying 'I'm running 10 minutes late' using the Messages tool"*

    The more specific you are, the better the AI understands.
  </Step>

  <Step title="For Apple Shortcuts">
    If using Apple Shortcuts:

    1. Open the **Shortcuts** app
    2. Edit your shortcut
    3. Add "Receive input from" and set it to accept text
    4. Save the shortcut
    5. Try again in Alter
  </Step>
</Steps>

## Test it

Try this simple test:

1. Make sure you're using a tool-capable model
2. Enable the **System Notification** tool
3. Say: "Send a system notification saying 'Test successful'"
4. **Success:** You should see a macOS notification appear!

<Tip>
  **Start simple:** Test with basic tools like System Notification before trying complex integrations. This helps identify if it's a general tool issue or specific to one integration.
</Tip>

<Tip>
  **Try Flow:** If you're unsure which tool to use or having trouble with tool selection, enable [Flow](/workflows/use-flow-orchestration) - Alter's tool orchestrator that automatically selects the right tool for you.
</Tip>

## Still not working?

Some models are better at tools than others. If one model isn't working well with tools:

1. Switch to **Alter Best** (it automatically picks capable models)
2. Or try **Gemini 2.0 Flash** or **Claude Sonnet**

## Related help

* [Tool Manager Guide](/how-to/tool-manager-guide)
* [Integrations overview](/apps-tools/integrations-overview)


# Create reusable actions
Source: https://docs.alterhq.com/getting-started/actions-basics

Turn repeated prompts into reliable workflows with model and tool control

Use actions when you repeat the same task pattern and want consistent output quality.

## What an action gives you

<CardGroup>
  <Card title="Reusable prompts" icon="repeat">
    Run the same workflow without rewriting instructions each time.
  </Card>

  <Card title="Model choice" icon="brain">
    Assign the best model for each task.
  </Card>

  <Card title="Tool control" icon="sliders-horizontal">
    Enable only the tools needed for safer, faster runs.
  </Card>
</CardGroup>

## Create your first action

<Steps>
  <Step title="Open Action Editor">
    Open the Alter window menu and select **Action Editor**.
  </Step>

  <Step title="Create or duplicate">
    Create a new action, or duplicate a built-in action before customizing it.
  </Step>

  <Step title="Set clear instructions">
    Define one concrete outcome, such as weekly summary, release notes, or inbox triage.
  </Step>

  <Step title="Save and run">
    Test with one real input and refine wording if needed.
  </Step>
</Steps>

<Note>
  Built-in actions are read-only. Duplicate them to customize behavior.
</Note>

## Pick a model and tools per action

Use **Advanced** settings in the action to assign a model and tool access.

* Choose local models for sensitive tasks.
* Choose faster models for automation-heavy tasks.
* Start with minimal tools, then add only what your workflow needs.

## Related pages

* [Use workspaces for bigger tasks](/getting-started/workspaces-basics)
* [Automate with workspaces and actions](/getting-started/automate-with-workspaces-and-actions)
* [Use Tool Manager](/how-to/tool-manager-guide)


# Add files, folders, and media
Source: https://docs.alterhq.com/getting-started/add-files-and-media

Use drag and drop context for documents, images, audio, and code

Use this page to quickly ground Alter with the files and folders that matter for your task.

## Add context from Finder or apps

You can add content by dragging files or folders to the notch or The Hub. You can also use **Right click > Add to Alter**.

## Supported content

<CardGroup>
  <Card title="Documents" icon="file-text">
    `.xlsx`, `.docx`, `.pdf`, `.txt`, `.md`, `.org`, `.rtf`
  </Card>

  <Card title="Images" icon="image">
    `.jpg`, `.png`, `.heic`, `.gif`, `.tiff`, `.svg`
  </Card>

  <Card title="Web content" icon="globe">
    `.html`, URLs, and dragged text
  </Card>

  <Card title="Email" icon="mail">
    `.eml` and Apple Mail messages
  </Card>

  <Card title="Audio" icon="music">
    `.mp3`, `.wav`, `.m4a`, `.aac`, `.flac`
  </Card>

  <Card title="Code" icon="code">
    Source files, config files, and scripts
  </Card>
</CardGroup>

<Note>
  Alter supports directory drops, OCR for images and PDFs, and automatic text encoding detection.
</Note>

## Audio and video transcription

When you add audio or video, Alter starts transcription automatically.

<Steps>
  <Step title="Drop one or more files">
    Drag media files to the notch or The Hub.
  </Step>

  <Step title="Wait for processing">
    Transcription starts automatically.
  </Step>

  <Step title="Ask targeted questions">
    Try: "Summarize key decisions" or "List action items by owner."
  </Step>
</Steps>

<Warning>
  For image analysis, use a model with vision capability.
</Warning>

## Related pages

* [Use current app and Follow Mode](/getting-started/use-current-app-and-follow-mode)
* [Use workspaces for bigger tasks](/getting-started/workspaces-basics)
* [Capture voice and meetings](/getting-started/capture-voice-and-meetings)


# Automate with workspaces and actions
Source: https://docs.alterhq.com/getting-started/automate-with-workspaces-and-actions

Get repeatable results by combining persistent context and reusable actions

After your first successful tasks, this is the fastest way to level up.

## What this helps you do

Use Workspaces to keep large project context ready, then use Actions to repeat high-value tasks with consistent prompts.

<CardGroup>
  <Card title="Workspaces" icon="folder-tree">
    Keep project context ready so Alter can work across large file sets quickly.
  </Card>

  <Card title="Actions" icon="zap">
    Save reusable prompts for recurring tasks and consistent output quality.
  </Card>

  <Card title="Tool scope" icon="sliders-horizontal">
    Enable only needed tools per workflow for better reliability.
  </Card>
</CardGroup>

## Build your first repeatable workflow

<Steps>
  <Step title="Create one workspace">
    Add the folders and files for a single project you touch every week.
  </Step>

  <Step title="Create one action">
    Turn a recurring task into a reusable action (for example weekly summary or release notes).
  </Step>

  <Step title="Constrain tools">
    Enable only the tools needed for that action, then run the flow end to end.
  </Step>
</Steps>

<Tip>
  Start with one workspace and one action. Small, reliable automations scale better than large, generic setups.
</Tip>

## Related pages

* [Use workspaces for bigger tasks](/getting-started/workspaces-basics)
* [Create reusable actions](/getting-started/actions-basics)
* [Use Tool Manager](/how-to/tool-manager-guide)
* [Run your first workflows](/getting-started/first-workflows)
* [Tools Not Working](/common-issues/tool-not-working)


# Capture voice and meetings
Source: https://docs.alterhq.com/getting-started/capture-voice-and-meetings

Use dictation, transcription, and meeting workflows from day one

Alter can capture meetings automatically, not only from files you drop manually.

<Info>
  For most users, the default workflow is: join meeting -> Alter detects it -> record -> get transcript and follow-up items.
</Info>

## What you can do from day one

<CardGroup>
  <Card title="Speak to Alter" icon="mic">
    Dictate prompts for fast commands, drafts, and follow-up requests.
  </Card>

  <Card title="Auto-detect meetings" icon="radar">
    Alter detects common meeting apps and prompts you to record.
  </Card>

  <Card title="Generate outcomes" icon="clipboard-check">
    Turn transcripts into summaries, decisions, and action items.
  </Card>
</CardGroup>

## How meeting capture works

<Steps>
  <Step title="Join a meeting">
    When Alter detects a meeting, it shows a prompt to record or skip.
  </Step>

  <Step title="Record automatically or manually">
    Enable auto-record in settings, or start/stop recording yourself from the mic control.
  </Step>

  <Step title="Ask for structured follow-up">
    Ask Alter for summary, decisions, open questions, and action items with owners.
  </Step>
</Steps>

## Common first prompts

* "Summarize this meeting in 5 bullets."
* "Extract action items with owner and due date."
* "What decisions were made, and what is still unresolved?"
* "Give me a follow-up email draft based on this meeting."

<Tip>
  Dropping audio/video files is still useful for external recordings, but it is not required for normal meeting transcription inside Alter.
</Tip>

## Related pages

* [Run your first workflows](/getting-started/first-workflows)
* [Never miss action items from meetings](/workflows/meeting-workflow)
* [How to access settings](/how-to/settings-guide)
* [Mic not transcribing](/common-issues/mic-not-transcribing)


# Core features
Source: https://docs.alterhq.com/getting-started/core-features

Overview of app context, files, workspaces, and actions with links to focused getting-started pages

This page is the feature map. For setup and hands-on steps, use the linked getting-started pages.

## Interacting with Your Apps

### AppSense - Understanding Your Mac

AppSense reads data directly from macOS apps so Alter can work with more than what is visible on screen.

Use this focused guide:

* [Use current app and Follow Mode](/getting-started/use-current-app-and-follow-mode)

## Follow Mode

Follow Mode keeps your context in sync while you continue working, so follow-up answers stay grounded.

Use this focused guide:

* [Use current app and Follow Mode](/getting-started/use-current-app-and-follow-mode)

## Interacting with Files and Folders

You can drag files and folders to Alter, add content from apps, and ask grounded questions about that material.

Use this focused guide:

* [Add files, folders, and media](/getting-started/add-files-and-media)

## Workspaces

Workspaces keep larger context indexed and ready so you can run repeatable tasks across bigger file sets.

Use this focused guide:

* [Use workspaces for bigger tasks](/getting-started/workspaces-basics)

## Alter Actions - Workflows

Actions let you save and reuse high-value prompt workflows with model and tool controls.

Use this focused guide:

* [Create reusable actions](/getting-started/actions-basics)

## Suggested learning path

1. [Open Alter](/getting-started/open-alter)
2. [Use current app and Follow Mode](/getting-started/use-current-app-and-follow-mode)
3. [Add files, folders, and media](/getting-started/add-files-and-media)
4. [Use workspaces for bigger tasks](/getting-started/workspaces-basics)
5. [Create reusable actions](/getting-started/actions-basics)


# Run Your First Workflows
Source: https://docs.alterhq.com/getting-started/first-workflows

Use practical workflows for writing, meetings, and everyday tasks

This page is your bridge from setup to real outcomes. Pick one workflow below, run it once end to end, then keep the one that saves you the most time.

## Choose a workflow by goal

<CardGroup>
  <Card title="Communication" icon="messages-square" href="/workflows/manage-mail-with-alter">
    Start with unread mail + draft reply, or send a quick iMessage.
  </Card>

  <Card title="Planning" icon="calendar" href="/workflows/manage-calendar-with-alter">
    Plan your day, add meetings, and route to places quickly.
  </Card>

  <Card title="Capture and knowledge" icon="notebook-pen" href="/workflows/manage-notes-with-alter">
    Turn conversation into notes, summaries, and reusable knowledge.
  </Card>

  <Card title="Execution" icon="check-square" href="/workflows/manage-reminders-with-alter">
    Convert decisions into reminders and close the loop on tasks.
  </Card>
</CardGroup>

## 10-minute first run

<Steps>
  <Step title="Pick one workflow only">
    Start with one high-frequency job (for most users: Calendar, Notes, or Reminders).
  </Step>

  <Step title="Run one real prompt">
    Use the copy/paste prompts from that workflow page and execute one real action.
  </Step>

  <Step title="Save your winning pattern">
    Keep the prompt style that worked, then repeat it in your next session.
  </Step>
</Steps>

## Recommended first pages

* [Manage your schedule](/workflows/manage-calendar-with-alter)
* [Capture and organize notes](/workflows/manage-notes-with-alter)
* [Stay on top of tasks](/workflows/manage-reminders-with-alter)
* [Never miss action items from meetings](/workflows/meeting-workflow)

<Tip>
  If a workflow does not trigger the expected tool action, open [Use Tool Manager](/how-to/tool-manager-guide) and verify only the relevant tools are enabled.
</Tip>


# Getting Started
Source: https://docs.alterhq.com/getting-started/getting-started-path

Learn the different ways to open and interact with Alter on your Mac

<Info>
  **New to Alter?** This guide covers the three main ways to open and use Alter on your Mac.
</Info>

## Three Ways to Open Alter

<CardGroup>
  <Card title="The Notch" icon="computer-mouse">
    Hover over your Mac's camera notch
  </Card>

  <Card title="Keyboard Shortcut" icon="keyboard">
    Press `Alt + Space` (or your custom hotkey)
  </Card>

  <Card title="Voice Command" icon="microphone">
    Hold `Fn` key and speak
  </Card>
</CardGroup>

***

### The Notch

The easiest way to open Alter is to hover your mouse over the camera notch at the top of your screen.

<Frame>
  ![Open Alter by hovering over the notch](https://hackmd.io/_uploads/rkBSeIydJg.gif)
</Frame>

<Tip>
  **External monitors:** On an external screen, you can hover anywhere on the top bar except directly on the mic icon.
</Tip>

***

### Hotkey - Alter Quick Menu

Press your keyboard shortcut to open Alter instantly from any app.

<Steps>
  <Step title="Use the default shortcut">
    Press `Alt + Space` to open the quick menu
  </Step>

  <Step title="Or use your custom hotkey">
    If you've changed it in settings, use your configured combination
  </Step>
</Steps>

<Note>
  **Customize your shortcut:** Go to **Settings > General > Quick Access** to change the hotkey to something else.
</Note>

***

### Voice Command

Control Alter hands-free using your voice.

<AccordionGroup>
  <Accordion icon="message-circle" title="Speech-to-Prompt (Hold to Speak)">
    Perfect for quick commands and questions:

    1. **Hold** the mic icon or press and hold your voice hotkey (default: `Fn`)
    2. **Speak** your prompt naturally
    3. **Release** to send immediately

    <Frame>
      ![Hold to speak demonstration](https://hackmd.io/_uploads/ry2fML1dJe.gif)
    </Frame>

    <Tip>
      The currently active window is automatically selected as context when you use speech-to-prompt.
    </Tip>
  </Accordion>

  <Accordion icon="mic" title="Dictate Mode (Click to Start/Stop)">
    Best for longer text input:

    1. **Click once** on the mic icon to start recording
    2. **Speak** your content
    3. **Click again** to stop and process

    <Info>
      Your transcript appears in the context section of Alter, ready to be sent as a prompt or edited.
    </Info>
  </Accordion>
</AccordionGroup>

<Note>
  **Configure voice settings:** Go to **Settings > Dictation > Shortcut** to customize your voice hotkey.
</Note>

***

## Mouse Interaction

### Text Selection

Select any text on your Mac to instantly invoke the **Alter Floating Menu**.

<Card title="Floating Menu Features" icon="menu">
  * Shows system Alter actions
  * Favorite actions appear at the top
  * Quick access to common operations
</Card>

### Right-Click Menu

Right-click on any file or folder and select **Add to Alter** to send it as context.

<Steps>
  <Step title="Find your file">
    Locate the file or folder in Finder
  </Step>

  <Step title="Right-click">
    Open the context menu
  </Step>

  <Step title="Select 'Add to Alter'">
    The file appears in your context section
  </Step>
</Steps>

***

## What's Next?

Now that you know how to open Alter, explore these guides:

<CardGroup>
  <Card title="Core Features" icon="sparkles" href="/getting-started/core-features">
    Discover AppSense, Follow Mode, Workspaces, and Actions
  </Card>

  <Card title="Window Types" icon="window" href="/getting-started/window-types-notch-hub-panels">
    Learn about the Hub and Quick Panel interfaces
  </Card>

  <Card title="Use Flow" icon="wand-magic-sparkles" href="/workflows/use-flow-orchestration">
    Set up intelligent tool orchestration and improve accuracy
  </Card>

  <Card title="Best Context Habits" icon="compress" href="/how-to/managing-context-window">
    Learn how to keep conversations fast and reliable
  </Card>
</CardGroup>


# Open Alter
Source: https://docs.alterhq.com/getting-started/open-alter

Learn the fastest ways to open Alter and send your first prompt

## Open Alter in three ways

Use whichever feels most natural:

* **Notch:** Hover over your Mac's notch
* **Shortcut:** Press your quick menu shortcut
* **Voice:** Hold your voice key and speak

<Tip>
  If this is your first time, start with the notch. It is the easiest option.
</Tip>

## Send your first prompt

1. Open Alter
2. Type a simple request like "Summarize my notes"
3. Press Enter

## Learn more

* [Getting Started guide](/getting-started/getting-started-path)
* [How to open Alter](/getting-started/open-alter)
* [Dictation guide](/workflows/dictation)


# Understand context and app awareness
Source: https://docs.alterhq.com/getting-started/understand-context-and-apps

Learn how Alter uses app context, follow mode, and files to give better answers

Alter works best when it understands what you are currently working on.

## Why context matters

When Alter sees the right context, answers become faster and more specific. You spend less time re-explaining your screen and more time making progress.

<CardGroup>
  <Card title="Current app" icon="app-window">
    Add your active app to get context-aware help on what you are looking at right now.
  </Card>

  <Card title="Follow Mode" icon="refresh-cw">
    Keep context synchronized while you edit files, documents, or pages.
  </Card>

  <Card title="Files and folders" icon="folder-open">
    Drag and drop project material for grounded answers and edits.
  </Card>
</CardGroup>

## Try it in 60 seconds

<Steps>
  <Step title="Start from your active app">
    Open any app, add **Current Application**, then ask: "Summarize what I am viewing and suggest next steps."
  </Step>

  <Step title="Turn on continuous context">
    Keep editing while chatting and ask: "What changed since the previous version?"
  </Step>

  <Step title="Add supporting files">
    Drag a related file or folder into Alter and ask for a concrete output (rewrite, summary, checklist, or edit plan).
  </Step>
</Steps>

<Tip>
  For best results, combine one app context with only the files needed for the task. Smaller, focused context usually gives better answers.
</Tip>

## Related pages

* [Use current app and Follow Mode](/getting-started/use-current-app-and-follow-mode)
* [Your workspace](/getting-started/your-workspace)
* [Run your first workflows](/getting-started/first-workflows)
* [Use Tool Manager](/how-to/tool-manager-guide)


# Use current app and Follow Mode
Source: https://docs.alterhq.com/getting-started/use-current-app-and-follow-mode

Keep app context synced so Alter can help without repeated explanations

Use this page when you want Alter to stay aligned with what you are actively doing in an app.

## What this does

Current app adds your active window as context. Follow Mode keeps that context updated as you keep working.

<CardGroup>
  <Card title="Current app" icon="app-window">
    Add your active app in one click when Alter suggests **Current Application**.
  </Card>

  <Card title="Follow Mode" icon="refresh-cw">
    Keep updates synchronized across turns while you edit and ask follow-up questions.
  </Card>
</CardGroup>

## Start in under a minute

<Steps>
  <Step title="Add your active app">
    Open Alter and click **Current Application** under the prompt box. You can also press `Down Arrow`, then `Enter`.
  </Step>

  <Step title="Ask a grounded first prompt">
    Try: "Summarize what I am looking at and suggest the next three actions."
  </Step>

  <Step title="Keep editing and ask again">
    Make a small change in the app, then ask: "What changed since your previous summary?"
  </Step>
</Steps>

## Best practices

* Keep one app in context when possible for clearer answers.
* Ask follow-up questions instead of re-describing your screen.
* If results drift, remove context and re-add your current app.

## Related pages

* [Understand context and app awareness](/getting-started/understand-context-and-apps)
* [Add files, folders, and media](/getting-started/add-files-and-media)
* [Run your first workflows](/getting-started/first-workflows)


# Window Types: Notch, Hub, and Panels
Source: https://docs.alterhq.com/getting-started/window-types-notch-hub-panels

Understand Alter's interface modes, including Notch interactions, The Hub, and the Quick Panel

<Info>
  **Two interfaces, one powerful experience.** Use the Quick Panel for fast interactions and The Hub for deep work.
</Info>

## Two Ways to Interact

<CardGroup>
  <Card title="The Hub" icon="layout">
    Full workspace with tabs, sidebar, and comprehensive management
  </Card>

  <Card title="Quick Panel" icon="message-square">
    Lightweight floating panel for quick queries and voice commands
  </Card>
</CardGroup>

***

### General Concept

Alter provides two main interfaces for interacting with AI:

<AccordionGroup>
  <Accordion icon="layout-dashboard" title="The Hub">
    The main window interface with tabs, sidebar, and comprehensive workspace management. Best for:

    * Extended conversations
    * Workspace management
    * Multi-tasking with multiple contexts
    * Reviewing meeting transcripts
  </Accordion>

  <Accordion icon="message-circle" title="Quick Panel">
    The lightweight floating panel accessible from the notch or hotkey. Perfect for:

    * Quick queries
    * Voice commands
    * Fast context additions
    * Rapid interactions
  </Accordion>
</AccordionGroup>

***

## Hub Interface

<Frame>
  The Hub is divided into three main sections:

  1. **Sidebar** - Navigation for conversations, workspaces, transcripts, and more
  2. **Main Content Area** - Tabbed interface showing active content
  3. **Input Area** - Prompt box and context management
</Frame>

### Opening The Hub

<Steps>
  <Step title="Keyboard shortcut">
    Press `Shift + Cmd + H`
  </Step>

  <Step title="Menu bar">
    Select "Open The Hub" from the Alter menu bar icon
  </Step>

  <Step title="From a conversation">
    Open a conversation link from a floating panel
  </Step>
</Steps>

### Tab Types

<CardGroup>
  <Card title="Conversations" icon="message-square">
    Chat sessions with AI models
  </Card>

  <Card title="Workspaces" icon="folder-open">
    Collections of files, folders, and apps
  </Card>

  <Card title="Transcripts" icon="file-audio">
    Meeting transcriptions and recordings
  </Card>

  <Card title="Calendar Events" icon="calendar">
    Scheduled meetings and events
  </Card>

  <Card title="Scheduled Jobs" icon="clock">
    Automated tasks and workflows
  </Card>
</CardGroup>

### Keyboard Shortcuts

| Shortcut           | Action                     |
| ------------------ | -------------------------- |
| `Cmd + B`          | Toggle sidebar visibility  |
| `Cmd + W`          | Close active tab           |
| `Cmd + Option + →` | Next tab                   |
| `Cmd + Option + ←` | Previous tab               |
| `Cmd + K`          | Clear all contexts         |
| `Cmd + Delete`     | Delete active conversation |

### Managing Contexts

<Steps>
  <Step title="Add context">
    Drag and drop files, or use `@` in the prompt box
  </Step>

  <Step title="Navigate">
    Use arrow keys to move between contexts
  </Step>

  <Step title="Clear">
    Press `Cmd + K` to remove all contexts
  </Step>
</Steps>

### Inspector Panel

<CardGroup>
  <Card title="Conversation Details" icon="info">
    Metadata, export options, sharing links
  </Card>

  <Card title="Context Management" icon="layers">
    See all contexts in current conversation
  </Card>

  <Card title="Workspace Info" icon="folder">
    Statistics, files, and settings
  </Card>
</CardGroup>

Toggle the Inspector using the sidebar icon or inspector button.

***

## Quick Panel Interface

The Quick Panel (accessible from the notch) is divided into three sections:

<CardGroup>
  <Card title="1. Context" icon="layers">
    Your selected files, apps, and references
  </Card>

  <Card title="2. Prompt" icon="edit">
    Where you type or speak your request
  </Card>

  <Card title="3. Additional Selection" icon="plus">
    Quick access to models and actions
  </Card>
</CardGroup>

### Navigation

Use keyboard shortcuts in the Quick Panel:

* `←`, `↑`, `→`, `↓` - Navigate between objects
* `Enter` - Select an object
* `@` - Add elements to context
* `#` - Show conversation history
* `>` - Show meeting history
* `/` - List and choose model
* `?` - Show help menu

<Note>
  See the **Prompt Box** section below for more keyboard shortcuts.
</Note>

***

## The Context Section

The **Context** section displays elements sent to Alter for reference.

<CardGroup>
  <Card title="Files" icon="file">
    Documents, images, audio files
  </Card>

  <Card title="Text Selection" icon="text">
    Selected text from any app
  </Card>

  <Card title="Transcripts" icon="headphones">
    Audio and YouTube transcripts
  </Card>

  <Card title="Folders" icon="folder">
    Entire directories
  </Card>

  <Card title="Workspaces" icon="briefcase">
    Saved workspace collections
  </Card>

  <Card title="Applications" icon="app-window">
    Current app context
  </Card>

  <Card title="Web Pages" icon="globe">
    URLs and web content
  </Card>
</CardGroup>

### Keyboard Navigation

| Key             | Action              |
| --------------- | ------------------- |
| `←` `↑` `→` `↓` | Navigate contexts   |
| `Space`         | Add/remove selected |
| `Cmd + K`       | Remove all contexts |

### Using Your Clipboard

Paste content directly: `Cmd + V`

Your clipboard content is automatically added to Alter's context.

***

## The Prompt Box

The **Prompt Box** is where the magic happens.

<Frame>
  Start typing your prompt or an Alter Action title to send it to your AI model.
</Frame>

### Keyboard Shortcuts

| Shortcut        | Action                             |
| --------------- | ---------------------------------- |
| `Enter`         | Send prompt with active model      |
| `Cmd + Enter`   | Search the web (via Gemini)        |
| `Shift + Enter` | New line                           |
| `@`             | Add elements to context            |
| `#`             | Show conversation history          |
| `>`             | Show meeting transcription history |
| `/`             | List and choose model              |
| `?`             | Show help menu                     |

<Tip>
  **Invoke Actions:** Type any character in an Action's title to trigger it!
</Tip>

### Help Menu

<Frame>
  ![Help menu](https://beehiiv-images-production.s3.amazonaws.com/uploads/asset/file/5c14ac40-d9bd-4912-bf57-85f853ad441d/image.png?t=1741473617)
</Frame>

Press `?` in the prompt box to see all available shortcuts.

***

## Conversation Windows

### Resizing Windows

Customize conversation window size for your workflow:

<CardGroup>
  <Card title="Width" icon="move-horizontal">
    Drag edges horizontally to resize
  </Card>

  <Card title="Height" icon="move-vertical">
    Drag edges vertically to resize
  </Card>

  <Card title="Layout" icon="layout">
    Fit alongside other applications
  </Card>

  <Card title="Persistent" icon="save">
    Size is remembered for future sessions
  </Card>
</CardGroup>

<Info>
  **Useful for:** Side-by-side work, reviewing long documents, screen sharing, different display setups
</Info>

### Continuous Speech-to-Prompt

Have extended voice conversations without touching your keyboard:

<Steps>
  <Step title="Hold voice hotkey">
    Press and hold `Fn` (or your configured key)
  </Step>

  <Step title="Speak naturally">
    Say your prompt out loud
  </Step>

  <Step title="Release">
    Let go to send to conversation
  </Step>

  <Step title="Keep going">
    Each voice prompt adds to the same thread
  </Step>
</Steps>

<Tip>
  **Hands-free workflow:** Perfect for brainstorming, dictation, or when your hands are busy.
</Tip>

***

## Conversation History

### Managing Chat History

Access history by typing `#` in the prompt box or using The Hub's sidebar.

<Frame>
  <img alt="History with tags" />
</Frame>

### Organizing with Tags

Add tags like `#personal` to categorize chats:

```
# #personal #food
```

Search for conversations matching multiple tags.

### Renaming Conversations

<Steps>
  <Step title="Right-click">
    Right-click any conversation in the list
  </Step>

  <Step title="Select Rename">
    Choose `Rename` from the menu
  </Step>

  <Step title="Type new name">
    Give it a descriptive name
  </Step>
</Steps>

### Exporting Conversations

Export as markdown for documentation or sharing:

<Steps>
  <Step title="Find conversation">
    Locate it in the history
  </Step>

  <Step title="Right-click">
    Open the context menu
  </Step>

  <Step title="Select Export">
    Choose the Export option
  </Step>

  <Step title="Save">
    Choose location and save as .md file
  </Step>
</Steps>

<Card title="Export Uses" icon="download">
  * Documentation
  * Sharing with team
  * Archiving important discussions
  * Using in other tools
</Card>

***

## Related Resources

<CardGroup>
  <Card title="Core Features" icon="sparkles" href="/getting-started/core-features">
    Workspaces, Actions, and more
  </Card>

  <Card title="Keyboard Shortcuts" icon="keyboard" href="/references/shortcuts">
    Complete shortcut reference
  </Card>
</CardGroup>


# Use workspaces for bigger tasks
Source: https://docs.alterhq.com/getting-started/workspaces-basics

Index folders and files once so Alter can work across larger contexts

Use workspaces when one-off file drops are not enough and you need persistent context.

## Why use workspaces

<CardGroup>
  <Card title="Faster responses" icon="zap">
    Keep relevant context indexed and ready.
  </Card>

  <Card title="Lower cost" icon="credit-card">
    Send focused context instead of large raw inputs every time.
  </Card>

  <Card title="Large folders" icon="folder-open">
    Work with bigger codebases and document sets.
  </Card>
</CardGroup>

## Create your first workspace

<Steps>
  <Step title="Open The Hub">
    Press `Shift + Cmd + H`.
  </Step>

  <Step title="Go to Workspaces">
    Open the Workspaces section in the sidebar.
  </Step>

  <Step title="Create workspace">
    Click `+` in the workspace picker.
  </Step>

  <Step title="Add files and folders">
    Add only the resources needed for one workflow you run often.
  </Step>
</Steps>

## How files are prepared

| File type   | Conversion                 |
| ----------- | -------------------------- |
| PDFs        | Markdown with page markers |
| DOCX        | Markdown                   |
| XLSX        | Markdown or CSV            |
| Images      | OCR text extraction        |
| Directories | Recursive processing       |

<Note>
  Audio and video files are not supported directly in workspaces. Transcribe them first by dropping them into Alter.
</Note>

## Local storage

Workspace data is stored locally in:

```text theme={null}
~/Library/Application Support/Alter/Workspaces/
```

## Related pages

* [Automate with workspaces and actions](/getting-started/automate-with-workspaces-and-actions)
* [Create reusable actions](/getting-started/actions-basics)
* [Use Tool Manager](/how-to/tool-manager-guide)


# Understand the Interface
Source: https://docs.alterhq.com/getting-started/your-workspace

Get comfortable with the Alter window, context area, and chat flow

## What you see in Alter

The main interface has three core parts:

* **Prompt box:** Where you type or dictate
* **Context area:** Files, apps, and data sent with your request
* **Conversation:** Responses and tool actions

## Why context matters

Good context gives better answers. Add only what is relevant to your current task.

<Note>
  If responses get slower, reduce context and start a fresh conversation.
</Note>

## Learn more

* [Window Types: Notch, Hub, and Panels](/getting-started/window-types-notch-hub-panels)
* [Managing Context Window](/how-to/managing-context-window)
* [How to add context](/how-to/add-context)


# How-To: Change Quick Access Hotkey
Source: https://docs.alterhq.com/how-to/change-hotkey

Customize your keyboard shortcut for opening Alter

## Steps

1. Open settings with `Cmd+,`.
2. Go to Defaults.
3. Click Quick access hotkey and press new keys.

<img alt="Defaults" />

## Related Docs

* [How to access settings](/how-to/settings-guide)


# Choose your generative model
Source: https://docs.alterhq.com/how-to/choose-generative-model

Pick the right model for speed, quality, vision, and privacy in Alter

Use this when you want better results for a specific task, not just the default model.

## Quick model selection in chat

<Steps>
  <Step title="Open model picker">
    In Alter, type `/` to open the model list.
  </Step>

  <Step title="Choose the model">
    Select a model based on your task type, then send your prompt.
  </Step>

  <Step title="Favorite frequent models">
    Click the star next to a model to pin it for faster access.
  </Step>
</Steps>

## Set your default model

Use `/` to pick a model. The selected model becomes your default model immediately and stays active until you choose another one.

## Practical model choices

* Use a fast model for short daily tasks.
* Use a stronger reasoning model for complex planning or coding.
* Use a vision-capable model when you add images.
* Use local or custom models when privacy requirements are stricter.

<Tip>
  If you are unsure, start with `/best`, then switch only when you need lower latency or a specific capability.
</Tip>

## Related pages

* [Use your own API key](/how-to/use-byok)
* [API model names](/references/api-model-names)
* [API Gateway guide](/api-router/api-gateway)


# Choosing your language
Source: https://docs.alterhq.com/how-to/choose-language

Set your preferred language for AI generation output

You can choose your generation language in the settings panel

**Settings > Profile > Generation Language**

![Settings Generation Language](https://beehiiv-images-production.s3.amazonaws.com/uploads/asset/file/cecd74bb-f332-4c17-a8e1-f71cb35cabff/Alter_Settings_Profile.png?t=1740500288)


# Manage context window
Source: https://docs.alterhq.com/how-to/managing-context-window

Optimize your AI interactions by understanding and managing context window usage

<Info>
  The **context window** is the amount of text an AI model can process in a single conversation. Think of it as the model's working memory — it includes your messages, file contents, tool definitions, and the AI's responses.
</Info>

## Why Context Window Matters

Every interaction with AI consumes context space. When your context window fills up:

<CardGroup>
  <Card title="Performance Slows Down" icon="gauge">
    Larger payloads take longer to process, increasing response times
  </Card>

  <Card title="Fair Use Budget Depletes" icon="scale-balanced">
    More tokens per request consumes your fair use policy budget faster
  </Card>

  <Card title="Context Gets Truncated" icon="scissors">
    Older messages may be dropped, causing the AI to "forget" earlier parts of the conversation
  </Card>
</CardGroup>

Understanding how to manage your context window helps you get better performance and more value from Alter.

***

## What Consumes Context Space

### 1. Conversation History

Every message you send and every response you receive stays in context. Long conversations naturally consume more space.

### 2. File Contents

When you attach files or folders, their entire contents are injected into the context:

* **Text files** — Full content is included
* **Code files** — Entire file contents are sent
* **Documents** — Parsed text is included
* **Images** — Descriptions or OCR text is added

### 3. Tool Definitions

Every enabled tool consumes context space. A tool definition includes:

* Tool name and description
* Required and optional parameters
* Parameter descriptions and types

<Warning>
  **Tools are the silent context consumer.** Enabling 10+ tools can easily consume 30-50% of your context window before you even start typing.
</Warning>

### 4. System Instructions

Background prompts, grounding documents, and system instructions all consume space.

***

## How Tools Consume Context

Here's a real example of how tools impact your context:

| Tools Enabled | Approximate Context Used | Remaining for Your Content |
| ------------- | ------------------------ | -------------------------- |
| 0 tools       | \~5%                     | \~95%                      |
| 5 tools       | \~15%                    | \~85%                      |
| 10 tools      | \~30%                    | \~70%                      |
| 20 tools      | \~50%                    | \~50%                      |
| 30+ tools     | \~70%+                   | \~30%                      |

<Note>
  These are approximate values. Actual usage varies based on tool complexity and description length.
</Note>

***

## Strategies for Managing Context

### 1. Use Flow for Tool Orchestration (Recommended)

The most effective way to reduce tool-related context consumption is to use **Flow** — Alter's built-in tool orchestrator.

<Card title="Flow loads as a single tool" icon="wand-magic-sparkles" href="/workflows/use-flow-orchestration">
  Instead of loading all your enabled tools into every request, Flow acts as one tool that intelligently selects and orchestrates the right tools for each task.

  **Benefits:**

  * Reduces context usage by 60-80%
  * Improves response times
  * Automatically handles multi-step tasks
  * Saves fair use budget
</Card>

**Best Practice:** Configure your default "Ask Anything" action to use only Flow instead of all enabled tools.

### 2. Disable Unused Tools

Only enable tools you actively use:

<Steps>
  <Step title="Review your tools">
    Go to **Settings > Tool Manager** and see what's enabled
  </Step>

  <Step title="Disable unused tools">
    Toggle off tools you haven't used in the past week
  </Step>

  <Step title="Re-enable when needed">
    You can always re-enable tools — they remember your authentication
  </Step>
</Steps>

### 3. Customize Tool Sets for Actions

Every action can be configured with its own specific tools. This is a powerful way to control context usage:

#### Ask Anything Action

The **Ask Anything** action is the default used when you type in the prompt box without selecting a specific action. It runs everywhere in Alter — minimize your tool selection here for maximum impact.

<Steps>
  <Step title="Open Action Editor">
    Go to **Settings > Actions**
  </Step>

  <Step title="Find Ask Anything">
    Select the "Ask Anything" action
  </Step>

  <Step title="Click Advanced">
    Expand the Advanced section
  </Step>

  <Step title="Limit Tools">
    Select only the tools you absolutely need (or just Flow)
  </Step>
</Steps>

#### Custom Actions

When creating custom actions, think carefully about which tools are actually needed:

<CardGroup>
  <Card title="Learn from Defaults" icon="book-open">
    Most built-in Alter actions have tools disabled by default. For example, "Correct Grammar" doesn't need any tools — it's a pure text transformation.
  </Card>

  <Card title="Be Minimal" icon="filter">
    Only enable tools your specific workflow requires. If your action just formats text, you probably don't need any tools.
  </Card>
</CardGroup>

#### Flow vs Specific Tools

<Info>
  **Use Flow** when you want flexibility and don't know which specific tools you'll need. It handles tool selection automatically.
</Info>

<Info>
  **Use specific tools** when you know exactly which tools your workflow needs. This gives better performance and fewer back-and-forth turns with the AI.
</Info>

**Example:** If you're building an action that just creates calendar events, enable only the Calendar tool rather than Flow. This eliminates the tool selection step and executes faster.

### 4. Use Workspaces for Large Files

Instead of attaching large files to every conversation:

* Create a **workspace** for projects with large files
* Reference the workspace when needed
* Clear workspace context when switching tasks

<Card title="Learn about Workspaces" icon="folder-open" href="/getting-started/core-features#workspaces">
  Workspaces help organize files and manage context more efficiently
</Card>

### 4. Clear Context Regularly

Use **⌘ K** (Command + K) to clear all contexts when:

* Starting a new, unrelated task
* Previous context is no longer relevant
* Responses are getting slow

### 5. Summarize Long Conversations

For very long conversations:

* Export the conversation to a file
* Start a new conversation with a summary
* Reference the exported file if needed

### 6. Be Selective with File Attachments

Instead of attaching entire folders:

* Attach only the specific files you need
* Remove files from context when done with them

***

## Monitoring Context Usage

While Alter doesn't show a real-time context meter, you can monitor usage indirectly:

<CardGroup>
  <Card title="Watch Response Times" icon="clock">
    Slower responses often indicate high context usage
  </Card>

  <Card title="Check Tool Count" icon="toolbox">
    More enabled tools = more context consumed. Review Tool Manager regularly.
  </Card>
</CardGroup>

***

## Quick Wins Checklist

<Steps>
  <Step title="Enable Flow" icon="check">
    Configure "Ask Anything" to use only Flow instead of all tools
  </Step>

  <Step title="Customize Actions" icon="check">
    Set specific tools for custom actions — disable tools you don't need
  </Step>

  <Step title="Audit Tools" icon="check">
    Disable tools you haven't used recently
  </Step>

  <Step title="Use Workspaces" icon="check">
    Organize large projects in workspaces instead of attaching files ad-hoc
  </Step>

  <Step title="Clear Context" icon="check">
    Press **⌘ K** when starting new tasks
  </Step>
</Steps>

***

## Related Docs

<CardGroup>
  <Card title="Use Flow for Tool Orchestration" icon="wand-magic-sparkles" href="/workflows/use-flow-orchestration">
    The best way to reduce tool-related context usage
  </Card>

  <Card title="Manage tools" icon="toolbox" href="/how-to/tool-manager-guide">
    Learn how to manage your tool integrations
  </Card>

  <Card title="Workspaces" icon="folder-open" href="/getting-started/core-features#workspaces">
    Organize files and manage context efficiently
  </Card>
</CardGroup>


# Reinstall or downgrade Alter safely
Source: https://docs.alterhq.com/how-to/reinstall-or-downgrade-alter

Replace Alter with another version without removing your local chats, transcripts, and other app data.

Use this process when Alter is acting up or when you want to install an older version.

<Warning>
  Do not use uninstall cleaners such as CleanMyMac before reinstalling. They can remove Alter's local data.
</Warning>

## Safe way to reinstall or downgrade

<Steps>
  <Step title="Download the version you want">
    Go to [alterhq.com/changelog](https://alterhq.com/changelog) and download the release you want to install.
  </Step>

  <Step title="Quit Alter">
    Fully quit the app before replacing it.
  </Step>

  <Step title="Replace the app in Applications">
    Drag the downloaded Alter app into your `Applications` folder and choose **Replace**.
  </Step>

  <Step title="Open Alter again">
    Launch Alter and confirm your existing chats, transcripts, and settings are still there.
  </Step>
</Steps>

## Why this works

Replacing the app updates the application bundle. It does not do a cleanup pass over your local support files.

## What not to do

* Do not drag Alter to the trash if you are trying to keep your data
* Do not use CleanMyMac or similar uninstall tools unless you want a full removal
* Do not assume reinstalling will restore data from the cloud later

## If you need a true clean uninstall

Back up your local Alter data first. Alter does not keep a cloud copy of your chat history or transcripts for restore.

See [Local data and privacy](/references/local-data-and-privacy).


# Configuring Alter Settings
Source: https://docs.alterhq.com/how-to/settings-guide

Learn how to customize Alter to match your preferences and manage your account

## Goal

Learn how to customize Alter to match your preferences, manage your account, configure AI models, and set up permissions for optimal productivity.

## Steps

### 1. Access Settings

There are three ways to open Settings:

**Option 1: Menu Bar**
Click the Alter icon in the menu bar and select **Settings...** from the dropdown menu.

**Option 2: Keyboard Shortcut**
Press **⌘ , (Command + Comma)** to open Settings directly.

**Option 3: Notch Menu**
Click the three-dot menu icon (⋮) in the Alter notch and select **Settings**.

<img alt="Menu Bar Access" />

### General Settings

In the **General** tab, you can configure core functionality and quick access options:

**Quick Access**

* **Open notch**: Enable keyboard shortcut to open the notch from anywhere on your screen
* **Open or Focus the Hub**: Quickly switch to or launch the Alter Hub window (⌘ ⌥ H)
* **New Hub Chat**: Start a fresh conversation session in the Hub (⌘ Space)
* **Selection Button**: Show a quick action button accessible from anywhere

**LLM Settings**

* **Max Tokens**: Set the maximum length of AI responses
* **Temperature**: Control response creativity and variation (0.0 = deterministic, 1.0 = creative; default: 0.70)

**Notifications**

* **Summarize YouTube video**: Automatically create summaries when you  visit YouTube videos
* **Record to transcript**: Automatically transcribe recordings to your notes (go to Notes settings for more options)

<img alt="General Settings" />

### 2. Voice Settings

The **Voice** tab controls how Alter processes and responds to audio:

**General Configuration**

* **Audio behavior during dictation**: Control how system audio is handled while dictating. Options include ducking (reduce volume) or silencing audio completely to minimize interruptions
* **Keep awake during meeting**: Prevent your Mac from sleeping or entering power-saving mode during meeting recordings, ensuring uninterrupted transcription
* **Play chime when starting recording**: Receive an audio alert when you begin dictation or meeting recording

**Language & Vocabulary**

* **Dictation language**: Select your preferred language for voice input
* **Personal Dictionary**: Add custom terms and transcription replacements
* **Manage Replacements**: Edit frequently misrecognized words

**Voice Processor**
Choose your voice processing model:

* **Apple**: Built-in, optimized for privacy
* **Local**: Run on your machine with downloaded models
* **Cloud options**: Anthropic and other cloud providers with various capabilities

<img alt="Voice Settings" />

#### Voice Settings - Keyboard Shortcuts

Configure keyboard shortcuts for quick voice access from anywhere:

* **Keyboard Shortcut** : Start/stop voice input and speak commands. Customize the activation key for hands-free operation. Hold to speak to prompt, tap for dictation.
* **Meeting Shortcut** : Quick access to meeting-specific voice commands
* **Live Captions** : Enable live transcription overlay while speaking
* **Live Notepad** : Open the live notepad panel to capture voice input directly into notes

These shortcuts allow you to activate Alter's voice features without switching windows or taking your hands off the keyboard.

<img alt="Voice Shortcuts" />

#### Voice Settings - Automation

Configure automation for meetings and recordings:

* **Meeting apps**: Select which apps to monitor for meetings
* **Auto record meetings**: Automatically start recording when a meeting is detected
* **Find speakers names**: Identify each speaker's name based on the meeting service you are using
* **Keep dictation in pasteboard**: Retain voice input in clipboard

<img alt="Voice Automation" />

#### Voice Settings - Dictionary

Build a personal dictionary for accurate transcription:

* Add words or phrases Alter frequently misrecognizes
* Create custom terminology for your field or workflow

<img alt="Voice Dictionary" />

#### Voice Settings - Replacements

Set up word replacements for common transcription mistakes:

* Map frequently misheard words to correct ones
* Example: "Alter" → "Alter" (if misheard as "Altar")

<img alt="Voice Replacements" />

#### Voice Settings - Local Models

Choose from local voice processing models when using the Local processor:

**Why Local Processing?**

* **Complete privacy**: All audio processing happens on your Mac—no data is sent to cloud services
* **Zero data sharing**: Recordings, transcripts, and speaker identification stay entirely on your device
* **GDPR compliant**: Designed with data protection by design principles
* **Always available**: Works offline without internet dependency

**Local** - Basic local model options

* Whisper models for speech-to-text
* Multiple model sizes (Tiny, Base, Small, Medium, Large, etc.)
* Choose based on accuracy vs. performance trade-off

**Whisper Models**

OpenAI Whisper supports 50+ languages with comprehensive global coverage:

* **Major languages**: English, Spanish, French, German, Portuguese, Russian, Italian, Japanese, Korean, Chinese
* **European languages**: Dutch, Polish, Romanian, Swedish, Ukrainian, Greek, Czech, Hungarian, Slovak, Turkish, Danish, Norwegian, Finnish
* **Other languages**: Arabic, Hebrew, Hindi, Vietnamese, Thai, Indonesian, Tagalog, Bengali, Tamil, Marathi, Kannada, and many more

**Features:**

* Word-level timestamps automatically generated
* Speaker identification (who said what)
* Optimized to 626MB for Mac performance
* Best for global language coverage and accuracy

Whisper excels with widely-spoken languages but accuracy may vary for less common languages with limited training data.

<img alt="Voice - Local Models" />

**Local Plus** - Paid feature

Includes both Whisper and Parakeet models with automatic language detection:

**Whisper Models** (99 languages)

* Same broad language support as Local option
* Optimized for accuracy across diverse linguistic contexts

**Parakeet Models** (25 European languages)

* Fast, lightweight speech-to-text engine by NVIDIA
* **10x faster than Whisper** for meeting transcription on Mac
* Automatic language detection from audio
* Supports Bulgarian, Croatian, Czech, Danish, Dutch, English, Estonian, Finnish, French, German, Greek, Hungarian, Italian, Latvian, Lithuanian, Maltese, and 9+ other European languages

**Features:**

* Speaker diarization (identify different speakers)
* Optimized to 494MB for Mac performance
* Ideal for real-time meeting recording
* Best for European language workloads

**Choose your model:**

* **Parakeet**: Faster processing, lower resource usage, ideal for meetings (25 European languages)
* **Whisper**: Broader language coverage, maximum accuracy (50+ global languages)

Both models provide word-level timestamps, speaker identification, and automatic language detection—all processed locally on your Mac.

<img alt="Voice - Local Plus Models" />

### 3. Profile Settings

The **Profile** tab manages your identity and preferences:

**Account Email**

* View your current account email
* Used for billing and account recovery

**Discord Integration**

* Connect or disconnect your Discord account
* Enables Discord-specific workflows

**My Profile**

* Add a profile description (helps Alter provide better-tailored responses)
* Custom information Alter uses in conversations

**Generation Language**

* Set your preferred language for Alter's responses (default: English)
* Note: This may vary depending on the model you're using

<img alt="Profile Settings" />

### 4. Appearance Settings

The **Appearance** tab controls the visual look and feel:

**Theme Options**

* **System**: Match your Mac's system appearance
* **Light**: Force light theme
* **Dark**: Force dark theme

**Customization**

* **Default Panel Position**: Where panels appear (Top Right default)
* **Menu Font Size**: Adjust text size for readability (default: 16)
* **Message Font Size**: Set chat message text size (default: 15)
* **Display Notch**: Show the status indicator
* **Show control block in menu bar**: Display indicator in Alter menu bar
* **Hide in screen captures**: Exclude Alter from screenshots and screen sharing

<img alt="Appearance Settings - Dark Theme" />

<img alt="Appearance Settings - Light Theme" />

<img alt="Appearance Settings - Full View" />

### 5. Billing Settings

The **Billing** tab shows your subscription status:

**License Information**

* Your current plan (e.g., Pro Plan)
* Expiration date
* Change or End subscription options

**Fair Use**

* Visual indicator of your remaining fair use allocation
* Shows reset timeline (e.g., "Reset in 20 days")

<img alt="Billing Settings" />

### 6. Permissions Settings

The **Permissions** tab manages system access and data collection preferences:

**System Permissions**
Each permission can be enabled with quick-access buttons:

* **Launch at Login**: Start Alter automatically when your Mac starts
* **Accessibility**: Required for keyboard commands and window control (Check Accessibility)
* **System Preferences**: Allow access to system settings (Check System Preferences)
* **Screen Recording**: Capture screen content for analysis and context awareness (Check Screen Recording)
* **Microphone**: Enable voice input and dictation (Check Microphone)

**Analytics**

* **Disable Analytics**: Control whether Alter collects anonymized usage data. When enabled, Alter only collects anonymous UI interaction and error data to improve the product—no personal data or content is tracked.

<img alt="Permissions Settings" />

### 7. API Keys Settings

The **API keys** tab allows you to bring your own models:

**Partners**

* Integrate with partner services that provide OpenAI-compatible endpoints

**Custom Providers**
Add and manage custom LLM providers:

* **Add Provider**: Create new custom model endpoint
* **Provider URL**: Endpoint URL (e.g., `http://localhost:1234/v1`)
* **Manage Models**: View and test available models from each provider

**Supported Provider Types**
When adding a custom provider, you can choose from:

* **OpenAI**: OpenAI's API (GPT models)
* **Custom**: Generic OpenAI-compatible endpoints
* **Azure**: Microsoft Azure OpenAI Service
* **LM Studio**: Local models via LM Studio
* **PrivateMode**: Local inference engines
* **Bifrost**: Bifrost API provider
* **Mistral**: Mistral AI models
* **Gemini**: Google Gemini API
* **OpenRouter**: Multi-model router service
* **Ollama**: Local LLM framework
* **Osaurus**: Osaurus provider

**Adding a Provider**

1. Click "Add Provider" button
2. Select Provider Type from the dropdown
3. Enter the API endpoint URL
4. Provide your API Key
5. Click "Save" to configure

<img alt="API Keys - Providers Configured" />

<img alt="API Keys - No Providers" />

<img alt="API Keys - Provider Configuration" />

<img alt="API Keys - Add Provider Modal" />

<img alt="API Keys - Provider Type Dropdown" />

### 8. Router Settings

The **Router** tab configures the default AI endpoint:

**OpenAI Compatible Endpoint**

* Default endpoint for powering Alter models
* Link: [https://alterhq.com/api](https://alterhq.com/api)

**Alter API Keys**

* Generate and manage your personal API keys
* Use for integrations and third-party tools

<img alt="Router Settings" />

## Related Docs

* [Getting Started with Alter](/getting-started/getting-started-path)
* [Dictation & Voice](/workflows/dictation)
* [Choosing Your Generative Model](/how-to/choose-generative-model)
* [API Gateway & Router Service](/api-router/api-gateway)


# Manage tools
Source: https://docs.alterhq.com/how-to/tool-manager-guide

Connect and manage integrations safely with clear troubleshooting steps

## Goal

Connect and manage integrations safely with clear troubleshooting steps.

## Steps

1. Open Alter settings and go to integrations or tool manager.
2. Connect one integration at a time and test immediately.
3. Confirm required permissions and account scopes.
4. Create a simple test prompt to verify expected behavior.
5. If failures occur, review provider auth and retry.

## Managing Many Tools

Enabling many tools increases context window usage and impacts performance. For most workflows, use **Flow** - Alter's tool orchestrator that automatically selects the right tool for each request.

<Card title="Use Flow for Tool Orchestration" icon="wand-magic-sparkles" href="/workflows/use-flow-orchestration">
  Flow reduces context usage by acting as a single tool that routes requests to the appropriate integration automatically.
</Card>

Instead of loading all tools into every request, Flow:

* Analyzes your request and selects the right tool
* Handles multi-step orchestration across tools
* Reduces context window usage and improves performance

Enable Flow in Tool Manager under **Local Tools > Alter**.

## Troubleshooting

* Re-authenticate provider connection.
* Confirm local/network permissions.
* Check integration-specific limits and quotas.

## Related docs

* [Use Flow for Tool Orchestration](/workflows/use-flow-orchestration)
* [Tools Not Working](/common-issues/tool-not-working)


# How-To: Use Your Own API Key
Source: https://docs.alterhq.com/how-to/use-byok

Connect your own API keys from OpenAI, Mistral, and other providers

## Steps

1. Open settings with `Cmd+,`.
2. Open API Keys.
3. Select provider and paste key.
4. Type `/` in prompt to confirm custom models appear.

<img alt="Custom API keys" />

## Related Docs

* [Privacy-focused local model workflow](/workflows/local-model-privacy)
* [How to access settings](/how-to/settings-guide)


# Welcome
Source: https://docs.alterhq.com/index

Documentation for Alter, the macOS AI assistant that lives in your notch

<Card title="Quick start" icon="rocket" href="/quickstart">
  Learn the basics and start using Alter in minutes.
</Card>

## Start in 10 Minutes

<Steps>
  <Step title="Open Alter and grant permissions">
    Go to the [Quickstart guide](/quickstart) and complete the install and setup steps.
  </Step>

  <Step title="Learn core interaction modes">
    Open [Open Alter](/getting-started/open-alter) and try:

    * Hovering the notch
    * Opening with your shortcut
    * Speaking a simple request
  </Step>

  <Step title="Set up reliable context and tools">
    Apply context habits and automation basics from:

    * [Understand context and app awareness](/getting-started/understand-context-and-apps)
    * [Automate with workspaces and actions](/getting-started/automate-with-workspaces-and-actions)
  </Step>
</Steps>

## Quick Access

<Columns>
  <Card title="Context and apps" icon="sparkles" href="/getting-started/understand-context-and-apps">
    Learn how Alter understands your app context and files.
  </Card>

  <Card title="Voice & Dictation" icon="microphone" href="/getting-started/capture-voice-and-meetings">
    Start dictation, transcription, and meeting follow-up workflows.
  </Card>

  <Card title="AI Models" icon="brain" href="/workflows/local-model-privacy">
    Pick local vs cloud model workflows based on privacy and speed.
  </Card>

  <Card title="Automation basics" icon="wand-magic-sparkles" href="/getting-started/automate-with-workspaces-and-actions">
    Build repeatable workflows with Workspaces and Actions.
  </Card>
</Columns>

## Popular Topics

<Columns>
  <Card title="Quick Tasks" icon="bolt" href="/getting-started/open-alter">
    Step-by-step guides for common actions.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/common-issues/mic-not-transcribing">
    Solutions to common issues and problems.
  </Card>

  <Card title="Integrations" icon="plug" href="/apps-tools/integrations-overview">
    Connect Alter with your favorite tools.
  </Card>

  <Card title="FAQ" icon="circle-question" href="/references/faq-core">
    Answers to frequently asked questions.
  </Card>
</Columns>

## Need Help?

<CardGroup>
  <Card title="Discord" icon="discord" href="https://discord.gg/gvCMmfBRWZ">
    Join our community
  </Card>

  <Card title="YouTube" icon="youtube" href="https://youtube.com/@useAlter">
    Watch tutorials
  </Card>

  <Card title="Email" icon="envelope" href="mailto:hi@alterhq.com">
    Contact support
  </Card>
</CardGroup>


# Quickstart
Source: https://docs.alterhq.com/quickstart

Get started with Alter in three simple steps

## Get started in three steps

Start using Alter to boost your productivity with AI assistance.

### Step 1: Download and Install

<AccordionGroup>
  <Accordion icon="download" title="Download Alter">
    Download Alter from our [website](https://alterhq.com/beta) or the Mac App Store.

    System requirements:

    * macOS 15.0 or later
    * Apple Silicon or Intel Mac
  </Accordion>

  <Accordion icon="gear" title="Complete Setup">
    1. Open the downloaded DMG and drag Alter to your Applications folder
    2. Launch Alter from Applications
    3. Grant required permissions when prompted (Accessibility, Microphone, Screen Recording)

    <Tip>Alter needs these permissions to provide full functionality like reading selected text and capturing context.</Tip>
  </Accordion>
</AccordionGroup>

### Step 2: Initial Configuration

<AccordionGroup>
  <Accordion icon="user" title="Set up your profile">
    Open **Settings** (⌘,) and go to the **Profile** tab:

    * Tell Alter about yourself and your role
    * Share what you're working on
    * Set your preferred communication style
    * Add any technical references or explainers for tools you use

    This helps Alter provide more relevant and personalized responses.
  </Accordion>

  <Accordion icon="keyboard" title="Configure your hotkeys">
    In **Settings > Defaults**:

    * Set your **Quick Menu** shortcut (default: Alt+Space)
    * Enable the **Selection Button** for quick access when selecting text
    * Adjust other preferences as needed
  </Accordion>
</AccordionGroup>

### Step 3: Start Using Alter

<Accordion icon="rocket" title="Try your first interaction">
  1. **Open Alter**: Hover over your Mac's notch or press your Quick Menu shortcut
  2. **Type a prompt**: Ask a question or give a command
  3. **Add context**: Drag files or use `@` to add context
  4. **Use voice**: Hold the mic icon or press your dictation key to speak

  <Tip>Press `/` in the prompt box to see available AI models and select your favorite!</Tip>
</Accordion>

## Next steps

Now that you're set up, explore these key features:

<CardGroup>
  <Card title="Core Features" icon="sparkles" href="/getting-started/core-features">
    Discover AppSense, Follow Mode, actions, and workspaces.
  </Card>

  <Card title="Voice Commands" icon="microphone" href="/workflows/dictation">
    Master speech-to-text and voice automation.
  </Card>

  <Card title="Use Flow" icon="wand-magic-sparkles" href="/workflows/use-flow-orchestration">
    Let one tool orchestrator handle the right actions automatically.
  </Card>

  <Card title="Control Context" icon="compress" href="/how-to/managing-context-window">
    Keep your conversations accurate and fast over time.
  </Card>
</CardGroup>

<Note>
  **Need help?** Check our [FAQ](/references/faq-core), join our [Discord](https://discord.gg/gvCMmfBRWZ), or email [hi@alterhq.com](mailto:hi@alterhq.com).
</Note>


# API Model Reference
Source: https://docs.alterhq.com/references/api-model-names

Complete list of AI models available through the Alter API Router

This reference lists all AI models available through the Alter API Router. Use these model names when making API requests.

## Model Naming Format

All models follow the format: `Provider#Model-name`

For example: `OpenAI#gpt-5`, `Claude#claude-sonnet-4-6`

## OpenAI Models

| Model Name          | Description           | Context Window |
| ------------------- | --------------------- | -------------- |
| `OpenAI#gpt-5`      | Latest GPT-5 model    | 128K           |
| `OpenAI#gpt-5-mini` | Lightweight GPT-5     | 128K           |
| `OpenAI#gpt-5-nano` | Fastest GPT-5 variant | 128K           |
| `OpenAI#o3`         | Advanced reasoning    | 200K           |
| `OpenAI#o4-mini`    | Efficient reasoning   | 200K           |

## Claude (Anthropic) Models

| Model Name                 | Description          | Context Window |
| -------------------------- | -------------------- | -------------- |
| `Claude#claude-sonnet-4-6` | Latest Claude Sonnet | 200K           |
| `Claude#claude-opus-4-6`   | Most capable Claude  | 200K           |
| `Claude#claude-haiku-4-6`  | Fast Claude variant  | 200K           |

## Gemini (Google) Models

| Model Name                     | Description         | Context Window |
| ------------------------------ | ------------------- | -------------- |
| `Gemini#gemini-2.5-pro`        | Most capable Gemini | 1M             |
| `Gemini#gemini-2.5-flash`      | Fast Gemini         | 1M             |
| `Gemini#gemini-2.5-flash-lite` | Lightweight Gemini  | 1M             |

## Mistral Models

| Model Name                     | Description          | Context Window |
| ------------------------------ | -------------------- | -------------- |
| `Mistral#mistral-large-latest` | Most capable Mistral | 128K           |
| `Mistral#mistral-small-latest` | Efficient Mistral    | 128K           |
| `Mistral#codestral-2501`       | Code specialist      | 32K            |
| `Mistral#pixtral-large-latest` | Vision capable       | 128K           |

## Perplexity Models

| Model Name                   | Description         | Context Window |
| ---------------------------- | ------------------- | -------------- |
| `Perplexity#sonar`           | Web-aware model     | 128K           |
| `Perplexity#sonar-pro`       | Advanced web search | 128K           |
| `Perplexity#sonar-reasoning` | Reasoning with web  | 128K           |

## Alter Models

| Model Name    | Description                      |
| ------------- | -------------------------------- |
| `Alter#best`  | Automatically selects best model |
| `Alter#fair`  | Cost-effective option            |
| `Alter#light` | Fastest response                 |

## Usage Examples

### Python

```python theme={null}
from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://alterhq.com/api/v1"
)

# Use GPT-5
response = client.chat.completions.create(
    model="OpenAI#gpt-5",
    messages=[{"role": "user", "content": "Hello!"}]
)
```

### cURL

```bash theme={null}
curl https://alterhq.com/api/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "OpenAI#gpt-5",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'
```

## Model Selection Tips

**For Speed**

* `Alter#light`
* `OpenAI#gpt-5-nano`
* `Gemini#gemini-2.5-flash-lite`

**For Quality**

* `Alter#best`
* `OpenAI#gpt-5`
* `Claude#claude-opus-4-6`
* `Gemini#gemini-2.5-pro`

**For Coding**

* `OpenAI#gpt-5`
* `Mistral#codestral-2501`
* `Claude#claude-sonnet-4-6`

**For Vision**

* `OpenAI#gpt-5`
* `Gemini#gemini-2.5-pro`
* `Mistral#pixtral-large-latest`

**For Cost**

* `Alter#fair`
* `Alter#light`
* `OpenAI#gpt-5-nano`


# API Router Overview
Source: https://docs.alterhq.com/references/api-router-overview

Overview of the Alter API Router service and OpenAI-compatible endpoint

The Alter API Router is an OpenAI-compatible API gateway that provides unified access to 92+ AI models from 10+ providers through a single endpoint.

## What is the API Router?

The API Router is a centralized service that eliminates the need to manage multiple API keys and billing accounts across different AI providers. Instead of maintaining separate accounts with OpenAI, Anthropic, Google, and others, you can use Alter as your single entry point for all AI model access.

### Key Benefits

* **Single API key** for all providers
* **Centralized billing** through your Alter account
* **92+ models** from 10+ providers
* **OpenAI-compatible endpoint** works with existing tools and SDKs
* **Easy model switching** without code changes

## Quick Start

### 1. Generate an API Key

1. Open **Settings** (**⌘ ,**)
2. Go to the **Router** tab
3. Under "Alter API Keys", click **Add New Key**
4. Copy your key (starts with `sk-`)

### 2. Get the Endpoint

```
https://alterhq.com/api
```

For most tools, use:

```
https://alterhq.com/api/v1
```

### 3. List Available Models

```bash theme={null}
curl https://alterhq.com/api/models \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Model Naming Format

Models use the format: `Provider#Model-name`

Examples:

* `OpenAI#gpt-5` - Latest GPT-5
* `OpenAI#gpt-5-mini` - Lightweight GPT-5
* `Claude#claude-sonnet-4-6` - Latest Claude
* `Gemini#gemini-2.5-pro` - Latest Gemini

## Usage Example

```python theme={null}
from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://alterhq.com/api/v1"
)

response = client.chat.completions.create(
    model="OpenAI#gpt-5",
    messages=[
        {"role": "user", "content": "What is machine learning?"}
    ]
)

print(response.choices[0].message.content)
```

## Usage Limits

* **Daily Limit**: 200 requests per day under fair use
* **Throttling**: After 200 requests, throttled to 1 per 10 minutes
* **Budget Top-up**: Available for consistent access beyond fair use

## Next Steps

* [API Gateway Guide](/api-router/api-gateway) - Complete usage documentation
* [API Router for Development](/api-router/development) - SDK and code examples
* [App Integrations with API Router](/api-router/app-integrations) - Connect third-party apps
* [Model Naming Reference](/references/api-model-names) - Full model list
* OpenAPI Reference - Interactive API documentation


# Documentation Map
Source: https://docs.alterhq.com/references/docs-map

Quick reference to all sections of the Alter documentation

## Core Documentation Sections

| Section              | Location                                                                                                    |
| -------------------- | ----------------------------------------------------------------------------------------------------------- |
| Getting Started      | [Getting Started Guide](/getting-started/getting-started-path)                                              |
| The Notch            | [Getting Started](/getting-started/getting-started-path#the-notch)                                          |
| Hotkey               | [Getting Started](/getting-started/getting-started-path#hotkey-alter-quick-menu)                            |
| Voice Command        | [Getting Started](/getting-started/getting-started-path#voice-command)                                      |
| Context Section      | [Window Types: Notch, Hub, and Panels](/getting-started/window-types-notch-hub-panels#the-context-section)  |
| Conversation History | [Window Types: Notch, Hub, and Panels](/getting-started/window-types-notch-hub-panels#conversation-history) |
| Core Features        | [Core Features](/getting-started/core-features)                                                             |
| AppSense             | [Core Features](/getting-started/core-features#appsense-understanding-your-mac)                             |
| Follow Mode          | [Core Features](/getting-started/core-features#follow-mode)                                                 |
| Workspaces           | [Core Features](/getting-started/core-features#workspaces)                                                  |
| Alter Actions        | [Core Features](/getting-started/core-features#alter-actions-workflows)                                     |
| Files and Folders    | [Core Features](/getting-started/core-features#interacting-with-files-and-folders)                          |

## AI Models

| Section             | Location                                                               |
| ------------------- | ---------------------------------------------------------------------- |
| Choosing Your Model | [Choose your generative model](/how-to/choose-generative-model)        |
| Using Your API Key  | [How-To: Use Your Own API Key](/how-to/use-byok)                       |
| Local Models        | [Privacy-Focused Local Model Workflow](/workflows/local-model-privacy) |

## API Router

| Section                | Location                                                          |
| ---------------------- | ----------------------------------------------------------------- |
| API Gateway Guide      | [API Gateway Guide](/api-router/api-gateway)                      |
| API Router Development | [API Router for Development](/api-router/development)             |
| API Router Operations  | [API Router Operations & Troubleshooting](/api-router/operations) |
| App Integrations       | [App Integrations with API Router](/api-router/app-integrations)  |
| TypingMind Setup       | [Set Up TypingMind with Alter API](/api-router/typingmind)        |
| Msty.ai Setup          | [Set Up Msty.ai with Alter API](/api-router/msty)                 |
| API Model Names        | [API Model Names](/references/api-model-names)                    |

## Voice & Dictation

| Section               | Location                                                          |
| --------------------- | ----------------------------------------------------------------- |
| Dictation             | [Dictation Guide](/workflows/dictation)                           |
| Voice Triggers        | [Dictation Guide](/workflows/dictation#voice-triggers)            |
| Modes                 | [Dictation Guide](/workflows/dictation#modes)                     |
| Meetings              | [Meetings Guide](/workflows/meetings)                             |
| Meeting Recording     | [Meetings Guide](/workflows/meetings#automatic-meeting-recording) |
| Live Captions         | [Meetings Guide](/workflows/meetings#live-captions)               |
| Accessing Transcripts | [Meetings Guide](/workflows/meetings#accessing-your-transcripts)  |

## Settings

| Section            | Location                                                   |
| ------------------ | ---------------------------------------------------------- |
| Accessing Settings | [Alter Settings](/how-to/settings-guide)                   |
| Defaults           | [Alter Settings](/how-to/settings-guide#defaults)          |
| Dictation Settings | [Alter Settings](/how-to/settings-guide#dictation)         |
| Appearance         | [Alter Settings](/how-to/settings-guide#appearance)        |
| Permissions        | [Alter Settings](/how-to/settings-guide#permissions)       |
| External API Keys  | [Alter Settings](/how-to/settings-guide#external-api-keys) |
| Router             | [Alter Settings](/how-to/settings-guide#router)            |

## Integrations & Tools

| Section                      | Location                                                            |
| ---------------------------- | ------------------------------------------------------------------- |
| Integrations Overview        | [Integrations Guide](/apps-tools/integrations-overview)             |
| Local Tools                  | [Integrations Guide](/apps-tools/integrations-overview#local-tools) |
| Tool Manager                 | [Tool Manager Guide](/how-to/tool-manager-guide)                    |
| Troubleshooting Integrations | [Tools Not Working](/common-issues/tool-not-working)                |
| URL Callbacks                | [URL Callbacks Guide](/workflows/url-callbacks)                     |
| Workspaces & Actions         | [Workspaces Guide](/workflows/workspaces-actions)                   |

## Troubleshooting

| Section                      | Location                                                                               |
| ---------------------------- | -------------------------------------------------------------------------------------- |
| Microphone Issues            | [Microphone Not Working](/common-issues/mic-not-transcribing)                          |
| Hotkey Issues                | [Keyboard Shortcut Not Working](/common-issues/hotkey-not-working)                     |
| Tool Issues                  | [Tools Not Working](/common-issues/tool-not-working)                                   |
| Missing Data After Reinstall | [Data missing after reinstall or cleanup](/common-issues/data-missing-after-reinstall) |
| Custom Provider Issues       | [Custom Models Not Showing](/common-issues/custom-provider-not-showing)                |
| API Gateway Issues           | [API Gateway Won't List Models](/common-issues/models-not-listed-in-api-gateway)       |

## Quick Tasks

| Section          | Location                                                        |
| ---------------- | --------------------------------------------------------------- |
| Choose Model     | [Choose your generative model](/how-to/choose-generative-model) |
| Change Hotkey    | [How-To: Change Hotkey](/how-to/change-hotkey)                  |
| Choose Language  | [How-To: Choose Language](/how-to/choose-language)              |
| Use Your API Key | [How-To: Use Your Own API Key](/how-to/use-byok)                |
| Access Settings  | [How-To: Access Settings](/how-to/settings-guide)               |

## Use Cases

| Section                | Location                                                               |
| ---------------------- | ---------------------------------------------------------------------- |
| Meeting Workflow       | [Meeting Capture and Follow-Up](/workflows/meeting-workflow)           |
| Privacy & Local Models | [Privacy-Focused Local Model Workflow](/workflows/local-model-privacy) |

## Reference

| Section                | Location                                                     |
| ---------------------- | ------------------------------------------------------------ |
| Core FAQ               | [Core FAQ](/references/faq-core)                             |
| General FAQ            | [General FAQ](/references/general-faq)                       |
| Local Data and Privacy | [Local data and privacy](/references/local-data-and-privacy) |
| Pricing FAQ            | [Pricing FAQ](/references/pricing-faq)                       |
| Shortcuts              | [Shortcuts](/references/shortcuts)                           |
| Image Library          | [Image Library](/references/image-library)                   |


# Core FAQ
Source: https://docs.alterhq.com/references/faq-core

Quick answers to common questions about using Alter

Use these short answers first, then expand with how-to or guide content.

Scope: quick in-product usage questions only (opening Alter, context, settings, dictation, BYOK setup).

## How do I open Alter?

1. Hover over the notch.
2. Press `Alt+Space`.
3. Hold `Fn` and speak.

<img alt="Open Alter" />

See [Getting Started](/getting-started/getting-started-path) for more details.

## How do I add my own API key?

1. Open Settings (`Cmd+,`).
2. Go to API Keys.
3. Select provider and enter key.

<img alt="Custom API keys" />

See [How-To: Use Your Own API Key](/how-to/use-byok) for detailed instructions.

## How do I add context to a prompt?

* Drag and drop files onto the notch.
* Right-click files and choose Add to Alter.
* Use `@` to add context from the prompt.

<img alt="Drag and drop" />

See [Window Types: Notch, Hub, and Panels](/getting-started/window-types-notch-hub-panels#the-context-section) for more details.

## How do I change settings quickly?

* Open Alter and press `Cmd+,`.
* Or open three-dot menu -> Settings.

<img alt="Settings menu" />

See [Alter Settings](/how-to/settings-guide) for more details.

## How do I configure dictation?

Settings -> Dictation, then choose processor, language, and replacements.

<img alt="Dictation" />

See [Dictation Guide](/workflows/dictation) for complete setup instructions.


# General FAQ
Source: https://docs.alterhq.com/references/general-faq

Use this for high-level 'about Alter' questions from the main website FAQ

Scope: product positioning, compatibility, privacy, model categories, and support.
For pricing, free-trial terms, fair use, devices, and discounts use `references/pricing-faq.md`.

## What makes Alter different from other tools?

Alter is a native macOS AI assistant that understands your current work context and integrates directly with your apps.

## What are the system requirements?

Alter supports macOS Ventura 13 or newer and runs on both Apple Silicon and Intel Macs.

## What macOS apps are compatible with Appsense?

All macOS apps are compatible with Alter Appsense out of the box.

## How does Alter save me time?

Alter gives contextual help in your workflow: writing support, meeting recording and summaries, and drag-and-drop file context.

## What AI models can I use with Alter?

Alter supports leading providers and adds newly released models quickly.

* Vision-capable models (for example Gemini, Claude, GPT-5, Pixtral)
* Text-focused models (for example Llama, Qwen, DeepSeek)

## Can I use my own API keys?

Yes. See [How to use your own API key](/how-to/use-byok).

## Can I use Alter offline or with local models?

Yes. Alter supports Ollama and LM Studio for local processing. See [Privacy-Focused Local Model Workflow](/workflows/local-model-privacy).

Note: LM Studio support may vary by device class; Ollama is broadly supported on Mac.

## Can I use Alter with a router?

Yes. Alter works with OpenAI-compatible routers by entering endpoint + API key in settings.
Alter is also a router itself via its API gateway.

## Can Alter see my data?

Prompts and data sent to models are encrypted in transit.
Alter collects anonymous usage analytics, which can be disabled in settings.

## Are my chats and transcripts stored in the cloud?

No. Alter stores chats, transcripts, and other local history on your Mac. There is no cloud sync or cloud restore for that history.

See [Local data and privacy](/references/local-data-and-privacy).

## Can I install an older version of Alter?

Yes. Download the version you want from [alterhq.com/changelog](https://alterhq.com/changelog) and replace the app in your `Applications` folder.

Do not uninstall first if you want to keep your local data.

See [Reinstall or downgrade Alter safely](/how-to/reinstall-or-downgrade-alter).

## Where can I find help and support?

* Discord: [https://discord.gg/gvCMmfBRWZ](https://discord.gg/gvCMmfBRWZ)
* Email: [hi@alterhq.com](mailto:hi@alterhq.com)


# Image Library
Source: https://docs.alterhq.com/references/image-library

Canonical image URLs and references for Alter documentation

All canonical image URLs should point to `/images/...`.

## Getting Started

| Image       | URL                                           | Use For               |
| ----------- | --------------------------------------------- | --------------------- |
| Open Notch  | `/images/getting-started/open-notch.gif`      | How to open Alter     |
| Hold Mic    | `/images/getting-started/hold-mic.gif`        | Speech-to-prompt      |
| Click Mic   | `/images/getting-started/click-mic.gif`       | Dictation mode        |
| Right Click | `/images/getting-started/right-click-add.gif` | Adding files via menu |

## Models and API

| Image              | URL                                     | Use For              |
| ------------------ | --------------------------------------- | -------------------- |
| Choose Model       | `/images/models/choose-model.gif`       | Model selection      |
| Favorite Model     | `/images/models/favorite-model.webp`    | Marking favorites    |
| Custom API Keys    | `/images/models/custom-api-keys.webp`   | BYOK setup           |
| Local Models       | `/images/models/local-models.png`       | Ollama and LM Studio |
| Custom Models List | `/images/models/custom-models-list.png` | Custom section       |

## Context and Files

| Image         | URL                                 | Use For             |
| ------------- | ----------------------------------- | ------------------- |
| Drag and Drop | `/images/context/drag-and-drop.gif` | Adding files        |
| AppSense      | `/images/context/appsense.gif`      | Current app context |
| Workspaces    | `/images/context/workspaces.gif`    | Creating workspaces |

## Settings

| Image         | URL                                  | Use For                    |
| ------------- | ------------------------------------ | -------------------------- |
| Settings Menu | `/images/settings/settings-menu.png` | Accessing settings         |
| Defaults      | `/images/settings/defaults.png`      | Default settings           |
| Appearance    | `/images/settings/appearance.png`    | Theme and notch visibility |
| Dictation     | `/images/settings/dictation.webp`    | Voice settings             |
| Permissions   | `/images/settings/permissions.png`   | Permissions                |
| Profile       | `/images/settings/profile.png`       | Profile and language       |
| Billing       | `/images/settings/billing.png`       | Billing                    |
| Router        | `/images/settings/router.png`        | API gateway                |

## Meetings

| Image       | URL                                 | Use For              |
| ----------- | ----------------------------------- | -------------------- |
| Auto-Record | `/images/meetings/auto-record.webp` | Auto-record toggle   |
| Recording   | `/images/meetings/recording.gif`    | Meeting notification |

## Other

| Image        | URL                               | Use For              |
| ------------ | --------------------------------- | -------------------- |
| Help Menu    | `/images/other/help-menu.png`     | Prompt shortcuts     |
| History Tags | `/images/other/history-tags.webp` | Conversation history |

## Integrations

| Image                   | URL                                                   | Use For                            |
| ----------------------- | ----------------------------------------------------- | ---------------------------------- |
| URL Callback Settings   | `/images/integrations/alter-callback-urls-focus.webp` | x-callback-url setup               |
| TypingMind Basic Config | `/images/integrations/typingmind-basic-config.png`    | TypingMind custom model setup      |
| TypingMind Auth Header  | `/images/integrations/typingmind-auth-header.png`     | TypingMind Authorization header    |
| Msty Endpoint + API Key | `/images/integrations/msty-endpoint-api-key.jpeg`     | Msty.ai endpoint and API key setup |


# Local data and privacy
Source: https://docs.alterhq.com/references/local-data-and-privacy

Understand what Alter stores locally, what is not synced to the cloud, and how to protect your data before reinstalling.

Alter stores your chats, transcripts, and related data on your Mac.

<Info>
  **Private and local-first:** Alter does not use cloud sync to keep a backup of your chats, meeting transcripts, or local history.
</Info>

## What stays on your Mac

* Chat history
* Meeting transcripts and recordings
* Local workspace data
* Other app data that Alter keeps for your account on that Mac

If you use cloud models for generation or cloud transcription for a specific task, that request is sent to the provider you selected. That is separate from cloud syncing your Alter history.

## What this means in practice

* Your data stays private to your Mac by default
* Reinstalling Alter does not restore old chats or transcripts from a cloud backup
* Moving to another Mac requires your own backup or transfer process

## Before you reinstall, downgrade, or troubleshoot

<Warning>
  Do not uninstall Alter if you want to keep your existing data.
</Warning>

If you need to try another version:

1. Download the version you want from the [Alter changelog](https://alterhq.com/changelog).
2. Quit Alter.
3. Drag the downloaded app into your `Applications` folder.
4. Choose **Replace** when macOS asks.

This replaces the app without doing a cleanup-style uninstall.

See [Reinstall or downgrade Alter safely](/how-to/reinstall-or-downgrade-alter).

## Why uninstall tools can remove your data

Utilities such as CleanMyMac often remove the app **and** its support files in `~/Library/Application Support`.

That can delete the local Alter database and transcript files at the same time.

## If you want a backup first

* Open Alter settings and use the data-location shortcut if available
* Copy your Alter data folder to another safe location
* Keep a normal Mac backup such as Time Machine before major changes

## If your data is already missing

See [Data missing after reinstall or cleanup](/common-issues/data-missing-after-reinstall).


# Pricing FAQ
Source: https://docs.alterhq.com/references/pricing-faq

Information about Alter plans, billing, fair use, and device limits

Use this reference when users ask about plans, billing, fair use, discounts, or device limits.

Scope: all money/plan policy questions, including trial terms and licensing limits.
For product capabilities and setup flows use `references/general-faq.md` and `references/faq-core.md`.

## Plans At A Glance

* **Free (\$0)**: All core Alter features with your own API keys or local models. No credit card required.
* **Local+ (add-on)**: Advanced local voice models (Whisper Pro and Parakeet V3), up to 3 devices.
* **Pro (subscription)**: Managed access to 50+ cloud models, router models (Best/Fast/Light), API gateway, remote tools, priority support.
* **Lifetime (one-time)**: Same access level as subscription plan without recurring billing.

## Trial And Free Usage

### Is Alter really free?

Yes. Alter is free to use with core features when using local models or your own API keys.

### What happens after the 7-day trial?

After trial, the app remains functional with BYOK/local usage. Paid plans remove upgrade prompts and provide managed model access.

## Unlimited And Fair Use

### What does "Unlimited" mean?

Paid plans include unlimited requests in Alter app, subject to fair use policy.

### How does fair use work?

* Uses a monthly budget system, not strict message caps.
* If budget is exceeded, requests may route to lower-cost models with in-app indication.
* API gateway has a daily limit (200 requests/day), then throttles to 1 request per 10 minutes.
* Heavy-use autonomous coding agent traffic is prohibited under policy.

## Routers

### What is Alter Light?

A router focused on speed/cost by selecting lite/flash models.

### What is Alter Best?

A balanced router that selects strong models (for example Sonnet-family) for quality and speed.

### What is Alter Fast?

A speed-first router prioritizing very high throughput models.

## Devices And Licensing

### Can I use Alter on multiple devices?

Yes, with all plans. Active use is limited to one device at a time for a single user.

### Device limits by plan

* **Local+**: up to 3 devices installed
* **Pro/Lifetime**: unlimited installs
* **All plans**: one active device at a time; no license sharing

## Discounts

### Student / Academic discount

Available. Contact `hi@alterhq.com` from your university email.

### Non-profit discount

Available. Contact `hi@alterhq.com` with organization details.

## Support Guidance For Responses

* Be explicit about the difference between **free core app** and **managed paid model access**.
* Mention fair use and API gateway limits when users ask about "unlimited".
* Include single-user licensing language when device-sharing is asked.
* Point users to billing/support: `hi@alterhq.com`.

## Related Documentation

* [Pricing FAQ](/references/pricing-faq)
* [API Gateway Guide](/api-router/api-gateway)


# Shortcuts
Source: https://docs.alterhq.com/references/shortcuts

Complete list of keyboard shortcuts for Alter

### Global Navigation

Available across windows (unless the target window is already active).

* **Shift + Cmd + H**: Open Alter Hub
* **Shift + Cmd + E**: Open Action Editor
* **Shift + Cmd + T**: Open Tools Manager
* **Alt + Space** (default): Open notch — configurable in **Settings > Defaults > Open notch keybinding**
* **Alter Quick Menu shortcut**: Open Alter from anywhere — configurable in **Settings > General > Quick Access**
* **Speech-to-text hotkey**: Start voice input — configurable in **Settings > Dictation > Shortcut** (default: Fn key)

### Quick Panel

When the quick panel is open (from the notch):

* **←**, **↑**, **→**, **↓**: Navigate between objects
* **Enter**: Select an object

### Context Section

* **←**, **↑**, **→**, **↓**: Navigate between contexts
* **Space Bar**: Add/remove selected context(s)
* **Cmd + K**: Remove all contexts from the active conversation
* **Cmd + V**: Paste clipboard content to add to context

### Prompt Box

* **Enter**: Prompt with your active model
* **Cmd + Enter**: Prompt using web search (via Gemini web)
* **Shift + Enter**: Line break
* **@**: Add elements to context
* **#**: Show history of Alter conversations
* **>**: Show history of meeting transcriptions
* **/**: List and choose your model
* **?**: Show help menu

### Alter Hub Window

* **Cmd + F**: Focus search (arrow keys to navigate results)
* **Cmd + B**: Toggle sidebar visibility
* **Cmd + T**: New tab (start new chat)
* **Cmd + J**: Create workspace (requires active context)
* **Cmd + Opt + O**: Switch to workspace...
* **Cmd + K**: Clear all contexts (requires active contexts)
* **Cmd + Delete**: Delete conversation (requires active conversation)
* **Cmd + W**: Close tab (closes window if it's the last tab)
* **Cmd + Opt + W**: Close all tabs (requires >1 tab)
* **Cmd + Opt + ←**: Previous tab (requires >1 tab)
* **Cmd + Opt + →**: Next tab (requires >1 tab)
* **Cmd + 1...9**: Switch to specific tab index

#### Workspace (requires selected workspace)

No default shortcuts; these can be set via macOS System Settings:

* Open workspace settings
* Rename workspace
* Set permissions
* Toggle sandbox
* Start/Stop sandbox container
* Open terminal in sandbox

### Action Editor Window

* **Cmd + F**: Focus search
* **Cmd + N**: New action
* **Cmd + D**: Duplicate action (requires selected action)
* **Cmd + E**: Export action (requires selected action)
* **Cmd + O**: Import action
* **Cmd + Delete**: Delete action (requires selected action)
* **Cmd + W**: Close window
* **Cmd + \[**: Previous section
* **Cmd + ]**: Next section

### Tools Manager Window

* **Cmd + W**: Close window
* **Cmd + F**: Focus search
* **When "Skills" is selected**: Cmd + O (Import skill), Cmd + R (Refresh list)
* **When "Remote MCP Servers" is selected**: Cmd + N (Add server), Cmd + R (Refresh list)
* **When "Quick Actions" is selected**: Cmd + N (New quick action), Delete (Delete quick action, requires selection)

### Live Meetings Panels

Available during meetings only:

* **Cmd + Shift + ↓**: Toggle live captions on/off
* **Shift + Cmd + →**: Toggle live notepad

### Alter Settings

* **Cmd + ,**: Open settings (when Alter window is visible)


# Alter Actions
Source: https://docs.alterhq.com/workflows/alter-actions

Create and configure custom AI workflows with voice triggers and automation

<Info>
  **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.
</Info>

## 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**

<img alt="Menu Bar" />

### Method 2: Options Menu

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

<img alt="Options Menu" />

### Method 3: Keyboard Shortcut

Press **⌘ E** (Command + E) to open the Action Editor directly

<Tip>
  The keyboard shortcut is the fastest method once you've memorized it.
</Tip>

## 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.

<img alt="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

<Note>
  Each action gets a unique UUID automatically.
</Note>

### 2. System Prompt

Define AI instructions and parameters for the model.

<img alt="System Prompt Tab" />

**System Prompt** - Core AI instructions describing the AI's behavior and expertise.

**Example:**

```
# IDENTITY AND PURPOSE
You are an expert software engineer who explains code clearly
and accessibly to developers of all skill levels.

# STEPS
1. Analyze the provided code
2. Identify its purpose and key components
3. Explain each section in simple terms

# OUTPUT INSTRUCTIONS
- Use markdown formatting
- Include code examples where helpful
- Keep language clear and non-technical
```

**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.

<img alt="User Prompt Tab" />

**Using Context Variables:**

Wrap variables in `{{ }}` to insert dynamic content:

```
Please explain this code:

{{ textSelection }}

Explanation detail: {{ detailLevel }};
```

**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.

<img alt="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.

<img alt="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.

<img alt="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

**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 and adjust creativity level.

<img alt="Model Tab" />

**Fields:**

* **Model** - Choose specific AI model for this action
  * Leave empty to use user's default model setting
  * Or select: Claude, GPT-4, local model, etc.

* **Temperature** - Adjust creativity vs. precision
  * **0.0** - Deterministic (consistent, predictable)
  * **0.5** - Balanced (default)
  * **1.0** - Creative (unpredictable, exploratory)

## Best Practices

<CardGroup>
  <Card title="Clear Names" icon="tag">
    "Code Explainer" describes what it does. Avoid generic names like "Action 1".
  </Card>

  <Card title="Specific Prompts" icon="message">
    Be detailed with AI instructions. Generic prompts produce generic outputs.
  </Card>

  <Card title="Scope Tools" icon="tool">
    Enable only the tools your action needs. Reduces overhead and improves speed.
  </Card>

  <Card title="Use Context Variables" icon="brackets">
    `{{ textSelection }}` always works. Manual copy/paste is error-prone.
  </Card>

  <Card title="Conditional Visibility" icon="eye">
    "Code Explainer" only in VSCode + Xcode reduces menu clutter.
  </Card>

  <Card title="Test Before Sharing" icon="check">
    Test with real data before deploying to your team.
  </Card>
</CardGroup>

## 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:

<Steps>
  <Step title="System Settings">
    Go to **Settings > Voice Triggers**
  </Step>

  <Step title="Add Trigger">
    Click **+ Add Trigger**
  </Step>

  <Step title="Select Action">
    Choose action from dropdown
  </Step>

  <Step title="Assign Phrase">
    Enter trigger phrase (e.g., "explain" for Code Explainer)
  </Step>

  <Step title="Save">
    Click Save and you're ready
  </Step>
</Steps>

**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

<Steps>
  <Step title="Open Action Editor">
    Press **⌘ E**
  </Step>

  <Step title="Select Action">
    Choose the action you want to expose
  </Step>

  <Step title="Go to General">
    Navigate to General tab
  </Step>

  <Step title="Find URL Callback">
    Look for "URL Callback" section
  </Step>

  <Step title="Copy URL">
    Copy the `alter://` URL
  </Step>
</Steps>

**Format:**

```
alter://action/{action-id}?input=VALUE&param2=VALUE
```

### Triggering Alter Actions from Other Apps

**Example 1: Web Search from Safari**

```
alter://action/ask-web?input=What+is+Alter+MacOS
```

**Example 2: Code Explainer with Input**

```
alter://action/explain-code?input=const+hello+%3D+%28%29+%3D%3E+%7B%7D
```

**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

<AccordionGroup>
  <Accordion icon="workflow" title="Workflow Automation">
    Trigger action from Calendar → Generate meeting notes → Create email draft
  </Accordion>

  <Accordion icon="link-2" title="Multi-App Integration">
    Notion button → Trigger Alter action → Update task status
  </Accordion>

  <Accordion icon="copy" title="Information Transfer">
    Copy text → Trigger action with callback → Open result in external app (no manual copying needed)
  </Accordion>
</AccordionGroup>

## Keyboard Shortcuts

| Action             | Shortcut                   |
| ------------------ | -------------------------- |
| Open Action Editor | `⌘ E`                      |
| New Action         | `Cmd + N` (in editor)      |
| Save Action        | `Cmd + S` (in editor)      |
| Delete Action      | `Cmd + Delete` (in editor) |
| Search Actions     | `Cmd + F` (in editor)      |

## Troubleshooting

<AccordionGroup>
  <Accordion icon="circle-exclamation" title="Action doesn't appear in menu">
    * Check **When to Show** settings
    * Verify app is running/active (if configured)
    * Ensure action is **enabled**
  </Accordion>

  <Accordion icon="triangle-exclamation" title="Action runs but produces poor output">
    * Review **System Prompt** — be more specific
    * Adjust **Temperature** (lower for precision, higher for creativity)
    * Check **User Prompt** — ensure variables are correct
  </Accordion>

  <Accordion icon="microphone" title="Voice trigger not working">
    * Verify hotkey is configured in Settings
    * Check microphone permissions
    * Test with manual trigger first
  </Accordion>

  <Accordion icon="lock" title="Tools not available in action">
    * Go to **Tools** tab
    * Verify tools aren't disabled
    * Check system permissions for the tool
  </Accordion>
</AccordionGroup>

## Related Guides

* [Tools & Integrations](/apps-tools/integrations-overview) — Available tools for your actions
* [URL Callbacks](/workflows/url-callbacks) — Deep dive into x-callback-url automation
* [Voice & Dictation](/workflows/dictation) — Set up voice triggers
* [Settings](/how-to/settings-guide) — Configure global model and voice settings

***

**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.


# Automate Blogging with Alter
Source: https://docs.alterhq.com/workflows/automate-blogging-with-alter

Teach Alter your writing style so it can help you automate content creation

<Info>
  **The problem:** AI models don't know your voice or writing style. They're trained on millions of texts from thousands of writers. To scale your writing without sounding generic, you have to give Alter the knowledge of who you are as a writer.
</Info>

## Why generic AI output doesn't sound like you

When you ask an LLM to write something, you're asking a system trained on hundreds of thousands of voices to guess what *your* voice sounds like. It doesn't know that you prefer short sentences over long ones. It doesn't know you lean conversational instead of formal. It doesn't know the perspective or tone that makes your work distinctly yours.

Each time you use an AI to help with content, you either:

* Accept generic output and spend hours editing it back to your voice
* Manually explain your style and tone every single time
* Stop automating because the overhead kills your productivity

**The cost:** You can't grow your writing output without losing the very thing that makes it valuable - your voice.

## The real solution: teach Alter who you are

Instead of re-explaining your voice every time, you encode it once into a **custom skill**. This skill becomes a permanent reference that tells Alter exactly how you write. Then you isolate it in a **workspace** with your project files, and activate it instantly with a **mode**. Now scaling your output means quality stays consistent because Alter isn't guessing - it's following your actual style.

This isn't about convenience. It's about making productivity possible without diluting your voice.

## How it works: giving Alter the knowledge it needs

**1. Custom skills teach Alter your voice**
A skill contains your writing samples, tone guidelines, formatting rules, and preferences. Instead of Alter trying to infer your style from thin air, it has concrete examples of how you write. It references these samples every time it helps you, so the output stays true to your voice.

**2. Workspaces give Alter context about your work**
When you link your blog repository or project folder to a workspace, Alter understands your structure, your conventions, and how you organize things. It's not starting from zero - it knows your actual ecosystem.

**3. Modes make activation automatic**
Modes let you switch into "Blogging Mode" with a single hotkey. Your workspace loads, your skill activates, your context is ready. No setup, no thinking - just write.

## Step-by-step: teaching Alter your voice

In this workflow, I demonstrate how I codified my blog creation process including capturing my writing style as a skill, then using Alter to automate blog post creation through the use of Workspaces and Modes.

While this tutorial shows how I set up my workflow for blogging, you can apply these principles to any type of writing or content creation.

### 1. Create a workspace (start here)

Your workspace is the foundation. Create it first so you have a dedicated context for your style skill to work with.

<Steps>
  <Step title="Open Alter Hub">
    In Alter's notch menu, find the **Open The Hub** section (or **Shift + , Cmd + H**)
  </Step>

  <Step title="Create a new workspace">
    Click **+ New Workspace**

    <img alt="New Workspace" />
  </Step>

  <Step title="Link your project folder">
    Select your blog repository, or any folder containing your content structure.

    <img alt="Workspace Add Files" />
  </Step>

  <Step title="Name and save">
    Give it a memorable name like "Blogging Workspace" and save
  </Step>
</Steps>

### 2. Create your custom blogging skill

Now that you have a workspace linked with your project context, we create a custom blogging skill. There are plenty of resources online explaining how to create a custom skill, so I won't go into that here. Instead, I will provide some references to get started below. Instead here's a picture of my skillfolder structure, and some screenshots of what is contained in my `SKILL.md`.

<img alt="Skill Folder Structure" />

<img alt="Blogging Skill Markdown" />

You can think of your skill as codifying your workflow. In my skill, I have given references to my writing style, tagging strategy, and a small python script to create a new post using the Hugo framework conventions. The `SKILL.md` file acts as the instructions binding everything together.

<Tip>
  Skills capture personal preferences, so what works for me may not work for you and how you architect your skills depends on **your** workflow. You may choose to keep your voice in a standalone skill and then have a blog post creation skill as a separate skill. I combined them in my example because that's what works for me.
</Tip>

### 3. Import your custom skill into Alter

Once your skill is created, add it first to Alter then to your blogging workspace.

<Steps>
  <Step title="Open Tools Manager">
    In Alter's notch menu, find the **Tools Manager** section (or **Shift + , Cmd + T**)
  </Step>

  <Step title="Import the skill">
    In the Tools Manager, select "Agent Skills" and then "Import Skill". Select the directory where your skill is located. This is what you created in the previous stage.

    <img alt="import skill" />
  </Step>

  <Step title="Open workspace settings">
    Back in the Hub, find your "Blogging Workspace" and open it
  </Step>

  <Step title="Add the skill">
    Look for an option to add capability. Select your newly created skill.

    <img alt="add capability" />

    <img alt="add custom skill" />
  </Step>

  <Step title="Verify the skill is active">
    Confirm that your skill is now mounted in this workspace

    <img alt="skill enabled" />
  </Step>
</Steps>

### 4. Create a mode to activate everything instantly

Modes let you switch your entire setup (workspace + skills) with a single hotkey.

<Steps>
  <Step title="Open Action Editor settings">
    In Alter's notch menu, find the **Action Editor** section (or **Shift + , Cmd + E**)
  </Step>

  <Step title="Create a new mode">
    Click **+** to create a new action.
  </Step>

  <Step title="Configure the mode">
    * **Name:** "Blogging Mode" (or whatever feels right)
    * **Mode:** Enable
    * **Workspace:** Select your "Blogging Workspace"
    * **Hotkey/Trigger:** Assign a memorable shortcut (e.g., `Cmd + Shift + B`)
      <img alt="Tool Manager Add Mode" />
  </Step>

  <Step title="Save">
    Save the mode. Now you can activate it anytime with your hotkey.
  </Step>
</Steps>

### 5. Use your workflow

Now everything is wired up. Here's how you actually use it:

**Your writing process:**

1. **Dictate or draft** your raw thoughts in Obsidian, Notes, or a text editor
2. **Activate Blogging Mode** by pressing your mode hotkey (e.g., `Cmd + Shift + B`)
3. **Switch to Alter** and ask something like:
   > "Using this dictated outline, create a blog post in my style."
4. **Paste or reference your draft** as context (using `@` to link files or drag content in)
5. **Review the output** - it should sound like you, follow your format, and have proper depth
6. **Copy and publish** to your blog platform

<img alt="final output" />

## Why this pattern scales

**You're not relying on Alter's guesses anymore.** Because Alter has your actual writing samples and tone guidelines, it doesn't need to infer your voice. It follows it.

**Consistency becomes automatic.** Your skill keeps your voice consistent across every piece of content, whether you're writing a blog post, social copy, or documentation. No more manual editing to fix the tone.

**You actually have time to write more.** Without the overhead of re-explaining your style or endlessly editing generic AI output, you can focus on the thinking part - the ideas - and let Alter handle the execution.

**This works for any content type.** Blog posts, marketing copy, internal docs, social posts - anywhere your voice matters, this pattern works. Just create a different skill if you need a different voice.

## Key learnings

1. **LLMs are voice-agnostic.** They don't know you. Teaching them who you are isn't optional if you want to scale - it's essential.

2. **Skills are how you teach them persistently.** A skill with examples beats re-explaining yourself every time. It's the difference between having a reference and starting from scratch.

3. **Context multiplies what the skill can do.** When your workspace links to your actual project folder, Alter understands your structure, your file naming, your conventions. It's not just guessing anymore - it's working with real information about your ecosystem.

4. **Modes reduce friction to zero.** One hotkey to load everything means the tool gets out of your way. You can focus on thinking, not setup.

5. **Start with one skill, then expand.** Build your primary voice skill first (your blog, your main writing). Test it, refine it. Once that's solid, create skills for other contexts (marketing, technical docs, social) where you need different voices.

## Troubleshooting and refinement

**Skill doesn't sound like me:**

* Add more diverse writing samples to the skill
* Be more specific about tone (not just "conversational" - what does that mean in your context?)
* Update the skill instructions to emphasize your samples as the reference

**Taking too long to review output:**

* Your skill's instructions might be too vague. Tighten the guidelines.
* Provide more structured input (bullet outline vs. rambling notes)
* Your raw content might need more detail for the skill to work with

**Skill isn't respecting my format:**

* Add explicit formatting rules to the skill
* Include a correctly formatted example post in the skill's context

## Next steps

* **Build your first skill:** Start with 2–3 examples that best represent your voice
* **Test the workflow:** Create one post using this pattern, then refine based on what worked
* **Expand gradually:** Once blogging is solid, apply the same pattern to other content (marketing, docs, social)
* **Read more:**
  * [Skill creation documentation](https://resources.anthropic.com/hubfs/The-Complete-Guide-to-Building-Skill-for-Claude.pdf?hsLang=en) – Complete guide to building skills
  * [Alter Workspaces](/getting-started/workspaces-basics) – How workspaces organize your context
  * [Dictation Guide](/workflows/dictation) – Voice capture to feed your skill (Note: this page also covers "Dictation Modes" which are different from Alter "Modes")


# Connect Exa
Source: https://docs.alterhq.com/workflows/connect-exa

Use Exa in Alter for web search workflows

Exa is a search-focused provider you can use with Alter through MCP-style integrations.

## How Exa positions itself

* "The best search API for AI"
* Quality-first positioning with benchmark-driven messaging
* One API covering search, contents, answer, crawl, and research-style workflows
* Emphasis on low-latency retrieval and enterprise controls

## Where to connect

* **Remote MCP Servers**
* **Apps Gallery** (if available in your workspace)

## Connect Exa

1. Open **Tools Manager**.
2. Add Exa in **Remote MCP Servers** or connect from **Apps Gallery**.
3. Paste your API key.
4. Enable the connector.

## Free tier

* Exa is often described with a free tier around **1,000 requests per month**.

<Warning>
  Verify Exa pricing and request limits during setup. Free tiers can change.
</Warning>

## Example prompts

* "Find the best primary sources on this topic from the past 30 days."
* "Search recent technical posts about this API and extract migration notes."

## Official links

* [https://exa.ai/](https://exa.ai/)
* [https://exa.ai/docs](https://exa.ai/docs)


# Connect Firecrawl
Source: https://docs.alterhq.com/workflows/connect-firecrawl

Use Firecrawl with Alter for structured multi-page scraping

Firecrawl is best when you need structured extraction from many pages instead of one-off search snippets.

## How Firecrawl positions itself

* "Turn websites into LLM-ready data"
* Developer-first web data API with scrape, crawl, map, search, and agent flows
* Strong focus on reliability for JavaScript-heavy pages and production scraping
* Open-source core with a hosted product for managed scale

## Why use Firecrawl

* Strong for scraping and structured data extraction
* Works well for multi-page websites and recurring crawls
* Useful when your output needs consistent fields

## Connect from Apps Gallery

1. Open **Tools Manager**.
2. Go to **Apps Gallery**.
3. Find **Firecrawl** and connect it.
4. Enter your API key and required settings.

## Free tier

* Firecrawl offers a free plan.

<Warning>
  Verify current Firecrawl limits, rate caps, and retention before scaling usage.
</Warning>

## Example prompts

* "Scrape these 25 pages and extract title, author, publish date, and main topic."
* "Crawl this docs section and return all endpoints with method and path."

## Official links

* [https://firecrawl.dev/](https://firecrawl.dev/)
* [https://docs.firecrawl.dev/](https://docs.firecrawl.dev/)


# Connect LinkUp
Source: https://docs.alterhq.com/workflows/connect-linkup

Set up LinkUp in Alter through Apps Gallery or Remote MCP

LinkUp is easy to connect and useful for both standard search and deeper research workflows.

## How LinkUp positions itself

* "World's best search for AI apps"
* Focus on factual grounding with sourced answers and trusted content
* Two clear modes: fast standard search and deeper multi-step research
* Strong positioning for business workflows like enrichment, answer engines, and GTM research

## Connection options

* **Apps Gallery** integration
* **Remote MCP Server** with API key

## Connect LinkUp

1. Open **Tools Manager**.
2. Connect LinkUp from **Apps Gallery** or add it in **Remote MCP Servers**.
3. Paste your API key.
4. Enable the connector.

## Free tier

* LinkUp is commonly presented with **1,000 standard requests** and **100 deep research requests** on its free plan.

<Warning>
  Confirm current LinkUp quotas and terms on the official pricing page.
</Warning>

## Example prompts

* "Run a deep research pass on this market and return sources plus confidence notes."
* "Track updates on these five companies and summarize what changed this week."

## Official links

* [https://www.linkup.so/](https://www.linkup.so/)
* [https://docs.linkup.so/](https://docs.linkup.so/)


# Connect Tavily
Source: https://docs.alterhq.com/workflows/connect-tavily

Connect Tavily as a Remote MCP Server for web research and extraction

Tavily is a strong option for web research, information extraction, and crawling page structures.

## How Tavily positions itself

* A web access layer for AI agents
* One API for real-time search, extraction, research, and crawling
* Built for model grounding with fresh web context and structured output
* Enterprise-oriented messaging around security, privacy, and reliability

## Why use Tavily

* Good balance between search quality and extraction depth
* Useful for scraping-style workflows and site traversal
* Simple API-key based setup in **Remote MCP Servers**

## Connect Tavily

1. Open **Tools Manager**.
2. Go to **Remote MCP Servers**.
3. Add the Tavily server.
4. Paste your Tavily API key.
5. Enable the connector.

## Free tier

* Tavily is commonly offered with around **1,000 free credits per month**.

<Warning>
  Verify current Tavily pricing and limits before production use. Provider plans can change.
</Warning>

## Example prompts

* "Research the latest browser automation frameworks and provide a ranked summary."
* "Extract key pricing fields from these product pages and return a table."
* "Traverse this docs site and list all pages about authentication."

## Official links

* [https://tavily.com/](https://tavily.com/)
* [https://docs.tavily.com/](https://docs.tavily.com/)


# Dictation
Source: https://docs.alterhq.com/workflows/dictation

Voice commands, speech-to-text, and advanced dictation features

<Info>
  **Speak naturally, work faster.** Alter's dictation goes beyond simple transcription with intelligent voice commands and text transformation.
</Info>

## Voice Triggers

Voice Triggers let you activate any Alter Action using just your voice. Say a magic word or phrase to instantly trigger configured actions.

### How Voice Triggers Work

<Steps>
  <Step title="Set up triggers">
    In the Action Editor, assign a trigger word or phrase to any Alter Action
  </Step>

  <Step title="Hold to speak">
    Hold your voice hotkey (default: `Fn` key) or the mic icon
  </Step>

  <Step title="Say the trigger">
    Speak your trigger word or phrase (e.g., "Hey Charlie", "Hey Google")
  </Step>

  <Step title="Release">
    Let go of the hotkey – the action fires immediately
  </Step>
</Steps>

### Practical Examples

<CardGroup>
  <Card title="Personal Assistant" icon="user">
    "Hey Charlie" – Start a conversation with your Mental Model expert
  </Card>

  <Card title="Web Search" icon="search">
    "Hey Google" – Trigger a web search action
  </Card>

  <Card title="Translation" icon="languages">
    "Hey Translate" – Activate your translation action
  </Card>

  <Card title="Custom Actions" icon="wand">
    Create triggers for any frequently-used action
  </Card>
</CardGroup>

### Setting Up Voice Triggers

<Frame>
  <div>
    <iframe title="YouTube video player" />
  </div>
</Frame>

<Steps>
  <Step title="Open Action Editor">
    From the Alter menu, select "Action Editor"
  </Step>

  <Step title="Choose an Action">
    Select the action you want to trigger by voice
  </Step>

  <Step title="Add Voice Trigger">
    In the action settings, add your trigger word or phrase
  </Step>

  <Step title="Test It Out">
    Hold your voice hotkey and say the trigger word to activate
  </Step>
</Steps>

### Best Practices

<AccordionGroup>
  <Accordion icon="ruler" title="Keep triggers short">
    2-3 words work best for quick recognition
  </Accordion>

  <Accordion icon="fingerprint" title="Make them unique">
    Avoid common phrases you might say in conversation
  </Accordion>

  <Accordion icon="volume-2" title="Use clear pronunciation">
    Choose words that are easy to say and distinguish
  </Accordion>

  <Accordion icon="layers" title="Combine with context">
    Voice triggers work great with text selections or current app context
  </Accordion>
</AccordionGroup>

<Note>
  Voice triggers use speech-to-prompt (hold to speak), making them perfect for quick voice-activated workflows.
</Note>

***

## Dictation Modes

<Tabs>
  <Tab title="Speech-to-Prompt">
    **Perfect for quick voice commands:**

    1. **Hold** your configured hotkey (default: `Fn` key) or mic icon
    2. **Speak** your command naturally
    3. **Release** to process immediately

    <Tip>
      The currently active window is automatically selected as context.
    </Tip>
  </Tab>

  <Tab title="Dictation Mode">
    **Ideal for longer text input:**

    1. **Click once** on the mic icon to start dictation
    2. **Speak** your content
    3. **Click again** to stop and process

    <Info>
      Perfect for drafting emails, documents, or longer prompts.
    </Info>
  </Tab>
</Tabs>

***

## Voice-Powered Text Transformation

Transform any selected text using voice commands:

<Steps>
  <Step title="Select text">
    Select text anywhere on your Mac
  </Step>

  <Step title="Hold and speak">
    Hold the record button (or `Fn` key)
  </Step>

  <Step title="Give command">
    Speak transformation commands like:
  </Step>
</Steps>

### Example Commands

<CardGroup>
  <Card title="Tone Changes" icon="palette">
    "Rewrite in friendly tone"<br />
    "Make this more professional"
  </Card>

  <Card title="Content Expansion" icon="expand">
    "Create counter arguments"<br />
    "Add my thoughts: \[input]"
  </Card>

  <Card title="Translation" icon="languages">
    "Translate to Spanish"<br />
    "Convert to French"
  </Card>

  <Card title="Formatting" icon="type">
    "Format as bullet points"<br />
    "Make this a summary"
  </Card>
</CardGroup>

<Info>
  **System-wide power:** This feature works with any text selection, making it incredibly useful for editing documents, emails, or any text content.
</Info>

***

## Language Settings

### Automatic Language Detection

When set to "Automatic," Alter detects the language you're speaking and processes it accordingly.

<Note>
  Auto-detection doesn't work with all languages and depends on the underlying engine. Set your language explicitly if you have accuracy issues.
</Note>

### Custom Word Recognition

Add technical terms and vocabulary to improve recognition:

<Steps>
  <Step title="Open Settings">
    Go to **Settings > Dictation > Dictionary**
  </Step>

  <Step title="Add words">
    Enter words separated by commas
  </Step>

  <Step title="Save">
    Changes apply immediately
  </Step>
</Steps>

<Card title="When to Use" icon="book">
  * Acronyms and abbreviations
  * Company and product names
  * Technical terminology
  * Proper nouns
  * Industry-specific jargon
</Card>

### Dictation Replacements

Automatically transform words and phrases during dictation:

<AccordionGroup>
  <Accordion icon="settings" title="How to Set Up">
    1. Navigate to **Settings > Voice > Replacements**
    2. Create pairs of "spoken phrase" → "written text"
    3. Replacements apply automatically at the end of dictation
  </Accordion>

  <Accordion icon="list" title="Practical Examples">
    | Spoken         | Written          |
    | -------------- | ---------------- |
    | "altair"       | "Alter"          |
    | "CTA"          | "call-to-action" |
    | "discord link" | Full Discord URL |
    | "jay son"      | "JSON"           |
  </Accordion>
</AccordionGroup>

<CardGroup>
  <Card title="Technical Writing" icon="code">
    Fix misheard code terms
  </Card>

  <Card title="Professional" icon="briefcase">
    Standardize company names
  </Card>

  <Card title="Personal" icon="user">
    Voice shortcuts for signatures
  </Card>
</CardGroup>

<Note>
  Replacements apply to both regular dictation and speech-to-prompt, ensuring consistency across all voice input.
</Note>

***

## Processing Options

Choose how Alter processes your voice input:

<CardGroup>
  <Card title="Cloud Processing" icon="cloud">
    **Highest accuracy**, fast processing<br />
    Uses cloud-based speech recognition<br />
    <span>Best for: Most users, accuracy-critical work</span>
  </Card>

  <Card title="Local (Apple)" icon="apple">
    **Privacy-focused**, on-device<br />
    Uses Apple's speech recognition<br />
    <span>Best for: Privacy-conscious users</span>
  </Card>

  <Card title="Local (Whisper)" icon="cpu">
    **Maximum privacy**, OpenAI Whisper<br />
    Runs locally, speed depends on model<br />
    <span>Best for: Offline work, sensitive content</span>
  </Card>

  <Card title="Whisper Pro" icon="zap">
    **Advanced local processing**<br />
    10-second transcripts for any length<br />
    <span>Best for: Meetings, long recordings</span>
  </Card>
</CardGroup>

### Whisper Pro Setup

Get meeting transcripts in just **10 seconds** regardless of length:

<Steps>
  <Step title="Open Settings">
    Navigate to **Settings > Dictation**
  </Step>

  <Step title="Select Whisper Pro">
    In the **Voice Processor** dropdown, choose "Whisper Pro"
  </Step>

  <Step title="Choose model">
    We recommend **Whisper Large V3** (626MB) for optimal speed/accuracy
  </Step>

  <Step title="Download">
    Click **Download** and wait for completion
  </Step>
</Steps>

<Tip>
  **Perfect for:** Back-to-back meetings, high-volume meeting days, offline transcription needs
</Tip>

***

## Configuration

### Global Voice Hotkey

| Setting  | Default          | Options             |
| -------- | ---------------- | ------------------- |
| **Key**  | `Fn`             | Any key combination |
| **Hold** | Speech-to-prompt | Quick commands      |
| **Tap**  | Dictation mode   | Longer input        |

Customize in **Settings > Dictation > Shortcut**

### Clipboard Integration

When enabled, dictated text is automatically copied to your clipboard for easy pasting into any application.

<Steps>
  <Step title="Open Settings">
    Go to **Settings > Dictation**
  </Step>

  <Step title="Enable clipboard">
    Toggle "Copy to clipboard" option
  </Step>
</Steps>

***

## Related Resources

<CardGroup>
  <Card title="Meetings" icon="users" href="/workflows/meetings">
    Record and transcribe meetings
  </Card>

  <Card title="Settings" icon="settings" href="/how-to/settings-guide">
    Configure dictation options
  </Card>

  <Card title="Keyboard Shortcuts" icon="keyboard" href="/references/shortcuts">
    Voice hotkey reference
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/common-issues/mic-not-transcribing">
    Fix microphone issues
  </Card>
</CardGroup>


# Keep Your Data Private with Local AI
Source: https://docs.alterhq.com/workflows/local-model-privacy

How to run AI models on your own Mac for sensitive documents and confidential work

<Info>
  **Perfect for:** Lawyers, doctors, security researchers, or anyone working with sensitive data who doesn't want it leaving their computer.
</Info>

## The Concern

You're working with:

* Client confidential information
* Medical records
* Proprietary business data
* Personal financial documents
* Security research

And you're worried about sending this data to cloud AI services like OpenAI or Google, even if they claim it's private.

**The good news:** You don't have to. You can run AI models directly on your Mac.

## How Local Models Work

Instead of sending your data to the internet, you download an AI model to your Mac (like downloading a large app) and run it locally. Your data never leaves your computer.

<CardGroup>
  <Card title="100% Private" icon="shield-check">
    Nothing sent to the cloud. Your data stays on your Mac.
  </Card>

  <Card title="Works Offline" icon="wifi-slash">
    Use AI on airplanes, in secure facilities, or anywhere without internet.
  </Card>

  <Card title="No API Costs" icon="money-bill">
    Once downloaded, no per-use fees. Analyze thousands of documents for free.
  </Card>

  <Card title="Faster for Big Files" icon="bolt">
    No upload/download time. Great for large documents.
  </Card>
</CardGroup>

## Setup: Two easy options

### Option 1: Ollama (Recommended for beginners)

Ollama makes running local models as simple as installing an app.

<Steps>
  <Step title="Install Ollama">
    1. Download from [ollama.com](https://ollama.com)
    2. Install it like any Mac app
    3. It runs in your menu bar
  </Step>

  <Step title="Download a model">
    Open Terminal and run:

    ```bash theme={null}
    ollama pull llama3.1
    ```

    This downloads Meta's Llama 3.1 model (\~4.7GB). Other good options:

    * `ollama pull mistral` (faster, smaller)
    * `ollama pull codellama` (great for code)
    * `ollama pull mixtral` (more capable, larger)
  </Step>

  <Step title="Connect to Alter">
    1. Open Alter → Settings (`Cmd + ,`)
    2. Go to **API Keys** tab
    3. Under **Custom Provider**, select **Ollama**
    4. Make sure Ollama is running (check your menu bar)
    5. Toggle **Enable Custom Provider** ON
  </Step>

  <Step title="Start using it">
    1. Press `/` in Alter's prompt box
    2. Look for the **Custom** section
    3. Select your local model (e.g., "llama3.1")
    4. Ask anything – it runs entirely on your Mac!
  </Step>
</Steps>

### Option 2: LM Studio (More control)

LM Studio gives you a graphical interface to manage models.

<Steps>
  <Step title="Install LM Studio">
    Download from [lmstudio.ai](https://lmstudio.ai) and install it.
  </Step>

  <Step title="Download a model">
    1. Open LM Studio
    2. Browse the model catalog
    3. Download one that fits your needs and Mac's specs
    4. Start the local server (big "Start Server" button)
  </Step>

  <Step title="Connect to Alter">
    1. In Alter Settings → **API Keys**
    2. Select **LM Studio** as the provider
    3. LM Studio runs on `localhost:1234` by default
    4. Toggle **Enable Custom Provider** ON
  </Step>
</Steps>

## Real-world example

**Dr. Chen, physician:**

> "I need to analyze patient notes for research, but I can't use cloud AI due to HIPAA. With a local model, I can ask 'What patterns do you see in these symptoms?' and get AI assistance while keeping everything on my secure laptop."

**Alex, security researcher:**

> "I analyze malware reports and can't upload them anywhere. Running a local model means I can ask 'What indicators of compromise are mentioned?' without risking data exposure."

## Trade-offs to know about

<AccordionGroup>
  <Accordion icon="gauge" title="Speed vs Privacy">
    **Cloud models:** Faster, more capable
    **Local models:** Slower, but completely private

    A MacBook Pro with 16GB RAM can run small models smoothly. For larger models, you'll want 32GB+ RAM.
  </Accordion>

  <Accordion icon="brain" title="Capability differences">
    Local models are getting better every month, but cloud models (GPT-4, Claude) are still more capable for complex reasoning.

    **Best approach:** Use local models for sensitive data, cloud models for less sensitive complex tasks.
  </Accordion>

  <Accordion icon="hard-drive" title="Storage requirements">
    Models range from 4GB to 70GB+. Make sure you have enough disk space.

    **Good starter models:**

    * Llama 3.1 8B (\~4.7GB) – Fast, decent quality
    * Mistral 7B (\~4.1GB) – Good balance
    * Mixtral 8x7B (\~26GB) – Higher quality, needs more RAM
  </Accordion>
</AccordionGroup>

## Best practices for private workflows

<Tip>
  **Use specific Actions for sensitive tasks:** Create Alter Actions configured to always use your local model. That way you never accidentally use a cloud model for sensitive work.
</Tip>

<Tip>
  **Set up a privacy workspace:** Create a workspace just for sensitive documents. This keeps them organized and reminds you to use local models.
</Tip>

<Tip>
  **Verify it's working:** After setting up, disconnect from WiFi and try using Alter. If it still works with your local model, you know it's truly local.
</Tip>

## When to use what

| Scenario           | Recommendation                           |
| ------------------ | ---------------------------------------- |
| Medical records    | Local model (Ollama/LM Studio)           |
| Legal documents    | Local model                              |
| Security research  | Local model                              |
| Financial analysis | Local model or Alter Cloud with Pro plan |
| Creative writing   | Cloud models (better creativity)         |
| General questions  | Cloud models (faster)                    |
| Code assistance    | Either works well                        |

## Related resources

* [How to use your own API key](/how-to/use-byok) – Step-by-step setup guide
* [How to access settings](/how-to/settings-guide) – Open settings and configure providers
* [General FAQ](/references/general-faq) – Model and provider basics

***

**Ready to go private?** Start with Ollama and the Llama 3.1 model. It's free, easy to set up, and you'll have AI assistance that never leaves your Mac!


# Manage your schedule with Alter
Source: https://docs.alterhq.com/workflows/manage-calendar-with-alter

What Alter can do with Apple Calendar, when to use it, and prompts you can copy

This workflow helps you run your agenda from conversation instead of manually editing Calendar all day.

## What this helps you do

When you are planning your day, adding meetings from chat, or cleaning up old events, Alter can handle those actions directly in Apple Calendar. You can think of it as an assistant that keeps your schedule consistent while you stay focused on work.

## Works with

* App: Apple Calendar
* Tool type: Local tool
* Permissions: Calendars

## What Alter can do today

Alter can list calendars and events, create new events, update existing ones, and remove events. In practice, the best flow is to first ask for a quick schedule view, then ask for changes in follow-up prompts.

## What Alter cannot do yet

Alter may ask a follow-up question when multiple events have similar titles. To avoid ambiguity, include clear date and time details in your prompt.

## A realistic workflow

<Steps>
  <Step title="Start with visibility">
    Ask Alter to show your events for today or tomorrow.
  </Step>

  <Step title="Apply changes">
    Ask Alter to create, move, or remove events based on what you see.
  </Step>

  <Step title="Verify final schedule">
    Ask for the updated event list so you confirm everything is in place.
  </Step>
</Steps>

## Copy/paste prompts

* "Show my events for tomorrow."
* "Create a 45-minute event called 'Design review' tomorrow at 14:00 in my Work calendar."
* "Move my 'Design review' event to 15:00 and keep the same duration."
* "List my events from 2026-03-06 to 2026-03-10."
* "Remove the 'Design review' event tomorrow."

## How to enable

<Steps>
  <Step title="Enable Calendar in Tools Manager">
    Open Alter -> click the three dots -> **Tools Manager** -> **Local Tools** -> enable **Calendar**.
  </Step>

  <Step title="Allow Calendar permission">
    On first use, macOS asks for permission. Allow access to Calendars for Alter.
  </Step>

  <Step title="Run a quick test">
    Ask: "Show my events for tomorrow." If it returns events, you are ready.
  </Step>
</Steps>

## What to expect

* If multiple events share similar titles, Alter may ask you to confirm which one to edit or remove.
* You get best results when your prompt includes date, time, and calendar name.

## Related pages

* [Calendar app capabilities](/apps-tools/calendar)
* [Stay on top of tasks with Alter](/workflows/manage-reminders-with-alter)
* [Use Tool Manager](/how-to/tool-manager-guide)


# Manage contacts with Alter
Source: https://docs.alterhq.com/workflows/manage-contacts-with-alter

What Alter can currently do with Apple Contacts, with practical prompts and setup

This workflow helps you keep your contact book accurate before messaging, emailing, or planning follow-ups.

## What this helps you do

Use Alter to clean and maintain contact data while you work. You can search people quickly, add missing details, and keep groups organized without opening Contacts for every edit.

## Works with

* App: Apple Contacts
* Tool type: Local tool
* Permissions: Contacts

## What Alter can do today

Alter can find contacts by name/email/phone, list contacts by group, create new contacts, update existing records, and delete contacts with explicit confirmation.

## What Alter cannot do yet

Update and delete actions are ID-based behind the scenes, so the best user flow is usually lookup first, then edit/delete.

## A realistic workflow

<Steps>
  <Step title="Find the person first">
    Ask Alter to find the contact by name.
  </Step>

  <Step title="Apply updates">
    Add missing phone/email/company details or assign group info.
  </Step>

  <Step title="Use contact in next action">
    Reuse that contact for Mail, Messages, or planning workflows.
  </Step>
</Steps>

## Copy/paste prompts

* "Find contact Sarah Martin."
* "List 20 contacts in the Work group."
* "Create contact: first name Alex, last name Chen, work email [alex@company.com](mailto:alex@company.com), mobile +33612345678."
* "Update contact \[contact id] and add work email [alex.chen@company.com](mailto:alex.chen@company.com)."
* "Delete contact \[contact id] and confirm yes."

## How to enable

<Steps>
  <Step title="Enable Contacts in Tools Manager">
    Open Alter -> click the three dots -> **Tools Manager** -> **Local Tools** -> enable **Contacts**.
  </Step>

  <Step title="Allow Contacts permission">
    On first use, macOS asks for Contacts access. Allow access for Alter.
  </Step>

  <Step title="Run a quick test">
    Ask: "Find contact John." If results appear, setup is complete.
  </Step>
</Steps>

## What to expect

* Many actions work best after a lookup step because updates/deletes use contact IDs.
* Deletion is protected by explicit confirmation (`confirm yes`).

## Related pages

* [Contacts app capabilities](/apps-tools/contacts)
* [Send iMessages faster](/workflows/send-messages-with-alter)
* [Check unread emails and draft replies](/workflows/manage-mail-with-alter)


# Check unread emails and draft replies with Alter
Source: https://docs.alterhq.com/workflows/manage-mail-with-alter

What Alter can currently do with Apple Mail, with practical prompts and setup

This workflow is for lightweight mail support: seeing unread messages and preparing drafts quickly.

## What this helps you do

If you want a fast inbox check and a ready-to-review draft, Apple Mail local tools are enough. It is best for "read + draft" moments, not full mailbox automation.

## Works with

* App: Apple Mail
* Tool type: Local tool
* Permissions: Mail automation

## What Alter can do today

Alter can list unread messages across mailboxes and generate a new draft email in Mail with the context you provide.

## What Alter does not do yet

* It cannot reply directly inside an existing email thread.
* It cannot send an email automatically from this tool (it creates drafts for review).
* It cannot delete, archive, label, or bulk-process emails.

## When to use Gmail or Outlook integrations instead

If you need advanced email workflows (thread-aware replies, send actions, labeling, archiving, rules, and broader mailbox automation), use external integrations like Gmail or Outlook from the Integrations catalog.

## Typical workflows

### Quick inbox check

Ask for a short unread list, identify priority messages, then open Mail for final handling.

### Draft first reply fast

Ask Alter to draft a response to a specific recipient, then review and send from Mail.

## A realistic workflow

<Steps>
  <Step title="Scan unread mail">
    Ask Alter to show 5-10 unread emails so you can prioritize.
  </Step>

  <Step title="Draft response">
    Ask Alter to create a draft for the top message.
  </Step>

  <Step title="Review and send">
    Open the draft in Mail, edit if needed, then send manually.
  </Step>
</Steps>

## Copy/paste prompts

* "Show my 10 latest unread emails."
* "Show only 5 unread emails so I can triage quickly."
* "Draft an email to [alex@company.com](mailto:alex@company.com) with subject 'Q2 Planning' and summarize our next steps."
* "Create a draft reply to this contact saying I can do Thursday at 3 PM."

## How to enable

<Steps>
  <Step title="Enable Mail in Tools Manager">
    Open Alter -> click the three dots -> **Tools Manager** -> **Local Tools** -> enable **Mail**.
  </Step>

  <Step title="Allow Mail automation">
    On first use, macOS may ask permission for Alter to control Mail. Allow it.
  </Step>

  <Step title="Run a quick test">
    Ask: "Show my 5 unread emails." Then ask Alter to create one draft email.
  </Step>
</Steps>

## What to expect

* Unread listing is preview-oriented: you get enough context to decide what to open in Mail.
* For drafts, you stay in control: Alter prepares the draft, and you send it after review.

## Related pages

* [Mail app capabilities](/apps-tools/mail)
* [Integrations overview](/apps-tools/integrations-overview)
* [Use Tool Manager](/how-to/tool-manager-guide)


# Capture and organize notes with Alter
Source: https://docs.alterhq.com/workflows/manage-notes-with-alter

What Alter can do with Apple Notes, when to use it, and prompts you can copy

This workflow helps you turn conversations into structured notes and keep your Notes app organized over time.

## What this helps you do

Use it when you want to capture meeting output quickly, retrieve knowledge without manual searching, and keep folders clean. Alter works well as your "notes operator": you tell it what you need, it handles create/search/update/move actions.

## Works with

* App: Apple Notes
* Tool type: Local tool
* Permissions: Automation (Alter -> Notes)

## What Alter can do today

Alter can create notes from chat context, search by topic, open full note content, update notes, remove old notes, create folders, and move notes between folders.

## What Alter cannot do yet

When note titles are similar, Alter may need a confirmation step to target the right note. Including unique keywords or folder names gives more reliable results.

## A realistic workflow

<Steps>
  <Step title="Capture the output">
    Ask Alter to create a note from your meeting or brainstorming discussion.
  </Step>

  <Step title="Find and refine">
    Later, ask Alter to search that topic and update the note with new details.
  </Step>

  <Step title="Organize">
    Move the note to the right folder so your knowledge base stays clean.
  </Step>
</Steps>

## Copy/paste prompts

* "Create a note called 'Release checklist' with the key steps we just discussed."
* "Search my notes for 'Q1 roadmap' and show the most relevant results."
* "Open the full content of the note about onboarding docs."
* "Update the 'Release checklist' note with a new section for QA sign-off."
* "Move this note to my Product folder."
* "Delete my old draft note called 'Temp ideas'."

## How to enable

<Steps>
  <Step title="Enable Notes in Tools Manager">
    Open Alter -> click the three dots -> **Tools Manager** -> **Local Tools** -> enable **Notes**.
  </Step>

  <Step title="Allow Notes automation">
    On first use, macOS asks for Automation permission. Allow Alter to control Notes.
  </Step>

  <Step title="Run a quick test">
    Ask: "Search my notes for project updates." If results appear, setup is complete.
  </Step>
</Steps>

## What to expect

* Alter may need one extra step to confirm the exact note when names are similar.
* For best results, include a unique keyword or folder name in your prompt.

## Related pages

* [Notes app capabilities](/apps-tools/notes)
* [Summarize your X feed with Computer Use](/workflows/summarize-x-feed-with-computer-use)
* [Use Tool Manager](/how-to/tool-manager-guide)


# Stay on top of tasks with Alter
Source: https://docs.alterhq.com/workflows/manage-reminders-with-alter

What Alter can do with Apple Reminders, when to use it, and prompts you can copy

This workflow helps you capture tasks in real time and keep your reminder lists up to date without manual cleanup.

## What this helps you do

Use Alter when tasks appear in conversation and you want immediate follow-through. It is useful for daily review, weekly planning, and keeping lists clean as priorities change.

## Works with

* App: Apple Reminders
* Tool type: Local tool
* Permissions: Reminders

## What Alter can do today

Alter can create reminders, list upcoming tasks by date or list, mark items completed, reschedule tasks, move tasks across lists, delete reminders, and create new reminder lists.

## What Alter cannot do yet

If several reminders have similar titles, Alter may ask you to clarify which one to update or remove. Including list name and due date in your prompt gives more deterministic results.

## A realistic workflow

<Steps>
  <Step title="Capture tasks as they appear">
    Ask Alter to create reminders during meetings or chats.
  </Step>

  <Step title="Run a daily review">
    Ask for what is due today and this week, then reprioritize.
  </Step>

  <Step title="Close the loop">
    Mark completed items and move postponed tasks to the right date/list.
  </Step>
</Steps>

## Copy/paste prompts

* "Create a reminder 'Send invoice' due tomorrow at 09:00 in my Admin list."
* "Show my reminders due this week in Personal."
* "Mark 'Send invoice' as completed."
* "Move 'Book dentist appointment' to my Personal list and set it for next Monday at 10:00."
* "Create a reminder list called 'Home Ops'."
* "Delete the reminder 'Old follow-up task'."

## How to enable

<Steps>
  <Step title="Enable Reminders in Tools Manager">
    Open Alter -> click the three dots -> **Tools Manager** -> **Local Tools** -> enable **Reminders**.
  </Step>

  <Step title="Allow Reminders permission">
    On first use, macOS asks for Reminders permission. Allow access for Alter.
  </Step>

  <Step title="Run a quick test">
    Ask: "Show my reminders due this week." If you get results, setup is done.
  </Step>
</Steps>

## What to expect

* If several reminders have similar titles, Alter may ask you to clarify which one to update or remove.
* Add list name and due date in your prompt when you want deterministic results.

## Related pages

* [Reminders app capabilities](/apps-tools/reminders)
* [Manage your schedule with Alter](/workflows/manage-calendar-with-alter)
* [Use Tool Manager](/how-to/tool-manager-guide)


# Never Miss Action Items from Meetings
Source: https://docs.alterhq.com/workflows/meeting-workflow

How to automatically record, transcribe, and extract tasks from your meetings

<Info>
  **Perfect for:** Busy professionals, team leads, and anyone who wants to focus on the conversation instead of taking notes.
</Info>

## The Problem

You're in back-to-back meetings all day. By the time you get to the third one, you can't remember:

* What was decided in the first meeting
* Who agreed to do what
* What your actual action items are

You could take notes during meetings, but then you're not fully present in the conversation.

## The Solution: Let Alter Handle It

Alter automatically detects when you're in meetings and creates searchable transcripts with speaker identification. Then you can ask it to extract action items, decisions, and key points.

## Real-world example

**Sarah, Product Manager:**

> "I used to spend 30 minutes after every meeting writing up notes. Now Alter records everything, and I just ask 'What are my action items?' and 'What decisions did we make about the API?' It saves me hours every week."

## How to set it up

<Steps>
  <Step title="Enable auto-recording">
    1. Open Alter Settings (`Cmd + ,`)
    2. Go to **Dictation** tab
    3. Turn on **Auto Record Meetings**
    4. Set the minimum duration (default: 2 minutes)

    Now Alter will automatically detect Zoom, Google Meet, and Teams calls and ask if you want to record.
  </Step>

  <Step title="Choose your transcription quality">
    **Option 1: Cloud Processing** (Fastest, most accurate)

    * Uses online AI for transcription
    * Best accuracy for accents and technical terms

    **Option 2: Whisper Pro** (Private, works offline)

    * Download a local model (recommended: Whisper Large V3)
    * 100% offline processing
    * Great for confidential meetings
  </Step>

  <Step title="Test with a sample meeting">
    1. Join any meeting (even a test Zoom with yourself)
    2. Click **Record** when Alter asks, or manually start recording
    3. Speak for 2-3 minutes
    4. End the meeting
    5. Wait 10 seconds for transcription
  </Step>
</Steps>

## How to extract value from transcripts

Once you have a transcript, try these prompts:

<CardGroup>
  <Card title="Get action items" icon="check-circle">
    "List all the action items from this meeting and who is responsible for each"
  </Card>

  <Card title="Summarize decisions" icon="gavel">
    "What decisions were made? List them with context"
  </Card>

  <Card title="Find specific topics" icon="search">
    "What did we say about the budget/timeline/API?"
  </Card>

  <Card title="Create follow-up email" icon="envelope">
    "Draft a follow-up email summarizing this meeting for the team"
  </Card>
</CardGroup>

## Pro tips

<Tip>
  **Speaker identification:** Alter uses AI to identify different speakers (Speaker 1, Speaker 2, etc.). You can rename them manually after the meeting if you know who they are.
</Tip>

<Tip>
  **Search across all meetings:** All transcripts are searchable. Type `#` in the prompt box to search past meeting content. Ask "What did John say about the roadmap in last week's meetings?"
</Tip>

<Tip>
  **Live captions:** Turn on live captions during meetings (Settings > Voice > Enable Live Captions) to follow along in real-time, especially helpful if audio quality is poor.
</Tip>

## Where your data goes

All transcripts are stored **locally on your Mac** at:

```
~/Library/Application Support/Alter/Transcripts
```

No one else can access them unless you explicitly share them.

## Related features

* [How to access settings](/how-to/settings-guide) – Configure meeting and voice options
* [Troubleshoot mic transcription](/common-issues/mic-not-transcribing) – Fix capture issues
* [Use Tool Manager](/how-to/tool-manager-guide) – Configure tools for follow-up workflows

***

**Ready to try it?** Your next meeting is the perfect time to test this out. Just turn on auto-record and see how much easier your follow-up becomes!


# Meetings
Source: https://docs.alterhq.com/workflows/meetings

Professional meeting transcription with speaker identification and offline processing

<Info>
  **Never take meeting notes again.** Alter records, transcribes, and helps you extract action items automatically.
</Info>

## Automatic Meeting Recording

### Smart Meeting Detection

Alter automatically detects when you join meetings on:

<CardGroup>
  <Card title="Zoom" icon="video">
    Instant detection
  </Card>

  <Card title="Google Meet" icon="google">
    Automatic recognition
  </Card>

  <Card title="Microsoft Teams" icon="users">
    Full support
  </Card>

  <Card title="Other Platforms" icon="more-horizontal">
    Most conferencing apps
  </Card>
</CardGroup>

When a meeting is detected, Alter displays a subtle notification giving you the option to record or skip.

### Auto-Record Settings

<Steps>
  <Step title="Enable auto-record">
    Settings → Dictation → **Auto Record Meetings**
  </Step>

  <Step title="Set threshold">
    Define minimum length (default: 120 seconds)
  </Step>

  <Step title="Configure notifications">
    Choose to skip or record via notification
  </Step>

  <Step title="Enable keep-awake">
    Prevent Mac from sleeping during long meetings
  </Step>
</Steps>

<Frame>
  <img alt="Auto-Record notification" />
</Frame>

### Keep-Awake Functionality

When enabled in **Settings > Voice**, Alter prevents your Mac from sleeping during recordings:

<CardGroup>
  <Card title="Automatic" icon="zap">
    Engages when recording starts
  </Card>

  <Card title="Screen Active" icon="monitor">
    Ensures uninterrupted recording
  </Card>

  <Card title="Smart Release" icon="unlock">
    Automatically releases when done
  </Card>

  <Card title="Toggle Control" icon="toggle-right">
    Enable/disable as needed
  </Card>
</CardGroup>

<Info>
  **Perfect for:** Long conference calls, webinars, presentations where screen sleep would interrupt recording
</Info>

### Manual Recording

You can also manually control recordings:

<Steps>
  <Step title="Start recording">
    Click the mic icon on the notch – it turns into a red recording button
  </Step>

  <Step title="Monitor">
    The mic animates during transcription
  </Step>

  <Step title="Stop">
    Click the red button to finish
  </Step>
</Steps>

***

## Speaker Identification

Alter uses **Pyannote 4 (Community-1)**, state-of-the-art AI for speaker diarization.

<CardGroup>
  <Card title="Perfect ID" icon="check-circle">
    Industry-leading speaker identification
  </Card>

  <Card title="Search by Speaker" icon="search">
    Find specific contributions
  </Card>

  <Card title="Track Input" icon="activity">
    See who said what
  </Card>

  <Card title="Filter Speakers" icon="filter">
    Focus on specific participants
  </Card>

  <Card title="Manual Rename" icon="edit">
    Customize speaker names
  </Card>

  <Card title="100% Offline" icon="shield">
    All processing on your Mac
  </Card>
</CardGroup>

### Fast Transcription with Whisper Pro

<CardGroup>
  <Card title="10-Second Transcripts" icon="zap">
    Complete transcription regardless of meeting length
  </Card>

  <Card title="Local Processing" icon="cpu">
    Maximum privacy, on-device
  </Card>

  <Card title="Cloud Option" icon="cloud">
    Regenerate with cloud for enhanced accuracy
  </Card>

  <Card title="Productivity Boost" icon="trending-up">
    Ideal for back-to-back meetings
  </Card>
</CardGroup>

***

## Live Captions

Live Captions brings real-time transcription to every app on your Mac – like YouTube subtitles, but system-wide.

<Frame>
  <div>
    <iframe title="Live Captions on macOS" />
  </div>
</Frame>

### How It Works

Captions appear instantly as audio plays through any application:

<AccordionGroup>
  <Accordion icon="video" title="Universal Compatibility">
    Works with Zoom, Google Meet, Teams, Safari, podcasts, streaming – any Mac app
  </Accordion>

  <Accordion icon="globe" title="Auto Language Detection">
    Recognizes and transcribes multiple languages automatically
  </Accordion>

  <Accordion icon="shield" title="100% Local">
    All transcription happens on your Mac for complete privacy
  </Accordion>
</AccordionGroup>

### Using Live Captions

**Toggle:** Press `Cmd + Shift + ↓` to show/hide captions

**Requirements:**

<Steps>
  <Step title="Go to Settings">
    Navigate to **Settings > Voice**
  </Step>

  <Step title="Select processor">
    Choose **Local Pro**
  </Step>

  <Step title="Download model">
    Get **Parakeet V3** (recommended for best performance)
  </Step>
</Steps>

### Use Cases

<CardGroup>
  <Card title="Meetings" icon="users">
    Real-time subtitles during video calls
  </Card>

  <Card title="Video Content" icon="play">
    Watch YouTube and streams with captions
  </Card>

  <Card title="Podcasts" icon="headphones">
    Read along with audio content
  </Card>

  <Card title="Accessibility" icon="accessibility">
    Essential for hard-of-hearing users
  </Card>

  <Card title="Language Learning" icon="languages">
    Practice listening comprehension
  </Card>

  <Card title="Note-taking" icon="edit">
    Capture key points visually
  </Card>
</CardGroup>

***

## Managing Transcripts

### Editing Content

<CardGroup>
  <Card title="Fix Errors" icon="edit-3">
    Correct recognition mistakes
  </Card>

  <Card title="Rename" icon="type">
    Better organization with custom titles
  </Card>

  <Card title="Summaries" icon="align-left">
    Customize meeting highlights
  </Card>
</CardGroup>

### Search Capabilities

Search across all transcripts by:

| Search Type   | Example               |
| ------------- | --------------------- |
| **Titles**    | "Q4 Planning"         |
| **Content**   | "budget discussion"   |
| **Speakers**  | "What did Sarah say?" |
| **Summaries** | "action items"        |

### Timestamps & Navigation

<CardGroup>
  <Card title="Jump to Moments" icon="clock">
    Click timestamps to navigate
  </Card>

  <Card title="Visual Timeline" icon="bar-chart-2">
    Navigate long recordings efficiently
  </Card>
</CardGroup>

### Meeting Reports

Generate comprehensive reports with:

<Steps>
  <Step title="Action Items">
    Automatically extracted tasks and follow-ups
  </Step>

  <Step title="Key Decisions">
    Important conclusions and agreements
  </Step>

  <Step title="Speaker Summary">
    Input from each participant
  </Step>
</Steps>

***

## Video Tutorials

### Real-time Meeting Transcripts

<Frame>
  <div>
    <iframe title="YouTube video player" />
  </div>
</Frame>

### Speaker Search & Editable Transcripts

<Frame>
  <div>
    <iframe title="YouTube video player" />
  </div>
</Frame>

### Speaker Identification

<Frame>
  <div>
    <iframe title="YouTube video player" />
  </div>
</Frame>

***

## File Storage

### Location

All recordings and transcripts are stored locally at:

```
~/Library/Application Support/Alter/Transcripts
```

<Info>
  **100% Private:** Everything stays on your Mac. No cloud storage unless you explicitly choose cloud processing.
</Info>

<Warning>
  If you uninstall Alter with a cleanup tool such as CleanMyMac, it can remove your local transcripts and related data. To switch versions, replace the app in `Applications` instead. See [Reinstall or downgrade Alter safely](/how-to/reinstall-or-downgrade-alter).
</Warning>

### Management Options

<CardGroup>
  <Card title="Finder Access" icon="folder">
    Open folder directly from Settings
  </Card>

  <Card title="Built-in Search" icon="search">
    Find transcripts in Alter
  </Card>

  <Card title="Export" icon="download">
    Save or share as needed
  </Card>
</CardGroup>

### Recovery

<Warning>
  **Crashed during recording?** Check `/private/var/folders` and search for files named "recording"
</Warning>

***

## Smart Features

### Context Awareness

Alter provides intelligent suggestions:

<CardGroup>
  <Card title="Recording Prompts" icon="bell">
    Suggests recording when joining meetings
  </Card>

  <Card title="Report Generation" icon="file-text">
    Offers summaries when stopping recordings
  </Card>

  <Card title="Action Extraction" icon="check-square">
    Identifies follow-up tasks automatically
  </Card>
</CardGroup>

### Productivity Enhancements

* **Auto-summaries:** Key points generated automatically
* **Task Tracking:** Extract and organize action items
* **Calendar Integration:** Connect with your schedule

***

## Related Resources

<CardGroup>
  <Card title="Dictation" icon="microphone" href="/workflows/dictation">
    Voice processing options
  </Card>

  <Card title="Settings" icon="settings" href="/how-to/settings-guide">
    Configure meeting recording
  </Card>

  <Card title="Use Case: Meetings" icon="briefcase" href="/workflows/meeting-workflow">
    Complete meeting workflow
  </Card>

  <Card title="Keyboard Shortcuts" icon="keyboard" href="/references/shortcuts">
    Meeting-related shortcuts
  </Card>
</CardGroup>


# Router-native search
Source: https://docs.alterhq.com/workflows/native-web-search-in-alter-routers

Use Fast, Best, Fair, and Light for recent web-backed answers without extra connectors

Alter routers include native web search capabilities. You can get fresh answers without connecting an external provider first.

## Supported routers

* `Fast`
* `Best`
* `Fair`
* `Light`

## How it works

* Ask for recent information, trends, or news.
* Alter routers use web search in the background.
* You get fresher and more context-aware responses.

## Example prompts

* "What changed this week in the open-source browser automation ecosystem?"
* "Give me the latest updates on macOS AI tooling and summarize the impact."

## When to add external connectors

* Add MCP or Apps Gallery providers when you need deeper extraction, repeatable scraping, or provider-specific controls.

<Tip>
  Start with router-native search because it is easy to use and already works well. Add Tavily, Firecrawl, LinkUp, or Exa when you need more control or when you want to build your own deep research tool.
</Tip>


# Plan places and routes with Alter Maps
Source: https://docs.alterhq.com/workflows/plan-places-and-routes-with-alter-maps

What Alter can currently do with Apple Maps, with practical prompts and setup

This workflow helps you go from "Where should I go?" to "How do I get there?" in a few prompts.

## What this helps you do

Use Alter Maps workflows for practical travel decisions: find a place, compare nearby options, and get route guidance quickly.

## Works with

* App: Apple Maps
* Tool type: Local tool
* Permissions: Location (optional, needed for "near me" flows)

## What Alter can do today

Alter can search places by name/address, find nearby places by category, and return directions between two locations with transport mode options.

## What Alter does not do yet

* ETA-specific tool responses are not currently exposed in the active tool set.
* Static map image generation is not currently exposed in the active tool set.

## A realistic workflow

<Steps>
  <Step title="Discover options">
    Ask for nearby places in a category (for example restaurants or pharmacies).
  </Step>

  <Step title="Pick destination">
    Choose one result from the list with address or name.
  </Step>

  <Step title="Get route">
    Ask for directions from your origin to that destination with your preferred transport type.
  </Step>
</Steps>

## Copy/paste prompts

* "Find coffee shops near me."
* "Find hotels near 48.8566, 2.3522 within 5km."
* "Search for 'Gare de Lyon, Paris'."
* "Get driving directions from 10 Downing Street London to Heathrow Airport."
* "Get transit directions from Times Square to JFK Airport."

## How to enable

<Steps>
  <Step title="Enable Maps in Tools Manager">
    Open Alter -> click the three dots -> **Tools Manager** -> **Local Tools** -> enable **Maps**.
  </Step>

  <Step title="Allow Location permission if needed">
    If you ask for nearby places without coordinates, Alter may request Location access.
  </Step>

  <Step title="Run a quick test">
    Ask: "Find restaurants near me." Then ask for directions to one result.
  </Step>
</Steps>

## What to expect

* Place results include practical details (address, phone, and map link when available).
* Nearby search works best with either your current location permission enabled or explicit coordinates.

## Related pages

* [Maps app capabilities](/apps-tools/maps)
* [Use Tool Manager](/how-to/tool-manager-guide)
* [Tools Not Working](/common-issues/tool-not-working)


# Send iMessages faster with Alter
Source: https://docs.alterhq.com/workflows/send-messages-with-alter

What Alter can currently do with Messages, with practical prompts and setup

This workflow is for quick outbound iMessages when you already know who to contact and what to say.

## What this helps you do

Use it for fast status updates, scheduling confirmations, or short follow-ups. Instead of switching apps and typing manually, you can send the message from the conversation flow.

## Works with

* App: Messages (iMessage)
* Tool type: Local tool
* Permissions: Messages automation (if prompted)

## What Alter can do today

Alter can send iMessages to valid phone numbers or email addresses tied to iMessage.

## What Alter does not do yet

* It does not read your message history.
* It does not summarize conversations or manage inbox threads.

## Typical workflows

### Fast update to one person

Give recipient + message in one prompt and send quickly.

### Contact-first sending

Ask Alter to find the contact details first, then send the message.

## A realistic workflow

<Steps>
  <Step title="Confirm recipient">
    Include the exact phone number or email in your prompt, or ask Alter to find it first.
  </Step>

  <Step title="Send concise message">
    Ask Alter to send one clear sentence with the necessary context.
  </Step>

  <Step title="Follow up if needed">
    Send a second confirmation message when plans change.
  </Step>
</Steps>

## Copy/paste prompts

* "Send a message to +33612345678: I'm running 10 minutes late."
* "Send an iMessage to [alex@company.com](mailto:alex@company.com): Can we move to 3 PM?"
* "Find Sarah's phone number, then send: I just shared the doc."

## How to enable

<Steps>
  <Step title="Enable Messages in Tools Manager">
    Open Alter -> click the three dots -> **Tools Manager** -> **Local Tools** -> enable **Messages**.
  </Step>

  <Step title="Check Messages app setup">
    Make sure Messages is installed and your iMessage account is active.
  </Step>

  <Step title="Run a quick test">
    Send a short message to yourself or a trusted contact.
  </Step>
</Steps>

## What to expect

* Recipient format must be a valid phone number or email.
* For safety, confirm recipient identity in the same prompt when names are ambiguous.

## Related pages

* [Messages app capabilities](/apps-tools/messages)
* [Contacts workflow](/workflows/manage-contacts-with-alter)
* [Use Tool Manager](/how-to/tool-manager-guide)


# Summarize your X feed with Computer Use
Source: https://docs.alterhq.com/workflows/summarize-x-feed-with-computer-use

Use Alter Computer Use to read what is visible in your X timeline and generate structured summaries

Use this workflow when API access is limited and you still need quick insight from your X (Twitter) feed.

## What this helps you do

You can treat your feed like a live source that Alter reads from the screen. Instead of pulling data from an API, Alter summarizes what is currently visible in your browser and helps you build a digest iteratively.

## Works with

* App: X in your browser
* Tool type: Computer Use (screen-based)
* Permissions: Accessibility and Screen Recording

## What Alter can do today

Alter can read visible feed content, summarize posts on screen, extract recurring topics, and merge multiple on-screen batches into one digest.

## What Alter does not do yet

* It does not use the official X API for this workflow.
* It cannot summarize posts that are not currently visible unless you scroll and ask again.
* It is not a full X account automation flow (posting, moderation, or analytics pipelines).

## A realistic workflow

<Steps>
  <Step title="Capture batch 1">
    Open your timeline and ask Alter to summarize visible posts.
  </Step>

  <Step title="Capture batch 2">
    Scroll down and ask for a second summary focused on new posts.
  </Step>

  <Step title="Merge into digest">
    Ask Alter to combine both summaries into one concise report.
  </Step>
</Steps>

## Copy/paste prompts

* "Summarize the tweets currently visible in my X feed."
* "List the top 5 topics in the visible posts, with one-line evidence for each."
* "Scroll down, capture the next batch, and summarize only new topics."
* "Combine the last two feed summaries into one concise daily digest."

## How to enable

<Steps>
  <Step title="Enable Computer Use tools">
    Open Alter -> click the three dots -> **Tools Manager** -> **Local Tools** -> enable **Alter** tools (Computer Use).
  </Step>

  <Step title="Grant required macOS permissions">
    In Alter settings, allow **Accessibility** and **Screen Recording** so Alter can read and interact with app windows.
  </Step>

  <Step title="Run a quick test on X">
    Open your X timeline and ask: "Summarize the posts visible on screen."
  </Step>
</Steps>

## What to expect

* Best quality comes from short iterative loops: summarize -> scroll -> summarize -> merge.
* If the wrong window is targeted, bring the browser window to front or ask Alter to list windows and target the correct one.

## Related pages

* [Computer Use capabilities](/apps-tools/computer-use)
* [Settings](/how-to/settings-guide)
* [Tools Not Working](/common-issues/tool-not-working)


# URL Callbacks
Source: https://docs.alterhq.com/workflows/url-callbacks

Integrate Alter with other apps using x-callback-url schemes

Use this guide to integrate Alter with other apps using URL schemes.

## Video Tutorial

* [https://www.youtube.com/watch?v=X-XJiveQ-Wc](https://www.youtube.com/watch?v=X-XJiveQ-Wc)

## Introduction

Alter supports x-callback-url so apps can trigger actions in each other.
You can:

* trigger Alter actions from external apps
* trigger external app actions from Alter
* pass input data in URLs
* return back to the originating app (depending on app support)

## How It Works

1. Trigger Alter actions from another app via `alter://...` URLs.
2. Trigger external app actions from Alter using that app's URL scheme.

## Trigger Alter Actions From External Apps

1. Open Action Editor.
2. Select an action.
3. In `General`, copy the URL from the **URL Callback** section.
4. Paste the URL into another app (browser, notes, shortcuts, etc.).

<img alt="Alter Callback URLs" />

## Trigger External App Actions From Alter

1. Create a clickable URL in Alter using the target app scheme.
2. Format parameters exactly as required by that app.
3. Click to run and verify action behavior.

## Examples

### Alter callback examples

* Search query:
  * `alter://action/ask-web?input=What+is+Alter+MacOS`
  * <a href="alter://action/ask-web?input=What+is+Alter+MacOS">Open in Alter</a>

* Business strategist without input:
  * `alter://action/business-strategist-gpt`
  * <a href="alter://action/business-strategist-gpt">Open in Alter</a>

* Business strategist with input:
  * `alter://action/business-strategist-gpt?input=Explain+Red+Ocean+Strategy`
  * <a href="alter://action/business-strategist-gpt?input=Explain+Red+Ocean+Strategy">Open in Alter</a>

### Cross-app example

* Bear note creation:
  * `bear://x-callback-url/create?title=Demo%20Note`

## Supported Apps (Sampling)

Apps with x-callback-url or URL-scheme support include:

* [1Writer](http://1writerapp.com/developers)
* [2Do](http://2doapp.com/kb/article/url-scheme-supported-by-2do-for-apps-like-launch-center-pro.html)
* [Agenda](https://agenda.community/t/x-callback-url-support-and-reference/27253)
* [Appigo Todo](http://support.appigo.com/support/solutions/articles/179661-third-party-integration-with-todo-ios-apps)
* [Bear](https://bear.app/faq/X-callback-url%20Scheme%20documentation/)
* [Begin](http://blog.beginapp.co/blog/2013/9/15/url-schemes)
* [breadwallet](http://breadwallet.com)
* [Byword](http://bywordapp.com/support/url-scheme.html)
* [Cal2Todo](http://yaas4home.blog.fc2.com/blog-entry-344.html)
* [ClouDrop](http://shabz.co/m/dev.html)
* [Command-C](http://danilo.to/command-c/faq/how-to-use-x-callback-url)
* [Daedalus Touch](http://daedalusapp.com/url-scheme/)
* [Daymate](http://www.nodheadsoftware.com/daymate/x-callback-url/)
* [Definition](http://handleopenurl.com/scheme/definition)
* [DEVONThink](https://www.devontechnologies.com/redirect/apps/devonthink)
* [Dispatch](http://www.dispatchapp.net)
* [Drafts](http://getdrafts.com)
* [Due](http://www.dueapp.com/developer.html)
* [Editorial](http://omz-software.com/editorial/docs/ios/editorial_urlscheme.html)
* [Equipd Bible](http://www.equipd.me/kb/url-scheme/)
* [Fantastical](http://flexibits.com/fantastical-iphone/faq)
* [Gladys](http://www.bru.build/gladys-callback-scheme)
* [Google Chrome](https://developers.google.com/chrome/mobile/docs/ios-links)
* [Google Maps](http://philgr.com/blog/google-maps-and-x-callback-url-support)
* [Hook](https://hookproductivity.com/)
* [iCab Mobile](http://www.icab.de/blog/2012/07/01/icab-mobile-6-0-supports-x-callback-url/)
* [Instapaper](http://blog.instapaper.com/post/4637427075)
* [iPGMail](http://ipgmail.com/info/developers/)
* [iZettle](http://developer.izettle.com/)
* [Kippster for Kippt](http://kippster.net/url-schemes/)
* [Launch Center Pro](http://appcubby.com/launch-center/)
* [miCal](http://micalapp.com/en/faqs#category_10)
* [Missives](http://blackfoggames.com/Missives/callback.html)
* [Multitimer](http://persapps.com/app/multitimer/url-scheme.php)
* [MyDoorOpener](http://forums.mydooropener.com/viewtopic.php?f=16\&t=295)
* [Notesy](http://notesy-app.com/weblog/files/b7e15801e5b4448495eaaccfdb374cc7-20.html)
* [OmniFocus](https://discourse.omnigroup.com/t/automation-in-omnifocus-2-14-released-2016-04-26/23985/92)
* [Opener](http://www.opener.link/api)
* [Otto's Remote](http://andymolloy.net/blog/2013/08/21/otto-and-x-callback-url/)
* [Overcast](https://overcast.fm)
* [Pleco](http://www.pleco.com/ipmanual/vershist.html)
* [Poster](http://www.tomwitkin.com/poster/developers/)
* [Prizmo](https://github.com/creaceed/PrizmoAPI)
* [Procraster](http://procrasterapp.com/userguide/51)
* [RollPG](http://blackfoggames.com/RollPG/callback.html)
* [RunJavascript](https://itunes.apple.com/us/app/runjavascript/id1254402852)
* [Scanner Go](http://ilevelupapps.com/scanner-go)
* [Shopi](http://sapient-pair.com/shopi/automation.html)
* [Showrtpath Browser](http://showrtpath.hatenablog.com/entry/2014/01/04/085804)
* [Silo](https://siloapp.net/developer)
* [Shortcuts](https://support.apple.com/guide/shortcuts/welcome/ios)
* [Story Planner](http://literautas.com/en/apps/story-planner/x-callback-url/)
* [Streets](http://www.futuretap.com/blog/streets-api/)
* [Terminology](http://agiletortoise.com/developers/terminology)
* [TextCenter](http://textcenterapp.com/xcallback.html)
* [TextExpander Touch](http://smile.clarify-it.com/d/ehf7a4)
* [Textastic](http://www.textasticapp.com/v4/manual/x-callback-url.html)
* [Textkraft](http://www.infovole.de/en/support-en/x-callback-url-in-textkraft/)
* [TextTool](http://blackfoggames.com/TextTool/callback.html)
* [Things](https://culturedcode.com/things/help/url-scheme/)
* [Timepage](http://moleskine.helpscoutdocs.com/article/92-timepage-url-scheme)
* [Trello](https://trello.com/c/cJfzOdDm/188-automate-with-url-scheme)
* [Tumblr for iOS](https://github.com/tumblr/TMTumblrSDK#url-schemes)
* [Ulysses](http://ulyssesapp.com/kb/x-callback-url/)
* [UpwardNotes](http://www.upwordnotes.com/url-scheme/)
* [VideoLAN](https://wiki.videolan.org/Documentation:IOS/#x-callback-url)
* [Waterminder](https://funnmedia.zendesk.com/hc/en-us/articles/360007745191-WaterMinder-X-Callback-URL-Support)
* [Where To?](http://www.futuretap.com/api/whereto/)
* [Working Copy](http://workingcopyapp.com/x-callback-url.html)

## Testing And Troubleshooting

* Verify the URL scheme and parameters.
* URL-encode special characters.
* Confirm the target app supports the action.
* Paste the app's callback documentation URL into Alter to ground syntax/rules.

## Related Docs

* [Alter Actions - Workflows](/getting-started/core-features#alter-actions-workflows)
* [Tools Not Working](/common-issues/tool-not-working)


# Use Flow for Tool Orchestration
Source: https://docs.alterhq.com/workflows/use-flow-orchestration

Let Flow automatically select and orchestrate your tools to reduce context usage and improve performance

<Info>
  **Flow** is Alter's built-in tool orchestrator. Instead of loading all your enabled tools into every request, Flow acts as a single tool that intelligently routes your requests to the right tools.
</Info>

<Warning>
  **Enable Tools First** — Flow can only use tools you've already enabled in Tool Manager. It doesn't automatically enable disabled tools. Make sure the tools you need are toggled on before using Flow.
</Warning>

## Why Use Flow?

<CardGroup>
  <Card title="Save Context Space" icon="compress">
    Flow loads as a single tool instead of all enabled tools, freeing up your context window for actual content
  </Card>

  <Card title="Faster Performance" icon="bolt">
    Smaller payloads process faster and reduce latency on every request
  </Card>

  <Card title="Save Fair Use Budget" icon="scale-balanced">
    Fewer tokens per request means less usage against your fair use policy budget
  </Card>
</CardGroup>

Every tool you enable consumes space in your context window. When you have 10+ tools enabled, this significantly impacts performance. Flow solves this by acting as a single tool that orchestrates all others.

***

## Enable Flow

<Steps>
  <Step title="Open Settings">
    Press **⌘ ,** (Command + Comma) or click **Settings** in the menu
  </Step>

  <Step title="Go to Tool Manager">
    Navigate to the **Tool Manager** tab
  </Step>

  <Step title="Enable Flow">
    Under **Local Tools > Alter**, toggle **Flow** on
  </Step>
</Steps>

<Note>
  Remember: Flow can only orchestrate tools that are already enabled. Enable the specific tools you need (Calendar, Gmail, Slack, etc.) in addition to Flow itself.
</Note>

***

## How Flow Works

When you send a request with Flow enabled, it follows this process:

<Steps>
  <Step title="Analyze">
    Flow analyzes your request to understand what you're trying to accomplish
  </Step>

  <Step title="Select">
    From your enabled tools, Flow selects the appropriate tool(s) for the task
  </Step>

  <Step title="Execute">
    Flow executes the tool calls in sequence, passing data between steps as needed
  </Step>

  <Step title="Summarize">
    Results are condensed into a concise response with key data points preserved
  </Step>
</Steps>

***

## Examples

<Tabs>
  <Tab title="Single Tool">
    **Request:** "What meetings do I have today?"

    Flow automatically:

    1. Recognizes you need calendar information
    2. Selects the Calendar tool
    3. Retrieves your meetings

    No need to manually select the Calendar tool — Flow handles it.
  </Tab>

  <Tab title="Multi-Tool Chain">
    **Request:** "Cancel my 3pm meeting and send an email to the attendees explaining I'm sick"

    Flow automatically:

    1. Uses the **Calendar** tool to find your 3pm meeting
    2. Identifies the attendees from the meeting
    3. Uses the **Gmail** tool to compose an email
    4. Sends the cancellation and explanation

    All in one natural language request.
  </Tab>

  <Tab title="With Transformation">
    **Request:** "Scrape the Alter documentation and extract the key features"

    Flow automatically:

    1. Uses a web tool to fetch the documentation content
    2. Transforms the raw HTML using `$1:Extract the key features and format as bullet points`
    3. Returns a formatted list of features

    The transformation step extracts only relevant information.
  </Tab>
</Tabs>

***

## When to Use Flow vs Specific Tools

<CardGroup>
  <Card title="Use Flow" icon="wand-magic-sparkles">
    <ul>
      <li>You're not sure which tool to use</li>
      <li>You want simple, natural language requests</li>
      <li>You have many tools enabled</li>
      <li>You're doing complex multi-step tasks</li>
    </ul>
  </Card>

  <Card title="Use Specific Tool Actions" icon="bullseye">
    <ul>
      <li>You know exactly which tool you need</li>
      <li>You want the fastest possible execution</li>
      <li>You're building repeatable workflows</li>
      <li>You need predictable, consistent behavior</li>
    </ul>
  </Card>
</CardGroup>

<Note>
  **90% Rule:** For 90% of tasks, Flow is the best choice. Create specific tool actions only when you need optimized, repeatable workflows.
</Note>

***

## Best Practice: Configure "Ask Anything"

The **Ask Anything** action is Alter's default — it's used when you type in the prompt box without selecting a specific action.

<Steps>
  <Step title="Open Action Editor">
    Go to **Settings > Actions**
  </Step>

  <Step title="Find Ask Anything">
    Look for the **"Ask Anything"** action
  </Step>

  <Step title="Click Advanced">
    Expand the **Advanced** section
  </Step>

  <Step title="Select Only Flow">
    In the **Tools** section, select only **Flow** (deselect all other tools)
  </Step>

  <Step title="Save">
    Save your changes
  </Step>
</Steps>

Now your default interactions will use Flow's orchestration instead of loading all enabled tools into every request.

***

<AccordionGroup>
  <Accordion icon="link" title="Advanced: Tool Chaining with Instructions">
    Flow automatically chains tools together when a task requires multiple steps. The output of one tool can be referenced in subsequent calls using the `$N` syntax.

    ### Reference Syntax

    | Syntax           | Description                                    |
    | ---------------- | ---------------------------------------------- |
    | `$1`             | Raw output from step 1                         |
    | `$2`             | Raw output from step 2                         |
    | `$N:instruction` | Transform step N's output using an instruction |

    ### Example with Transformation

    When scraping a website and formatting the results:

    1. Flow uses a web tool to fetch content
    2. Applies transformation: `$1:Extract the key frameworks and format as bullet points`
    3. The LLM processes the raw content before passing to the next tool

    This allows Flow to:

    * Extract only relevant information from large outputs
    * Format data appropriately for the next tool
    * Reduce noise in subsequent steps
  </Accordion>

  <Accordion icon="memory" title="Advanced: Smart Context Management">
    Flow includes a built-in summarization step that optimizes how results are returned to your conversation.

    ### What Summarization Does

    After executing tools, Flow:

    1. **Condenses the output** — Compresses verbose tool outputs
    2. **Preserves important data** — Keeps IDs, URLs, references, and data points
    3. **Surfaces key insights** — Highlights links, ideas, and findings for follow-up
    4. **Provides source citations** — Uses \[Step N] notation for traceability

    ### Why This Matters

    Without summarization, complex workflows would bloat your context window. By turn 5 or 6, you'd hit token limits.

    Flow's summarization ensures:

    * **Efficient context** — Only essential information is kept
    * **Actionable replies** — Important data points are preserved
    * **Better performance** — Less context = faster responses
    * **Traceability** — \[Step N] citations verify information sources

    ### Example Output

    ```
    Task completed successfully.

    Key artifacts for next actions:
    - Meeting ID: 12345 [Step 1]
    - Attendees: alice@example.com, bob@example.com [Step 1]
    - Draft email prepared [Step 2]

    Important findings:
    - Meeting conflicts with another event at 3pm [Step 1]
    - Alice has an out-of-office message active [Step 2]
    ```
  </Accordion>
</AccordionGroup>

***

## Tips for Best Results

<CardGroup>
  <Card title="Be Specific" icon="pencil">
    <p><strong>Good:</strong> "Send a Slack message to the engineering channel"</p>
    <p><strong>Vague:</strong> "Message the team"</p>
    <p>Specific requests help Flow select the right tool.</p>
  </Card>

  <Card title="Chain Naturally" icon="link">
    Flow handles multi-step tasks well. Don't break complex requests into multiple prompts — let Flow orchestrate the chain.
  </Card>

  <Card title="Review Results" icon="eye">
    Flow shows which tools it's using. If it selects the wrong one, rephrase your request with more detail.
  </Card>
</CardGroup>

***

## Troubleshooting

<AccordionGroup>
  <Accordion icon="xmark" title="Flow Selected the Wrong Tool">
    Rephrase your request with more specific details:

    * **Instead of:** "Check my messages"
    * **Try:** "Check my unread Slack messages in the general channel"

    The more specific you are, the better Flow can match your intent to the right tool.
  </Accordion>

  <Accordion icon="question" title="Flow Can't Find a Tool">
    Make sure the tool is:

    * **Enabled** in Tool Manager (Flow can't use disabled tools)
    * **Properly configured** (e.g., authenticated with Gmail)
    * **Not restricted** by your action settings
  </Accordion>

  <Accordion icon="gauge-high" title="Performance Still Slow">
    Even with Flow, very large requests can be slow. Try:

    * Breaking very complex tasks into 2-3 steps
    * Using specific tool actions for frequently repeated tasks
    * Enabling only essential tools in Tool Manager
  </Accordion>
</AccordionGroup>

***

## Related Docs

<CardGroup>
  <Card title="Tool Manager Guide" icon="toolbox" href="/how-to/tool-manager-guide">
    Learn how to connect and manage your tools
  </Card>

  <Card title="Tools Not Working" icon="wrench" href="/common-issues/tool-not-working">
    Fix common integration issues
  </Card>

  <Card title="Alter Actions" icon="play" href="/getting-started/core-features#alter-actions-workflows">
    Build custom tool workflows
  </Card>
</CardGroup>


# Getting started
Source: https://docs.alterhq.com/workflows/web-research-getting-started

Get started with web research connectors in Alter

Use this guide to pick the right web research setup in Alter.

<Info>
  Start with Alter routers first. `Fast`, `Best`, `Fair`, and `Light` already include web search, so you do not need to configure or connect any tool.
</Info>

## What you can use

* **Local Tools:** `Web Search` and `Web Search Gemini`
* **Remote MCP Servers:** Tavily, LinkUp, Exa
* **Apps Gallery:** Firecrawl, LinkUp, Exa (if available in your workspace)
* **Alter routers:** `Fast`, `Best`, `Fair`, and `Light` include native web search for fresh information

## Provider positioning snapshot

* **Tavily:** positions itself as a web access layer for AI agents, with one API for search, extraction, research, and crawling.
* **Firecrawl:** positions itself as an API that turns websites into LLM-ready data, with strong scraping and crawling workflows.
* **LinkUp:** positions itself as search for AI apps, with standard and deep modes and sourced answers.
* **Exa:** positions itself as a high-quality search API for AI, with multiple endpoints from search to research.

## Pick the right option

<CardGroup>
  <Card title="Start here: no setup" icon="rocket" href="/workflows/native-web-search-in-alter-routers">
    Use router-native web search first. It is the easiest option and works out of the box.
  </Card>

  <Card title="Included tools" icon="zap" href="/workflows/web-search-local-tools">
    Use Alter's included search tools when you want web access without a separate provider account.
  </Card>

  <Card title="Deep research" icon="search" href="/workflows/connect-tavily">
    Use Tavily when you need richer extraction and multi-step browsing.
  </Card>

  <Card title="Large scraping jobs" icon="database" href="/workflows/connect-firecrawl">
    Use Firecrawl when you need structured extraction across multiple pages.
  </Card>
</CardGroup>

## Build a hybrid strategy

1. Start with router-native search for the easiest setup and strong default results.
2. Use included search tools to extend models that do not have web search (including local models), without creating an account outside Alter.
3. Add MCP providers when you want great results on any model and more control over research and extraction.
4. Add a scraper when your workflow needs structured multi-page extraction.

<Warning>
  Free tiers and quotas change over time. Verify provider pricing before you rely on a specific limit.
</Warning>

<Tip>
  Avoid enabling multiple web search tools at the same time. This can confuse model tool selection. Enable one search tool per workflow, or add explicit instructions that force the model to choose a specific tool.
</Tip>

## Related guides

* [/workflows/web-search-local-tools](/workflows/web-search-local-tools)
* [/workflows/connect-tavily](/workflows/connect-tavily)
* [/workflows/connect-firecrawl](/workflows/connect-firecrawl)
* [/workflows/connect-linkup](/workflows/connect-linkup)
* [/workflows/connect-exa](/workflows/connect-exa)
* [/workflows/native-web-search-in-alter-routers](/workflows/native-web-search-in-alter-routers)


# Included search tools
Source: https://docs.alterhq.com/workflows/web-search-local-tools

Use Alter's built-in web search tools with no extra provider account

Alter includes two built-in web search tools out of the box.

These tools are useful when you use models that do not have native web search, including local models. They let you keep web access inside Alter without adding a third-party provider.

<Info>
  Unlike Tavily, LinkUp, Firecrawl, or Exa, these tools are included in Alter usage and do not require a separate provider account.
</Info>

## Tool comparison

<CardGroup>
  <Card title="Web Search (DuckDuckGo)" icon="compass">
    No API key required. Free and available immediately. Uses search snippets, so answers are fast but less detailed.
  </Card>

  <Card title="Web Search Gemini" icon="sparkles">
    Uses Google search with Gemini 2.5 Flash. Returns more detailed answers and includes source links used for grounding. Requires an Alter Pro or Lifetime subscription.
  </Card>
</CardGroup>

## When to use each

* Use **Web Search (DuckDuckGo)** when you are on a free Alter account and need quick lookups.
* Use **Web Search Gemini** when you have Alter Pro or Lifetime and need deeper synthesis with source links.

<Info>
  If you are on a free account, use **Web Search (DuckDuckGo)**.
</Info>

## How to enable

1. Open **Tools Manager**.
2. Go to **Local Tools**.
3. Enable **Web Search** and/or **Web Search Gemini**.

## Example prompts

* "Summarize the latest announcements about on-device AI assistants."
* "Compare the last three major updates from provider X and cite your sources."

<Tip>
  Do not keep both search tools enabled by default. Enable one tool for the current task, or write explicit instructions that tell the model exactly which search tool to use.
</Tip>


# Workspaces and Actions Guide
Source: https://docs.alterhq.com/workflows/workspaces-actions

Build repeatable flows by combining workspaces and Alter Actions

## Goal

Build repeatable flows by combining workspaces and Alter Actions.

## Steps

1. Gather related files and drag them together.
2. Create a workspace (`Cmd+J`).
3. Attach workspace context to an Alter Action.
4. Save prompt conventions and expected output format.
5. Test with one realistic task and refine.

<img alt="Workspaces" />

## Related Docs

* [Workspaces](/getting-started/core-features#workspaces)
* [Alter Actions - Workflows](/getting-started/core-features#alter-actions-workflows)


# Create a chat completion
Source: https://docs.alterhq.com/api-reference/create-a-chat-completion

openapi.json post /v1/chat/completions



# Create a completion
Source: https://docs.alterhq.com/api-reference/create-a-completion

openapi.json post /v1/completions



# List available models
Source: https://docs.alterhq.com/api-reference/list-available-models

openapi.json get /v1/models



# Create a chat completion
Source: https://docs.alterhq.com/api-reference/create-a-chat-completion

openapi.json post /v1/chat/completions



# Create a completion
Source: https://docs.alterhq.com/api-reference/create-a-completion

openapi.json post /v1/completions



# List available models
Source: https://docs.alterhq.com/api-reference/list-available-models

openapi.json get /v1/models



# Create a chat completion
Source: https://docs.alterhq.com/api-reference/create-a-chat-completion

openapi.json post /v1/chat/completions



# Create a completion
Source: https://docs.alterhq.com/api-reference/create-a-completion

openapi.json post /v1/completions



# List available models
Source: https://docs.alterhq.com/api-reference/list-available-models

openapi.json get /v1/models



# Create a chat completion
Source: https://docs.alterhq.com/api-reference/create-a-chat-completion

openapi.json post /v1/chat/completions



# Create a completion
Source: https://docs.alterhq.com/api-reference/create-a-completion

openapi.json post /v1/completions



# List available models
Source: https://docs.alterhq.com/api-reference/list-available-models

openapi.json get /v1/models



# Create a chat completion
Source: https://docs.alterhq.com/api-reference/create-a-chat-completion

openapi.json post /v1/chat/completions



# Create a completion
Source: https://docs.alterhq.com/api-reference/create-a-completion

openapi.json post /v1/completions



# List available models
Source: https://docs.alterhq.com/api-reference/list-available-models

openapi.json get /v1/models