# 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. **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. ## 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 Configure a custom OpenAI Chat Completions model in TypingMind using Alter endpoint and headers. Set Alter endpoint, API key, and model ID format in Msty.ai. Base URL, API key handling, and model ID format used by most OpenAI-compatible apps. ## 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. 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 API Router is designed for personal and low-volume workloads. For multi-user products or heavy agentic traffic, use dedicated provider infrastructure. ## 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 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 ` Replace `` with your real Alter API key. Make sure there is one space between `Bearer` and your key. 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` Need current model availability? Check [API Model Reference](/references/api-model-names). # 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 Goal-based Computer Use agent for macOS UI automation — describe a task, Alter drives the apps Computer Use is Alter's **UI automation layer** for macOS. Instead of chaining low-level tools yourself, describe what you want in plain language and the **Computer Use** agent (`computer_use_task`) reads accessibility trees, clicks, scrolls, opens apps, and returns the result. Since **2.0.0-beta100**, Computer Use runs **in the background** by default: you keep working while the agent operates a target window, with a live preview and Edge Bar session card. See [Background Computer Use](/apps-tools/computer-use-background) for the full non-blocking workflow. ## The `computer_use_task` agent **Computer Use** is a goal-based subagent. You pass a single **`goal`** string; Alter spins up an internal task loop that calls UI tools until the job is done or you stop it. ### Parameters | Parameter | Required | Description | | ---------- | -------- | -------------------------------------------------------------------------------------------------- | | `goal` | Yes | The complete UI task — name apps, URLs, negative constraints ("do not submit"), and what to return | | `windowID` | No | Target an existing window using `pid/title` or stable `pid/windowNumber` from `list_windows` | Example goal: ``` Open Calculator, compute 354+73, and return only the numeric result. Do not open any other apps. ``` Example with explicit window: ``` In windowID 4280/Mail — Inbox, read the subject lines of the first five unread messages and list them. ``` ### How to invoke it **Ask Anything (default)** — Computer Use is enabled by default for new sessions alongside Flow and Ask User. Ask in natural language: > "Use Computer Use to fill the job application form in Safari but don't click Submit." Alter's parent agent calls `computer_use_task` with your request as the `goal`. **Tool Manager** — Enable **Computer Use** (`computer_use_task`) for custom Actions or MCP workflows. The tool is **LLM-only**: it is meant to be chosen by the model, not run manually with fixed parameters in most cases. ## What the agent does When `computer_use_task` runs, Alter: 1. Builds **system instructions** for the subagent (AX-first workflow, batching rules, safety constraints) 2. Injects **live context** — today's date, your frontmost window ID, agent browser name, and your **app profile** (preferred Spotify vs YouTube for music, etc.) 3. Starts a **background session** (Edge Bar card + optional live preview) 4. Delegates to the **`task` primitive** with a fixed tool set and a **600 second** timeout 5. Returns a **final answer** — full extracted data for scrape goals, short confirmation for action goals The subagent self-loops: read screen → act → re-read. It does **not** have workspace/bash/file tools; non-UI work stays with the parent orchestrator. ## Tool set inside the subagent The Computer Use subagent receives these tools: | Tool | Role | | ------------------------- | ---------------------------------------------------------------------- | | `read_screen_ax` | Accessibility tree with `@elementID` tags (preferred over screenshots) | | `computer_use_screenshot` | Targeted app-window capture when visuals are required | | `perform` | Single click, fill, type, or shortcut | | `perform_sequence` | Batch multiple actions from one AX read | | `scroll` | Timed scroll in a background window | | `open_urls` | Open web pages (routed to agent browser when configured) | | `open_app` | Launch or focus a Mac app by bundle ID or name | | `list_windows` | Discover window IDs | | `wait` | Pause when AX read is empty or still loading | Full reference with parameters and examples: [Computer Use agent tools](/apps-tools/computer-use-agent-tools). ## AX-first workflow The agent is tuned for **accessibility text**, not pixels: 1. **`read_screen_ax`** with the target `windowID` 2. **`perform`** or **`perform_sequence`** using `@elementID` values from that read 3. **Re-read** after navigation, dialogs, scrolling, or shortcuts 4. **`computer_use_screenshot`** only when the goal explicitly needs images — not for routine inspection **Batching:** When several clicks or fills target elements visible in the **same** read, the agent should use **`perform_sequence`** once instead of many `perform` calls. Re-read before any step that changes layout. **App guidance:** For apps like Calculator, Discord, Spotify, and X/Twitter, `read_screen_ax` may include an `` block with faster techniques (for example Calculator `type` instead of clicking digits). ## Background vs foreground presentation | Mode | Behavior | | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Background (`edgebarOnly`)** | Default for `computer_use_task`. QuickHub stays detached; overlay not drawn on target; input via `BackgroundInputDriver`; live preview + Edge Bar session | | **Foreground (attached)** | Legacy presentation for direct `perform` / `get_active_app_context` use outside the task agent; QuickHub may attach to the target window | All new goals should go through **`computer_use_task`** so you get background execution automatically. ## Agent browser If you set **Settings → Computer use → Agent browser** to a dedicated browser, `open_urls` inside Computer Use opens pages there — not in your daily browser. This keeps agent logins separate. **Clean up when finished** closes agent tabs when the last session ends. ## Writing effective goals ### Name apps and constraints explicitly ``` Open Notes, create a new note titled "Q3 ideas", type three bullet points about team offsite ideas, and stop — do not share or sync the note anywhere else. ``` ### Negative constraints The agent respects instructions **not** to submit, send, publish, post, buy, or confirm. Say so in the goal: ``` Fill the contact form on example.com with test data but do NOT click Submit. ``` ### Extraction vs action goals | Goal type | Expected final answer | | ----------------------------------------------------- | ------------------------------------------------------------------------------------------- | | **Extraction** (scrape links, list prices, copy text) | Complete content — every row/link/field, structured (list or markdown table), not a summary | | **Action** (toggle setting, send message) | Short confirmation of what was done | | **Blocked / partial** | Explanation of what failed plus any partial data gathered | ### Example goals **Multi-app scrape** ``` Open https://news.ycombinator.com in the agent browser, extract the title and URL of each story on the front page, and return them as a markdown list. ``` **Form fill without submit** ``` In the frontmost Safari window, fill the newsletter signup with email test@example.com and name Test User. Stop before clicking Subscribe. ``` **Calculator** ``` Use Calculator to evaluate (128 * 7) + 45 and return only the final number. ``` ## Manual tool chain (power users) Before the task agent, workflows chained primitive tools explicitly: 1. `get_active_app_context` (or `read_screen_ax`) 2. `perform` 3. `scroll` 4. `wait` That pattern still works in **Tool Manager** or custom Actions when you need **one** deterministic step without a subagent. For multi-step UI work, **`computer_use_task` is strongly preferred** — it batches actions, tracks windows, runs in the background, and applies app-specific recipes. | Use `computer_use_task` | Use primitives directly | | ------------------------------------- | ------------------------------------------ | | Multi-step goals across apps or pages | Single click/fill you fully control | | Scraping, form fills, navigation | Debugging one Perform call in Tool Manager | | Default Ask Anything experience | Legacy Actions not yet migrated | Primitive references: * [Get Active App Context](/apps-tools/computer-use-get-active-app-context) — OCR-assisted read (agent prefers `read_screen_ax`) * [Perform](/apps-tools/computer-use-perform) * [Scroll](/apps-tools/computer-use-scroll) * [Wait](/apps-tools/computer-use-wait) ## Settings and permissions * **Settings → Computer use** — agent browser, preview, blocked apps ([guide](/how-to/settings-guide#computer-use)) * **Settings → Permissions** — Accessibility and Screen Recording required * **Settings → Doctor** — diagnose permission and automation issues ## Troubleshooting | Symptom | What to try | | ------------------- | ---------------------------------------------------------------------- | | Tool not available | Enable **Computer Use** in Tool Manager; confirm Ask Anything defaults | | "Blocked" app error | App is on blocklist — **Settings → Computer use → Blocked apps** | | Wrong window | Pass `windowID`; ask agent to `list_windows` once | | Timeout at 10 min | Break goal into smaller tasks or stop and continue manually | | Stopped by user | Agent reports partial progress; confirm next step before re-running | See [Background Computer Use](/apps-tools/computer-use-background), [Tools Not Working](/common-issues/tool-not-working), and [Integrations troubleshooting](/apps-tools/integrations-troubleshooting). ## Workflows * [Summarize your X feed with Computer Use](/workflows/summarize-x-feed-with-computer-use) * [Use Flow orchestration](/workflows/use-flow-orchestration) — Computer Use is a default Ask Anything tool ## Related docs * [Background Computer Use](/apps-tools/computer-use-background) * [Computer Use agent tools](/apps-tools/computer-use-agent-tools) * [Settings → Computer use](/how-to/settings-guide#computer-use) * [Tool Manager](/how-to/tool-manager-guide) # Agent tools reference Source: https://docs.alterhq.com/apps-tools/computer-use-agent-tools LLM-only tools used inside the Computer Use subagent — read_screen_ax, perform_sequence, list_windows, and more These tools are registered for Alter's **Computer Use** subagent (`computer_use_task`). They are **LLM-only** — designed for the model to call during a background UI loop, not for manual one-off execution in most cases. The subagent also receives the primitive tools [Perform](/apps-tools/computer-use-perform), [Scroll](/apps-tools/computer-use-scroll), and [Wait](/apps-tools/computer-use-wait). This page covers the **agent-specific** tools and shared window-targeting rules. Read the [Computer Use overview](/apps-tools/computer-use) for how to invoke the agent with a `goal` string. ## Shared workflow ### Window ID formats `list_windows` returns two ID styles: | Format | Example | Notes | | ------------------------- | ------------------- | ------------------------------------------------- | | `pid/title` | `4280/Mail — Inbox` | Human-readable; title can change | | Stable `pid/windowNumber` | `4280/12345` | Preferred when available — survives title changes | Pass the same `windowID` to `read_screen_ax`, `perform`, `perform_sequence`, `scroll`, and `computer_use_screenshot` for every step on that window. ### Resolution order When `windowID` is omitted: 1. Explicit `windowID` in the tool call 2. **Tracked target** — window recorded by `open_app`, `open_urls`, or prior tools in this conversation 3. **Session fallback** — during a background run, the window shown in the live preview (prevents drift when you refocus another app) 4. **Frontmost window** ### Blocked apps Computer Use refuses to open, read, or control apps on your blocklist (**Settings → Computer use → Blocked apps**). Password managers are blocked by default. Tools return a clear error so the agent stops looping and reports the block to you. ### Standalone vs inside the agent | Context | Available? | | ----------------------------------- | ----------------------------------------------------------------------------- | | Inside `computer_use_task` subagent | Yes — full set below | | Ask Anything parent agent | Indirectly — parent should call `computer_use_task`, not chain these manually | | Tool Manager manual run | Possible for debugging; not the primary workflow | Workspace tools (`workspace_read`, `workspace_bash`, etc.) are **not** available inside Computer Use. *** ## `read_screen_ax` **Display name:** Read Screen (AX) Returns the **accessibility tree** of a window as text. Interactive elements include an **`@elementID`** suffix for use with `perform` and `perform_sequence`. **No screenshot** and no vision analysis — strict AX-only. ### Parameters | Parameter | Required | Default | Description | | ---------- | -------- | -------------------------------------- | ---------------------------------------- | | `windowID` | No | tracked → session fallback → frontmost | `pid/title` or stable `pid/windowNumber` | ### When the agent calls it * **First step** on a window (before any click or fill) * **After** navigation, dialogs, scrolling, or shortcuts that change the UI * **Before** choosing combobox/list options that were not visible in the prior read ### Output Wrapped in `…`. During Computer Use runs, matching apps may append `` (Calculator, Discord, Spotify, X.com, etc.) with faster techniques. ### Example Goal step: agent already opened Mail via `open_app` and received `windowID: 5123/Mail — Inbox`. ``` read_screen_ax({ "windowID": "5123/Mail — Inbox" }) ``` Returns rows with element IDs such as `Unread message row 1@MessageRow_0` for subsequent `perform` clicks. ### vs `get_active_app_context` [Get Active App Context](/apps-tools/computer-use-get-active-app-context) adds OCR from screenshots. The Computer Use agent prefers **`read_screen_ax`** for speed and privacy unless the goal requires visual capture via `computer_use_screenshot`. *** ## `perform_sequence` **Display name:** Perform Sequence Runs multiple UI actions in **one tool call** — faster than separate `perform` invocations when every target element is already visible in the current AX read. ### Parameters | Parameter | Required | Description | | ---------- | -------- | ----------------------------------- | | `steps` | Yes | Array of action objects (see below) | | `windowID` | No | Applied to every step | Each **step** object: | Field | Required for | Description | | ----------- | --------------- | ------------------------------------------------ | | `action` | — | `click` (default), `fill`, `type`, or `shortcut` | | `elementID` | `click`, `fill` | ID after `@` from `read_screen_ax` | | `text` | `fill`, `type` | Text to enter | | `shortcut` | `shortcut` | e.g. `cmd+k`, `escape`, `shift+enter` | ### Batching rules * All `elementID` values must come from the **same** `read_screen_ax` result * Only batch actions that do not change layout between steps (multi-field form, calculator expression via `type`) * **Stop batching** before navigation, app switch, or opening menus/dialogs — then re-read * Execution **stops at the first failing step** and reports which step failed ### Example Fill a three-field form visible in one read: ```json theme={null} { "windowID": "5123/Signup", "steps": [ { "action": "fill", "elementID": "FirstName", "text": "Alex" }, { "action": "fill", "elementID": "LastName", "text": "Rivera" }, { "action": "fill", "elementID": "Email", "text": "alex@example.com" } ] } ``` Spotify quick search (after reading the main window): ```json theme={null} { "steps": [ { "action": "shortcut", "shortcut": "cmd+k" }, { "action": "type", "text": "Debussy Clair de Lune" } ] } ``` See [Perform](/apps-tools/computer-use-perform) for single-action semantics (`type` vs `fill`, shortcut format). *** ## `computer_use_screenshot` **Display name:** Computer Use Screenshot Captures a **specific app window** as PNG. Does **not** use global screenshot shortcuts, `screencapture`, or interactive region selection. ### Parameters | Parameter | Required | Description | | ---------- | -------- | ------------------------------------ | | `windowID` | No | Same resolution order as other tools | ### When to use * Goal explicitly asks for screenshots or visual artifacts * **Avoid** for routine UI inspection — use `read_screen_ax` instead ### Output Text metadata (`app`, `title`, `windowID`, dimensions) plus an image attachment for the model. ### Example ``` computer_use_screenshot({ "windowID": "9042/Google Chrome — Dashboard" }) ``` Fails if Screen Recording permission is missing or the window is minimized/hidden. *** ## `list_windows` **Display name:** List Windows Enumerates open windows from running applications. No parameters. ### Returns For each window: * App name and bundle identifier * Window title * **Window ID** (`pid/title`) * **Stable Window ID** when available * PID * **⭐ (ACTIVE)** marker on the frontmost window ### When the agent calls it * Target window is **not** the frontmost app and was not opened via `open_app` / `open_urls` in this run * **Once per run** is usually enough — reuse returned IDs instead of listing repeatedly ### Example output (abbreviated) ``` Open Windows (42 total): Safari (com.apple.Safari): - Window: "Apple — Homepage" ⭐ (ACTIVE) Window ID: 4280/Apple — Homepage Stable Window ID: 4280/87 PID: 4280 ``` The agent then passes `4280/87` to `read_screen_ax` for a background scrape while you work in another app. *** ## `open_app` **Display name:** Open Application Launches or focuses a Mac application. Returns the target window ID for immediate follow-up — often **without** calling `list_windows`. ### Parameters | Parameter | Required | Description | | ---------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | `bundleId` | Yes | Bundle identifier (e.g. `com.apple.Calculator`) **or** human app name (`Calculator`, `Google Chrome`) — names are resolved automatically | ### Behavior * **Background runs:** If the app is already running, Alter does not steal focus. New launches use non-activating open when possible and restore your previous frontmost app. * **Blocked apps:** Refused with blocklist error * **Success response** includes `Window ID` and optional `Stable Window ID` to pass to subsequent tools ### Example ```json theme={null} { "bundleId": "com.apple.Calculator" } ``` Response includes: ``` Target window: Calculator - Calculator Window ID: 6012/Calculator Pass this windowID to read_screen_ax, perform, perform_sequence, and scroll... ``` *** ## Primitive tools in the same agent These have dedicated pages; the subagent uses them with the same `windowID` rules: | Tool | Page | Agent notes | | ----------- | ------------------------------------------- | ----------------------------------------------------------------------------------------- | | `perform` | [Perform](/apps-tools/computer-use-perform) | Single click/fill/type/shortcut; prefer `perform_sequence` when batching | | `scroll` | [Scroll](/apps-tools/computer-use-scroll) | `milliseconds` duration (default 3000); Chromium/Safari use keyboard scroll in background | | `wait` | [Wait](/apps-tools/computer-use-wait) | Use when AX read is empty or loading — not before every step | | `open_urls` | — | Opens URLs; routed to agent browser during Computer Use | `get_active_app_context` is **not** in the subagent tool set — use `read_screen_ax` instead. *** ## Troubleshooting | Issue | Guidance | | -------------------------------- | ----------------------------------------------------------------- | | `Window … not found` | Re-run `list_windows`; window may have closed | | `elementID` failures after batch | Layout changed — re-read with `read_screen_ax` | | Blocked app | Adjust blocklist or rephrase goal to skip that app | | Screenshot failed | Grant Screen Recording; ensure window is visible | | Global shortcuts ignored | Expected in background mode — agent uses `fill`/`type`, not ⌘C/⌘V | ## Related docs * [Computer Use overview](/apps-tools/computer-use) * [Background Computer Use](/apps-tools/computer-use-background) * [Perform](/apps-tools/computer-use-perform) · [Scroll](/apps-tools/computer-use-scroll) · [Wait](/apps-tools/computer-use-wait) · [Get Active App Context](/apps-tools/computer-use-get-active-app-context) * [Settings → Computer use](/how-to/settings-guide#computer-use) # Background Computer Use Source: https://docs.alterhq.com/apps-tools/computer-use-background Run Computer Use tasks in the background while you keep working, with live preview and Edge Bar session controls Background Computer Use lets Alter drive apps on your Mac **without taking over your screen**. You keep typing, reading, and switching windows while the agent works in a background window. A floating live preview and Edge Bar session card show progress — and you can stop the run at any time. This is the default experience for the **Computer Use** agent (`computer_use_task`), introduced in **2.0.0-beta100**. ## When to use background mode Use Background Computer Use when: * You want Alter to scrape a page, fill a form, or navigate an app **while you continue your own work** * The task may take several minutes and you do not want QuickHub attached to the target window * You need to run UI automation on a window that is **not** your frontmost app Foreground-style Computer Use (QuickHub attached to the target, overlay drawn on the app) still exists for older flows and some tool configurations. For almost all new work, describe the full task in one **Computer Use** goal and let the background agent handle it. Start with the [Computer Use overview](/apps-tools/computer-use) — pass a `goal` to `computer_use_task` and the agent self-loops with its tool set. ## How a background run works When you (or the parent agent) invoke **Computer Use**, Alter: 1. **Starts an Edge Bar session** immediately — before the subagent resolves its target window 2. **Pushes `edgebarOnly` presentation** — QuickHub does not attach to the target app, and the on-screen overlay is not drawn on that window 3. **Runs a dedicated subagent** that loops with UI tools (`read_screen_ax`, `perform`, `scroll`, and others) for up to **600 seconds** (10 minutes) 4. **Routes input to the target window in the background** via `BackgroundInputDriver` — clicks, typing, and scrolls go to the agent's window, not your global keyboard focus 5. **Tracks the active target window** and mirrors it into the session card and live preview as the agent switches apps You stay in control of your Mac. Global shortcuts like **⌘C**, **⌘V**, **⌘Tab**, or system screenshot keys are **not** used by the agent — they would hit whatever app you are actually using. ## Edge Bar session card While a run is active, a **Computer Use** session appears in the **Edge Bar** (requires [QuickHub Mode](/getting-started/window-types-notch-hub-panels)). Each card shows: * **Goal** — the task text you asked for (truncated in the UI; hover for the full goal) * **Status** — what the agent is doing (for example "Reading AX", "Resolving target", or the latest action) * **Target app** — name, icon, and window title once the agent binds a window * **Stop** — cancels the subagent immediately; Alter summarizes what was done so far and does not auto-retry When a session completes, fails, or is stopped, the card updates to a terminal state (**Done**, **Needs attention**, or **Stopped**) and auto-dismisses after a short delay. Move your pointer to the inner edge of your screen to reveal the Edge Bar launcher. Computer Use sessions stack with other Edge Bar actions. ## Live preview window The **floating preview** is a picture-in-picture window that shows a live screenshot of the window the agent is controlling. It updates continuously (\~15 fps) so you can verify behavior without bringing that app forward. ### Show preview automatically By default, the preview opens when a Computer Use task starts. Turn this off in **Settings → Computer use → Show preview automatically**. Runs still execute in the background; only the floating window stays hidden until you open it. ### Watch preview When the preview is hidden (either because you turned off auto-show or clicked **Hide** on the preview itself), open it from the **Tool Inspector** on the running task: 1. Select the **Computer Use** tool run in the Hub inspector 2. Click **Watch preview** This reopens the floating window and focuses the matching session. ### Preview size Choose **Small**, **Large**, or **Custom** under **Settings → Computer use → Preview size**. **Custom** remembers the size you set by dragging the preview corner. The preview keeps a fixed aspect ratio; off-ratio target windows are letterboxed inside it. Up to **six** concurrent sessions can appear in the preview picker when multiple runs overlap. ## Background input routing `BackgroundInputDriver` sends mouse clicks, keyboard events, and scroll gestures to the target app's process without activating that app in the foreground. Alter tries routes in order: | Route | When used | | ---------------- | ----------------------------------------------------------------------------- | | **SkyLight** | Preferred when the window server can deliver events to the background process | | **Per-PID** | Posts events directly to the target process | | **HID fallback** | Last resort when other routes are unavailable | **Chromium-based apps** (Chrome, Edge, Brave, Arc, Electron apps) and **Safari** use keyboard-based scrolling in the background because native scroll events are unreliable in those engines. This is why scroll behavior may look different from foreground use but still reaches the correct window. ## Window targeting during background runs UI tools resolve `windowID` in this order: 1. **Explicit `windowID`** in the tool call (`pid/title` or stable `pid/windowNumber` from `list_windows`) 2. **Tracked target** — window last opened via `open_app`, `open_urls`, or a prior tool in this conversation 3. **Session fallback** — while `edgebarOnly` is active, the window bound to the live preview (so omitted `windowID` does not drift to whatever you clicked since the run started) 4. **Frontmost window** — only outside a background session If you pass `windowID` on the initial `computer_use_task` call, the agent is instructed to reuse it for every `read_screen_ax`, `perform`, and `scroll` step. ## Agent browser Web pages the agent opens with `open_urls` during a Computer Use run go to the **agent browser** when you configure one under **Settings → Computer use → Agent browser**. This isolates logins and tabs from your everyday browser. With **Clean up when finished** enabled, Alter closes agent-opened tabs (or quits the browser if the agent launched it) when the last session ends. Links you open yourself still use your macOS default browser. See [Settings → Computer use](/how-to/settings-guide#computer-use) for configuration details. ## Stop, cancel, and timeout | Action | Effect | | ---------------------------------- | -------------------------------------------------------------------------------------------------- | | **Stop** (preview or session card) | Cancels the subagent; parent agent receives a message to summarize progress and ask how to proceed | | **600 s timeout** | Subagent stops; answer is prefixed with a timeout notice if partially complete | | **Dismiss** (completed session) | Removes the card from the Edge Bar; does not undo UI changes the agent made | Alter does not automatically rerun Computer Use after you stop it. ## Settings Configure background behavior in **Settings → Computer use**: * **Agent browser** — dedicated browser for agent-driven URLs * **Clean up when finished** — close agent tabs when done * **Show preview automatically** — open floating preview on start * **Preview size** — Small / Large / Custom * **Blocked apps** — apps the agent must never open, read, or control Full label-by-label reference: [Settings → Computer use](/how-to/settings-guide#computer-use). ## Troubleshooting ### Preview never appears * Check **Show preview automatically** is on, or click **Watch preview** in the Tool Inspector * Confirm you did not click **Hide** on the preview — that persists until the next run or you reopen via **Watch preview** * Edge Bar must be available (QuickHub Mode on); the preview itself is independent of Edge Bar visibility ### Agent acts on the wrong window * Include a specific `windowID` in your goal or the `computer_use_task` parameters * Ask the agent to call `list_windows` once and reuse stable IDs * Avoid switching the target app to fullscreen mid-run if the window bounds change unexpectedly ### Blocked app errors Password managers and other sensitive apps are blocked by default. The agent reports that the app is on your blocklist. Remove it only if you intentionally want Computer Use to control that app: **Settings → Computer use → Blocked apps**. ### Permission failures Background Computer Use requires **Accessibility** and **Screen Recording** (for preview capture). Grant both under **Settings → Permissions** or **Settings → Doctor**. See [Tools Not Working](/common-issues/tool-not-working). ### Scroll or click seems ignored in a browser Chromium and Safari background scrolling uses keyboard simulation. If content still does not move, the agent should re-read the AX tree and try a shorter scroll duration or a different direction. ## Related docs * [Computer Use overview](/apps-tools/computer-use) — `computer_use_task` goals, tool set, examples * [Computer Use agent tools](/apps-tools/computer-use-agent-tools) — `read_screen_ax`, `perform_sequence`, `list_windows`, and more * [Perform](/apps-tools/computer-use-perform) · [Scroll](/apps-tools/computer-use-scroll) · [Wait](/apps-tools/computer-use-wait) — primitive tools the subagent also uses * [Settings → Computer use](/how-to/settings-guide#computer-use) * [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. The [**Computer Use**](/apps-tools/computer-use) agent prefers **`read_screen_ax`** (AX-only, no screenshot) from the [agent tools reference](/apps-tools/computer-use-agent-tools). Use Get Active App Context for manual primitive chains or when you need OCR from screenshots outside the task agent. ## 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, type, and shortcut actions against UI elements Use this tool to execute concrete UI interactions after you identify targets with Get Active App Context. For multi-step UI work, prefer the [**Computer Use**](/apps-tools/computer-use) agent (`computer_use_task`), which calls `perform` and [`perform_sequence`](/apps-tools/computer-use-agent-tools) automatically. See the [agent tools reference](/apps-tools/computer-use-agent-tools) for batching rules. ## Supported actions * `click`: Click a target element (default). * `fill`: Enter text into a text field or textarea identified by `elementID`. * `type`: Type raw keystrokes into whatever currently has keyboard focus — no `elementID` needed (useful for apps without a fillable field, e.g. typing a full expression into Calculator). * `shortcut`: Send keyboard shortcuts (for example `cmd+c`, `ctrl+shift+t`). ## Inputs * `action` (optional): `click`, `fill`, `type`, or `shortcut` (default `click`). * `elementID` (required for `click` and `fill`): Element ID from Get Active App Context output. * `text` (required for `fill` and `type`): Value to insert or keystrokes to type. * `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. The [**Computer Use**](/apps-tools/computer-use) agent calls `scroll` as part of its background loop. See [agent tools](/apps-tools/computer-use-agent-tools) for window targeting and [Background Computer Use](/apps-tools/computer-use-background) for non-blocking runs. ## What it does * Scrolls in the frontmost app window (or a specific background window when `windowID` is set). * Supports direction: `up`, `down`, `left`, `right`. * Runs for a timed duration in milliseconds. ## Inputs * `milliseconds` (optional): Duration to scroll in milliseconds (default **3000**, max **3600000**). * `direction` (optional): `up`, `down`, `left`, or `right` (default `down`). * `windowID` (optional): Target a specific window (`pid/title` or stable `pid/windowNumber` from `list_windows`). ## 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. Inside [**Computer Use**](/apps-tools/computer-use), the subagent calls `wait` only when an accessibility read is empty or still loading — not before every step. See the [agent tools reference](/apps-tools/computer-use-agent-tools). ## 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. 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). ## 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 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) # Gateways Source: https://docs.alterhq.com/apps-tools/gateways Talk to Alter from Discord and Telegram while Alter runs on your Mac **Gateways** connect Alter to **Discord** and **Telegram** bots so you can chat with Alter from those apps. Each gateway runs locally on your Mac — Alter must be open and running for messages to be processed. **Gateways** (Discord/Telegram bots) are different from the **API Gateway** in **Settings → Router**, which exposes an OpenAI-compatible endpoint for third-party apps. See [API Gateway Guide](/api-router/api-gateway) for that feature. **Buzz gateway (internal)** — Internal Alter builds also support a [Buzz gateway](/apps-tools/gateways-buzz) for the dev team. It is not available in public releases yet. ## What Gateways do Gateways let you use Alter from chat platforms you already have open: * **Discord** — DM the bot or mention it in a server channel (when configured). * **Telegram** — Message the bot in a private chat or group. * **Buzz** *(internal)* — Message a dedicated Nostr identity in an accessible Buzz channel, forum, thread, or direct conversation. See [Buzz gateway (internal)](/apps-tools/gateways-buzz). Each gateway instance has its own name, **Default action**, access controls, and connection settings. Conversations are stored in Alter on your Mac the same way as Hub chats — gateways are another way to start and continue those conversations. When someone sends a message, Alter: 1. Receives it through the platform bot connection. 2. Runs the selected **Alter Action** (for example **Ask Anything**). 3. Streams the reply back into the Discord channel or Telegram chat. 4. Can download incoming attachments and upload output files from tool runs. ## Open Gateways settings Press **⌘,** (Command + Comma), click the Alter menu bar icon and choose **Settings...**, or open **Settings** from the notch **⋯** menu. In the settings sidebar, open **Integrations**, then select **Gateways**. You can also deep-link directly: `com.wearedevx.alter://settings?id=gateways` The Gateways page shows every configured gateway. Use **Add gateway** to create a **Discord** or **Telegram** connection. Internal builds also offer **Buzz**. ## Setup guides Create a Discord bot, enable intents, invite it to your server, and connect it in Alter. Create a bot with BotFather and paste the token into Alter. Join a Buzz community with an invitation link — dev team only, internal builds. ## Gateway settings reference Every gateway shares these fields: | Field | Description | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Name** | Label shown in the gateway list (for example "Team Discord" or "Personal Telegram"). | | **Enabled** | Turn the connection on or off. A bot token is required before enabling. | | **Default action** | The Alter Action used when a new conversation starts on this gateway. | | **Start server discussions in threads** (Discord only) | When on, each new top-level server message starts a Discord thread and a separate Alter chat. Messages already inside a thread continue that chat. Direct messages are unchanged. **On by default** for new Discord gateways. | | **Start Buzz discussions in threads** (Buzz only, internal) | When on, each triggering top-level shared-channel message starts a Buzz thread and separate Alter chat. **On by default** for new Buzz gateways. | | **Available actions** | Lists every action enabled for this gateway's platform. Click an action to open it in **Action Editor → Gateways**. The current **Default action** is labeled **Default**. | | **Setup guide** (Connection section) | Link to the Discord or Telegram setup guide for this platform. | | **Save and restart** | Saves credentials and reconnects the bot. | Platform-specific **Connection** fields are documented in the setup guides: * [Buzz connection fields](/apps-tools/gateways-buzz#step-1--connect-in-alter) *(internal)* * [Discord connection fields](/apps-tools/gateways-discord#connect-in-alter) * [Telegram connection fields](/apps-tools/gateways-telegram#connect-in-alter) After saving an enabled gateway, Alter shows a status line such as **Connected as @username** or an error you can act on. ## Keep gateways online with the lid closed On a MacBook, closing the lid normally puts the Mac to sleep and disconnects gateway bots. Alter can keep active gateways available while the lid is closed. At the top of **Settings → Integrations → Gateways**: | Control | Description | | -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Keep gateways online with the lid closed** | When on (default), Alter prevents sleep while at least one gateway is enabled and connected. Normal sleep returns when the last gateway stops. | | **Allow…** | Shown when administrator permission is needed. Alter asks once to install a protected `pmset` permission so it can toggle the macOS sleep setting while gateways run. | | **Options…** | Opens **Lid-closed availability** — status, battery safeguards, and permission management. | ### Battery safeguards Alter pauses lid-closed availability automatically to protect battery life: * **Pause below** — While the Mac is unplugged and discharging, Alter restores normal sleep at or below this level (default **20%**, adjustable from **5%** to **50%** in 5% steps). Lid-closed availability turns back on after charging above the limit. * **Pause in Low Power Mode** — Always honored while macOS Low Power Mode is on. Turning the main toggle off keeps the installed administrator permission, so you can enable it again without another prompt. Use **Remove administrator permission…** in **Options…** when you want to revoke it entirely. Lid-closed availability changes a protected macOS sleep setting. Alter also runs a safety monitor that restores normal sleep if the app stops unexpectedly. Gateways still require Alter to be running — this feature keeps the Mac awake, not Alter closed. ## Which actions work on Gateways? Actions **opt in** to external platforms. In the **Action Editor**, open the **Gateways** section and choose **Availability**: | Setting | Where the action runs | | --------------------- | -------------------------------- | | **None** | Local-only (Hub, QuickHub, etc.) | | **Buzz** *(internal)* | Buzz gateways only | | **Discord** | Discord gateways only | | **Telegram** | Telegram gateways only | | **All** | Every gateway | The bundled **Ask Anything** action defaults to **All** — it is the usual **Default action** for new gateways. Set **None** on Ask Anything if you want it local-only. Custom actions start on **None** until you enable a platform or **All**. In **Settings → Integrations → Gateways**, each gateway shows an **Available actions** list for its platform. Use it to confirm which actions are enabled and jump straight into **Action Editor → Gateways** for any listed action. People can still switch actions per conversation with `/new [action]` or the **Choose action** picker as long as that action is allowed on the platform. ### Parameterless vs parameterized actions When someone picks an action from **Choose action** (or `/actions`): * **Parameterless actions** (no input fields in the Action Editor) start **immediately** — Alter runs the action using its configured prompt, the same as a one-click launch in the Hub. * **Parameterized actions** (with input fields) start a **new conversation** and wait for the next message so the user can supply those inputs. ## Chat commands and controls Both Discord and Telegram support the same text commands (type them as regular messages). On Telegram, commands also work with a bot suffix such as `/help@YourBotName`. | Command | What it does | | ------------------------------------- | ------------------------------------------------------------------------------------- | | `/help` or `/start` | List available commands and show quick-action buttons | | `/status` | Show the default action and whether a conversation is selected | | `/actions` | List actions enabled for this platform (Discord: up to 40; Telegram picker: up to 20) | | `/new [action]` or `/action [action]` | Start a new conversation with the given action | | `/chats [limit] [page]` | List saved Alter conversations (limit 1–25, default 10 for text commands) | | `/use ` | Select a conversation from the last `/chats` page | | `/history [limit]` | Show recent messages from the selected conversation (limit 1–40, default 12) | | `/stop` | Stop Alter's current response in this channel or chat | On **Discord**, Alter also registers native slash commands (`/help`, `/new`, `/actions`, `/chats`, `/history`, `/stop`, `/status`) when the bot connects. If you set a **Server ID**, commands register for that server only; otherwise they register globally for the bot application. Both platforms also expose **buttons** for common tasks — for example **New chat**, **Choose action**, and **Past chats** on `/help`. Telegram uses inline keyboards; Discord uses message components. When an action uses the **Ask User** tool, Alter presents multiple-choice questions through those same interactive controls (and accepts typed replies for "Other" answers). Any message that is not a command is treated as a chat turn in the current conversation. ## Daily usage 1. Keep **Alter running** on your Mac with the gateway **Enabled**. On a MacBook, turn on **Keep gateways online with the lid closed** if you want bots to stay connected with the lid shut. 2. Message the bot on Discord or Telegram (or `@mention` it in Discord servers when **Require a mention in servers** is on). 3. Alter shows a **Thinking…** placeholder while the action runs, then updates with the streamed reply. In Telegram DMs, Alter can stream through Telegram's native draft preview when supported; in groups it edits a regular message instead. 4. Attach files in Discord or Telegram — Alter downloads them for the turn and can upload output files from tools. **Voice messages** and **audio files** are transcribed using your selected voice processor (**Settings → Voice**) and sent to Alter as text; longer audio is also attached as a meeting-style transcript context. 5. Use `/stop`, the **Stop** button (Telegram groups and Discord), or wait for the turn to finish before sending another message in the same channel or chat. ### One response at a time Alter handles **one in-flight response per channel or chat**. If a second message arrives while Alter is still responding, the bot replies that Alter is already responding in that channel or chat. Wait for the current turn to finish, then send again. ### Conversation continuity Each Discord channel or Telegram chat can have one active Alter conversation. Use `/new` to start fresh, or `/chats` and `/use` to resume an existing Alter conversation from your Mac. On Discord, enabling **Start server discussions in threads** gives each new top-level server message its own thread and Alter chat. Replies inside an existing thread continue that chat instead of starting another. ## Scheduled action output on Gateways Scheduled Alter Actions can post their automatic opening response to a connected gateway instead of staying Hub-only. Open the action in **Action Editor → Gateways** and set **Availability** to the platform, enable the gateway toggles you need, or use **All**. Enable **Start scheduled conversations on a gateway**, choose an enabled **Discord**, **Telegram**, or **Buzz** *(internal)* gateway, then choose a **Destination** (server channel, Telegram chat, or Buzz stream/forum/DM). Save the action and run or wait for its schedule. Alter delivers the opening response to the selected destination with any output attachments. **Buzz only:** Set **Default scheduled destination** on the gateway when an action should fall back to a destination without naming one each time. See [Buzz gateway (internal)](/apps-tools/gateways-buzz#send-scheduled-action-output-to-buzz). If a saved destination is no longer accessible, refresh destinations in the Action Editor or gateway settings before the next scheduled run. ## Privacy and data * Bot tokens are stored in the **macOS Keychain**, not in plain-text settings files. * Gateway configuration (names, access lists, default actions) is stored locally in Alter's preferences on your Mac. * Per-channel state (selected conversation, pending action) is stored under Alter's Application Support folder. * Message processing uses the same local Alter stack as the Hub — there is no separate cloud relay for gateway traffic. See also [Local data and privacy](/references/local-data-and-privacy). ## Troubleshooting ### Connection and tokens | Symptom | What to try | | ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | *A Discord/Telegram bot token is required before enabling this gateway.* | Paste a token in **Connection → Bot token** before turning **Enabled** on. | | *Discord rejected the bot token* | Copy a fresh token from the [Discord Developer Portal](https://discord.com/developers/applications) → your app → **Bot** → **Reset Token**. | | *Enable Message Content Intent…* (Discord code 4014) | In the Developer Portal, open your app → **Bot** → enable **Message Content Intent** under **Privileged Gateway Intents**. See [Discord privileged intents](https://discord.com/developers/docs/events/gateway#privileged-intents). | | *Telegram rejected the bot token* | Copy a fresh token from [@BotFather](https://t.me/BotFather) (`/token` for an existing bot). | | *Telegram polling is already active for this bot token* | Only one client can poll a bot token at a time. Disable other Alter Telegram gateways using the same token, remove any webhook on the bot, or revoke and replace the token in BotFather. | | *Telegram is rate-limiting this gateway* | Wait a moment and try again. Alter retries automatically; avoid rapid repeated saves or restarts. | | *…is still connecting. Check the token and network connection.* | Confirm the token, network access, and that Alter remains open. Click **Save and restart**. | ### Usage | Symptom | What to try | | -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Bot online but no replies in a Discord server | If **Require a mention in servers** is on, `@mention` the bot. Confirm the bot has **Send Messages** and **Read Message History** in that channel. If **Start server discussions in threads** is on, also grant **Create Public Threads** and **Send Messages in Threads**. | | *I couldn't start a Discord thread for this discussion* | Threads only start from server text or announcement channels. Check thread permissions above, or turn off **Start server discussions in threads**. | | Messages ignored on Discord | Check **Server ID (optional)** matches the server you are using. Confirm your user ID is in **Allowed Discord user IDs** if that list is not empty. | | Messages ignored on Telegram | Confirm your user or chat ID is listed in **Allowed Telegram user or chat IDs** if that list is not empty. | | *Action '…' is not enabled for Discord/Telegram* | Open the action in **Action Editor → Gateways** and set **Availability** to the platform or **All**. | | *No actions are enabled for Discord/Telegram* | Enable at least one action for the platform in **Action Editor → Gateways**, and set a valid **Default action** on the gateway. The gateway's **Available actions** list stays empty until at least one action opts in. | | *That action is no longer available on Discord/Telegram* | The action was disabled for this platform or removed. Pick another action or re-enable it in **Action Editor → Gateways**. | | *Alter is already responding…* | Wait for the current turn to finish (turns can run up to about 10 minutes), or send `/stop` / tap **Stop**. | ### Lid-closed availability | Symptom | What to try | | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | Gateways disconnect when the MacBook lid closes | Turn on **Keep gateways online with the lid closed** in **Settings → Integrations → Gateways** and click **Allow…** when prompted. | | *Administrator permission needed* | Click **Allow…** or open **Options…** → **Allow Alter to keep gateways online…** and approve the one-time macOS prompt. | | Status shows *Paused for low battery* | Plug in or charge above the **Pause below** threshold in **Options…**. Alter restores lid-closed availability automatically after charging. | | Status shows *Paused for Low Power Mode* | Turn off Low Power Mode, or accept normal sleep until it is off. | | Gateways still stop when Alter quits | Lid-closed availability keeps the Mac awake — Alter must still be open and running. | ### Platform notes * **Alter must be running** — closing Alter stops gateway bots until you reopen the app. On a MacBook, **Keep gateways online with the lid closed** keeps the Mac awake while gateways run, but Alter still needs to stay open. * **Bot messages are ignored** on both platforms. * **Discord** adds 👀 while processing your message, then ✅ or ❌ when the turn finishes. User-added reactions are not treated as commands or chat input. * **Telegram** uses long polling for `message` and `callback_query` updates (inline keyboard taps). After a turn completes, Alter may react with 👍 or 👎 on your message. Group chats show a **Stop** button during active turns. For broader tool and permission issues, use **Settings → Doctor** or [Tools not working](/common-issues/tool-not-working). Doctor includes a **Gateways** section with per-gateway **connection** status (connected, reconnecting, failed) and **access** warnings when no allowlist is configured on an enabled gateway. ## Related pages * [Set up a Buzz gateway (internal)](/apps-tools/gateways-buzz) * [Set up a Discord gateway](/apps-tools/gateways-discord) * [Set up a Telegram gateway](/apps-tools/gateways-telegram) * [Alter Actions — Gateway availability](/workflows/alter-actions#gateways) — configure actions and gateway availability * [Alter Settings](/how-to/settings-guide) * [Integrations overview](/apps-tools/integrations-overview) * [API Gateway Guide](/api-router/api-gateway) — OpenAI-compatible API (separate from chat Gateways) # Buzz gateway (internal) Source: https://docs.alterhq.com/apps-tools/gateways-buzz Join a Buzz community with Alter using an invitation link — dev team only **Internal — dev team only.** Buzz gateway support is available in internal Alter builds for the Alter dev team. It is not yet available in public releases. Use this guide to join a Buzz community with Alter under **Settings → Integrations → Gateways**. The gateway runs on your Mac and can receive Buzz messages, continue conversations in threads or direct messages, exchange files, and send scheduled action output to a Buzz destination. Alter connects directly to your Buzz relay. It does not install or run Buzz Desktop, and it does not need a public endpoint on your Mac. ## Before you start * An **internal Alter build** with Buzz gateway support. * **Alter** installed and running on your Mac. * A Buzz community invitation link from an owner or administrator. * Permission to give the Alter identity access to the intended community and channels. Alter creates a dedicated Nostr identity and stores its private key in the macOS Keychain. It never puts the key in the invitation URL, process arguments, or gateway configuration. ## Step 1 — Connect in Alter Open **Settings** (⌘,) → **Integrations** → **Gateways**. Click **Add gateway** → **Buzz**. Enter the public **Agent name** colleagues will see and mention in Buzz. This is separate from the gateway's local name in Alter. Paste the full **Buzz invite link**, then click **Connect Alter**. A link normally looks like `https://your-community.example/invite/...`. If the community has a joining policy, review its Terms and Privacy links, complete any required age confirmation, then click **Accept and join**. After Alter joins and loads the available destinations, choose the desired channels, enable the gateway, then click **Save and restart**. Create separate Buzz gateways for agents that need different identities, channel access, actions, workspaces, personas, or tool permissions. Each gateway keeps its own public agent name and Nostr key. Use **Advanced connection settings** only for local development, an identity supplied by an administrator, or recovery. It exposes the community URL, private key, optional owner auth tag, and manual validation action. ## Step 2 — Set access and conversation behavior New Buzz gateways use conservative defaults: shared-channel messages require a mention, and each new top-level discussion starts a thread. | Field | Behavior | | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Agent name** | Public Buzz profile name for this gateway's dedicated identity. Changing it and saving republishes the profile without affecting other Buzz gateways. | | **Channels** | Choose **All accessible channels** or **Selected channels**. Selection can only narrow the destinations returned by Buzz membership. | | **Default scheduled destination** | Destination used for automatic action output when the action does not select one explicitly. Leave it at **None** if scheduled output must always name a destination. | | **Allowed Nostr pubkeys or npubs** | Optional comma-separated sender allowlist. Leave it empty to allow any existing member of an enabled destination, or enter public keys/`npub` values to restrict access further. | | **Require a mention in shared channels** | When on, Alter ignores every shared-channel message unless the gateway identity is mentioned, including replies in an existing thread. Direct messages and scheduled outbound messages do not need a mention. **On by default.** | | **Start Buzz discussions in threads** | When on, each triggering top-level shared-channel message gets a separate Buzz reply thread and Alter conversation. Mentioned replies inside that thread continue it. Direct messages remain private. **On by default.** | | **Limit this Buzz agent to its default action** | Keeps `/new`, `/actions`, and restored chats inside the configured action's persona, workspace, and tool permissions. Turn it off only when this identity should expose every action enabled for this specific gateway. **On by default.** | A dedicated identity can expose local actions and their permitted Mac data to Buzz participants. Keep the channel selection and sender allowlist limited to the people who should be able to invoke those actions. ## Step 3 — Choose actions and save **Ask Anything** is available by default. For a custom action, open **Action Editor → Gateways** and turn on this named Buzz gateway. Other Buzz gateways remain independent. Turn **Enabled** on and click **Save and restart**. The status changes to the connected identity after the relay authenticates the live subscription. ## Test the gateway Buzz gateway processing happens on your Mac. Keep Alter open. On a MacBook, enable **Keep gateways online with the lid closed** if you want the gateway to remain available while plugged in with the lid shut. In a shared Buzz destination, mention the gateway identity and send `/help`. In a direct message, `/help` works without a mention. Alter replies with the available text commands. In a shared channel, mention the gateway identity and ask a short question. Mention the gateway again for each follow-up in the thread. Alter adds activity feedback, creates or continues the Buzz thread, and edits its draft reply while the action runs. Send a direct message or attach a file from an accessible Buzz conversation. Alter keeps direct-message routing private, downloads the attachment for the action, and can upload files produced by tools. ## Send scheduled action output to Buzz An action can send its automatic opening response to a Buzz stream, forum, or direct conversation. Open the action in **Action Editor → Gateways** and turn on the enabled Buzz gateway. Enable **Start scheduled conversations on a gateway**, choose the enabled Buzz gateway, then choose a **Destination**. Save the action and run or wait for its schedule. Alter posts a new top-level Buzz message with any output attachments. Scheduled sends are serialized per destination so overlapping runs do not interleave. If a saved destination is no longer accessible, load channels again and choose a current destination before the next scheduled run. ## Commands Buzz accepts the same text workflow as the other chat gateways: | Command | What it does | | ------------------------------------- | ------------------------------------------------------------------- | | `/help` or `/start` | Show Buzz gateway help. | | `/status` | Show the live gateway state and the selected conversation's action. | | `/actions` | List actions enabled for Buzz. | | `/new [action]` or `/action [action]` | Start a new conversation with the default or named action. | | `/chats [limit] [page]` | List saved Alter conversations. | | `/use ` | Select a conversation from the last `/chats` page. | | `/history [limit]` | Show recent messages from the selected conversation. | | `/stop` | Stop the active response in this Buzz conversation. | When an action asks a question, reply with the numbered choice, a comma-separated set of choices for multi-select, free text for **Other**, or the submit/cancel instruction shown in the Buzz message. ## Limitations * **Internal builds only** — Buzz gateway is not available in public Alter releases yet. * **Alter must be running** — Like Discord and Telegram gateways, Buzz processing happens locally on your Mac. * **No Buzz Desktop required** — Alter bundles a pinned Buzz CLI and gateway helper; it does not install Buzz Desktop. * **Mention-only shared channels by default** — Every shared-channel message, including thread replies, must mention the gateway identity unless you turn **Require a mention in shared channels** off. * **Default action lock** — With **Limit this Buzz agent to its default action** on (default), `/new`, `/actions`, and restored chats cannot switch to another action. * **One response at a time** — Alter handles one in-flight response per Buzz conversation, same as other gateways. * **Text commands only on Buzz** — Unlike Discord slash commands or Telegram inline keyboards, Buzz uses text commands and numbered replies for interactive prompts. ## Troubleshooting | Symptom | What to try | | ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | An invitation is rejected | Ask a Buzz owner or administrator for a fresh link. The invitation may be expired or out of uses. | | A joining policy appears | Open the linked documents, accept the policy, and complete the age confirmation when required by that community. | | Alter shows a public key and asks for Buzz access | Give that public key to a Buzz administrator and add it to the relay and intended destinations. Never share the private key. | | Validation succeeds but a destination is missing | Confirm that the gateway identity is a member, then click **Validate and load channels** and save again. | | Shared-channel messages are ignored | Mention the gateway identity, check **Allowed Nostr pubkeys or npubs**, and confirm the channel is enabled. | | Direct messages are ignored | Confirm Buzz reports the direct conversation as accessible. Alter only accepts direct messages whose participant set matches discovered Buzz membership. | | Scheduled output has no destination | Choose a destination in the action's **Gateways** schedule settings or set **Default scheduled destination** on the gateway. | | The gateway keeps reconnecting | Check the relay URL, network connection, membership, and owner auth tag. Alter reconnects with overlap so accepted events are not silently skipped. | Use **Settings → Doctor → Gateways** for the latest connection and access status. ## Privacy and packaging * The private key and optional owner auth tag are stored in the macOS Keychain. * Messages, attachments, and action processing use Alter on your Mac. The gateway does not move your private actions into a cloud-hosted Alter service. * Alter bundles only the pinned Buzz command-line client and a small signed gateway helper. It does not bundle Buzz Desktop or its interface assets. * Incoming relay events are authenticated, signature-checked, and restricted to discovered Buzz memberships before Alter runs an action. ## Related pages * [Gateways overview](/apps-tools/gateways) * [Set up a Discord gateway](/apps-tools/gateways-discord) * [Set up a Telegram gateway](/apps-tools/gateways-telegram) * [Alter Actions — Gateway availability](/workflows/alter-actions#gateways) * [Local data and privacy](/references/local-data-and-privacy) # Set up a Discord gateway Source: https://docs.alterhq.com/apps-tools/gateways-discord Create a Discord bot and connect it to Alter Gateways Use this guide to create a Discord bot, grant the permissions Alter needs, and connect it under **Settings → Integrations → Gateways**. Alter connects to Discord as a **bot** using a **bot token**. You create the bot in the [Discord Developer Portal](https://discord.com/developers/applications); Alter does not generate an invite URL for you — you add the bot to your server from the portal. ## Before you start * A Discord account with permission to create applications (and to add bots to your target server). * **Alter** installed and running on your Mac. * A few minutes to copy tokens and IDs — treat bot tokens like passwords. Official references: * [Discord Developer Portal](https://discord.com/developers/applications) * [Discord quick start — overview of apps](https://discord.com/developers/docs/quick-start/overview-of-apps) ## Step 1 — Create a Discord application Go to [discord.com/developers/applications](https://discord.com/developers/applications) and sign in. Click **New Application**, choose a name (for example `Alter`), and confirm. Discord Developer Portal — General Information page after creating an application *Source: [discord.js guide — Application Setup](https://discordjs.guide/preparations/app-setup)* In the left sidebar, select **Bot**, then click **Add Bot** (or **Reset Token** if you already created one). Discord Developer Portal — Bot page with Add Bot button *Source: [Stack Overflow — permanent OAuth invite for a Discord bot](https://stackoverflow.com/questions/68218211/how-do-you-create-a-permanent-oauth-invite-for-your-discord-bot)* ## Step 2 — Enable Message Content Intent Alter must read message text in servers and DMs. Discord requires you to turn this on explicitly in the Developer Portal. In your application, go to **Bot**. Under **Privileged Gateway Intents**, turn on **Message Content Intent**. Discord Developer Portal — Privileged Gateway Intents with Message Content Intent enabled *Source: [PyCord docs — Gateway Intents](https://docs.pycord.dev/en/master/intents.html)* Confirm any prompts. Without this intent, Alter cannot read messages and shows an error such as *Enable Message Content Intent for this bot*. ## Step 3 — Copy the bot token On the **Bot** page, click **Reset Token** (first-time setup) or **Copy** under **Token**. Discord Developer Portal — Bot token section with Reset Token *Source: [discord.js guide — Application Setup](https://discordjs.guide/preparations/app-setup)* Paste the token somewhere safe temporarily — you will enter it in Alter in a later step. If it leaks, use **Reset Token** in the portal and update Alter. Never commit or share your bot token. Anyone with the token can control your bot. ## Step 4 — Invite the bot to your server Alter does not build an invite link inside the app. Generate one in the Developer Portal: In your application sidebar, go to **OAuth2** → **URL Generator**. Under **Scopes**, check **bot**. Discord Developer Portal — OAuth2 URL Generator with bot scope selected *Source: [Stack Overflow — permanent OAuth invite for a Discord bot](https://stackoverflow.com/questions/68218211/how-do-you-create-a-permanent-oauth-invite-for-your-discord-bot)* Under **Bot Permissions**, enable: * **View Channels** * **Send Messages** * **Read Message History** * **Attach Files** * **Create Public Threads** and **Send Messages in Threads** (optional — only needed if you enable **Start server discussions in threads** in Alter) These let Alter read your messages, reply, send file outputs from tool runs, and optionally create discussion threads in server channels. Discord Developer Portal — OAuth2 URL Generator bot permissions *Source: [Stack Overflow — permanent OAuth invite for a Discord bot](https://stackoverflow.com/questions/68218211/how-do-you-create-a-permanent-oauth-invite-for-your-discord-bot). Select the permissions listed above — not Administrator.* Copy the URL at the bottom, open it in your browser, choose your server, and authorize the bot. Discord documents this flow in [Adding bots to servers](https://discord.com/developers/docs/topics/oauth2#bot-authorization-flow). Discord bot authorization page when opening the generated invite URL *Source: [discord.js guide — Adding Your App](https://discordjs.guide/preparations/adding-your-app)* You need **Manage Server** (or equivalent) on the target Discord server to complete the invite. ## Step 5 — Optional: copy Server and user IDs Use these if you want to restrict which server or users can talk to Alter. In the Discord client: **User Settings → Advanced → Developer Mode** → on. See [Discord's ID documentation](https://support.discord.com/hc/en-us/articles/206346498-Where-can-I-find-my-User-Server-Message-ID). Right-click your server icon → **Copy Server ID**. Paste this into Alter's **Server ID (optional)** field to ignore messages from other servers. Right-click a user → **Copy User ID**. Use comma-separated IDs in **Allowed Discord user IDs** to allow only those people. Leave **Server ID** and **Allowed Discord user IDs** empty to allow anyone who can message the bot (subject to Discord channel permissions). ## Connect in Alter Open **Settings** (⌘,) → **Integrations** → **Gateways**. See the [Gateways overview](/apps-tools/gateways#open-gateways-settings) for other ways to open Settings. Click **Add gateway** → **Discord**. Alter creates a new gateway entry in the list. | Field | What to enter | | --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | **Name** | A label you will recognize (for example `Discord — Work server`). | | **Bot token** | The token from **Step 3**. Alter accepts tokens with or without a leading `Bot ` prefix. | | **Server ID (optional)** | Your guild ID from **Step 5**, or leave empty for any server the bot is in. When set, Alter also registers slash commands for that server only. | | **Ready message channel ID (optional)** | A channel ID where Alter posts “Hey, I'm up and running.” after a successful connection. | | **Allowed Discord user IDs** | Comma-separated user IDs, or leave empty for open access. Use `*` to allow everyone explicitly. | | **Require a mention in servers** | When on, the bot only responds in server channels when `@mentioned`. Direct messages are unaffected. | A **Discord gateway setup guide** link at the bottom of the Connection section opens this page in your browser. **Ask Anything** is the default and works on Discord out of the box. For a custom action, set **Availability** to **Discord** or **All** under **Action Editor → Gateways**. Under **Behavior**, **Start server discussions in threads** is **on by default** for new Discord gateways — each new top-level server message gets its own Discord thread and Alter chat. Messages already inside a thread continue that chat. Direct messages are unchanged. Turn it off if you prefer replies in the main channel. If you keep it on, grant **Create Public Threads** and **Send Messages in Threads** when inviting the bot (**Step 4**). Turn **Enabled** on, then click **Save and restart**. Wait for a status such as **Connected as bot …** or **Connected as @…**. If connection fails, see [Gateways troubleshooting](/apps-tools/gateways#troubleshooting). ## Test the bot Gateways only work while Alter is open on your Mac. In a DM or server channel, send `/help` (or use Discord's `/help` slash command). The bot should list commands and show **New chat**, **Choose action**, and **Past chats** buttons. Send a normal message (or `@mention` the bot in a server if **Require a mention in servers** is enabled). Alter should react with 👀, show a **Thinking…** placeholder, then stream the answer and react with ✅ or ❌ when done. When the active action uses web search, Discord replies include clearly formatted source links instead of raw markup. Run `/new` to start a fresh conversation with the **Default action**, or `/new ask-anything` to target a specific action ID. Send a Discord **voice message** or attach an audio file. Alter transcribes it with your selected voice processor (**Settings → Voice**) and sends the text to the active action. ## Related pages * [Gateways overview](/apps-tools/gateways) * [Set up a Telegram gateway](/apps-tools/gateways-telegram) * [Alter Actions — Gateway availability](/workflows/alter-actions#gateways) * [Alter Settings](/how-to/settings-guide) # Set up a Telegram gateway Source: https://docs.alterhq.com/apps-tools/gateways-telegram Create a Telegram bot with BotFather and connect it to Alter Gateways Use this guide to create a Telegram bot through **BotFather**, copy its token, and connect it under **Settings → Integrations → Gateways**. Alter connects to Telegram with a **bot token** from [@BotFather](https://t.me/BotFather). Alter uses long polling on your Mac — you do not configure webhooks or a public URL. ## Before you start * A Telegram account. * **Alter** installed and running on your Mac. * The Telegram app or [Telegram Web](https://web.telegram.org/). Official references: * [@BotFather](https://t.me/BotFather) on Telegram * [Telegram Bots — Features and BotFather](https://core.telegram.org/bots/features#botfather) * [Telegram Bot API tutorial](https://core.telegram.org/bots/tutorial) * [Bot FAQ — groups and privacy](https://core.telegram.org/bots/faq#what-messages-will-my-bot-get) ## Step 1 — Create a bot with BotFather In Telegram, open [@BotFather](https://t.me/BotFather) and tap **Start** (or send `/start`). Telegram search results showing @BotFather *Source: [kitob-bot README](https://github.com/ytsshinobi/kitob-bot)* Send `/newbot`. BotFather asks for a **display name** (shown in contacts) and a **username** (must end in `bot`, for example `MyAlterHelperBot`). Telegram chat with BotFather after sending /newbot BotFather asking for a bot username ending in bot *Source: [kitob-bot README](https://github.com/ytsshinobi/kitob-bot)* When creation succeeds, BotFather sends a message containing your **token** (format like `123456789:ABCdefGHIjklMNOpqrsTUVwxyz`). Copy the full string. Telegram documents this flow in the [Bot tutorial — Obtain your bot token](https://core.telegram.org/bots/tutorial#obtain-your-bot-token). BotFather success message with bot link and HTTP API token *Source: [kitob-bot README](https://github.com/ytsshinobi/kitob-bot). The token shown is from a public tutorial repo — treat your own token like a password.* Treat the token like a password. If it is exposed, open BotFather and send `/revoke` for that bot, then paste the new token into Alter. ### Optional BotFather settings | Command | When to use | | ----------------- | --------------------------------------------------- | | `/setdescription` | Short description users see before starting the bot | | `/setabouttext` | About text on the bot profile | | `/setuserpic` | Bot avatar | | `/token` | Retrieve the token again for an existing bot | ## Step 2 — Start a chat with your bot Tap the link BotFather provides (for example `t.me/YourBotName`) or search for your bot's username in Telegram. The success message in **Step 1** includes this link. Send `/start` so Telegram opens a conversation. You need an active chat before testing Alter. ## Step 3 — Optional: use the bot in a group Alter can receive messages from group chats as well as private chats. In your group, add the bot as a member (you may need admin permission to add bots). By default, Telegram bots in groups may only see commands and @mentions. For broader group access, open [@BotFather](https://t.me/BotFather) → `/mybots` → your bot → **Bot Settings** → **Group Privacy** → **Turn off**. See [Bot FAQ — privacy mode](https://core.telegram.org/bots/faq#what-messages-will-my-bot-get). If the bot should only respond to certain people or groups, see [Secure access — allowlists and IDs](#secure-access--allowlists-and-ids) below and fill in **Allowed Telegram user or chat IDs** when you connect Alter. ## Secure access — allowlists and IDs Restrict who can use your Telegram gateway with **Allowed Telegram user or chat IDs** in **Settings → Integrations → Gateways**. Alter checks every incoming message and inline-button tap against that list before running an action. Alter matches **user IDs**, **chat IDs**, and `@usernames` (case-insensitive). Leave the field **empty** to allow anyone who can message the bot. Enter `*` to allow everyone explicitly. Messages from users or chats not on the list are **silently ignored** — Alter does not reply with an error. ### User ID vs chat ID Telegram uses numeric IDs for both people and conversations: | ID type | Typical format | When to use in Alter | | ----------- | -------------------------------------------------------------------------------------------------- | ------------------------------------------------- | | **User ID** | Positive number (for example `123456789`) | Allow a specific person in DMs or in a group | | **Chat ID** | Positive for private chats; **negative** for groups and supergroups (for example `-1001234567890`) | Allow an entire group, or a specific private chat | In a **private chat** with your bot, the chat ID is usually the same as your user ID. In a **group**, add the group's chat ID if you want everyone in that group to be allowed (subject to [Group Privacy](#step-3--optional-use-the-bot-in-a-group) settings). Alter also accepts `@username` values (for example `@sam`) if the person has a public username. ### How to find your Telegram user ID In Telegram, open [@userinfobot](https://t.me/userinfobot) or [@getidsbot](https://t.me/getidsbot) and tap **Start**. The bot replies with your numeric **Id** — that is your **user ID**. Copy the number (digits only, no `@`) into **Allowed Telegram user or chat IDs**. To identify someone else, forward one of their messages to [@userinfobot](https://t.me/userinfobot) or [@getidsbot](https://t.me/getidsbot). The bot reports the sender's user ID. Only forward messages in contexts where you are comfortable sharing metadata with a third-party bot. For sensitive groups, prefer the Bot API method below or add the whole group by chat ID instead. ### How to find a chat ID Your user ID from **Step 1** above is usually enough — private chat IDs match the user's ID. To confirm, message your bot, then call Telegram's [`getUpdates`](https://core.telegram.org/bots/api#getupdates) method with your bot token and look for `"chat": {"id": …}` and `"from": {"id": …}` in the JSON. See [Telegram Bot API — Chat](https://core.telegram.org/bots/api#chat) and [User](https://core.telegram.org/bots/api#user). Add [@getidsbot](https://t.me/getidsbot) to the group temporarily (or use [@RawDataBot](https://t.me/RawDataBot)), send any message in the group, and copy the **Chat ID** from the bot's reply. Group IDs are negative numbers. Remove the ID bot from the group when you are done if you do not need it there permanently. With your bot token, open this URL in a browser (replace `TOKEN` with your token): `https://api.telegram.org/botTOKEN/getUpdates` Send a test message in the chat you want to identify, refresh the page, and read `message.chat.id` (chat ID) and `message.from.id` (sender user ID) from the latest entry. Treat the URL like a password — anyone with it can control your bot. Close the tab when finished and never share the link. Alter's `/status` command shows the default action and whether a conversation is selected — it does **not** print user or chat IDs. Use the methods above when building an allowlist. ### Configure the allowlist in Alter Gather comma-separated user IDs, chat IDs, and/or `@usernames` for everyone (or every group) that should be able to use the bot. Open **Settings → Integrations → Gateways**, edit your Telegram gateway, and enter the values in **Allowed Telegram user or chat IDs** (for example `123456789, -1001234567890, @sam`). Click **Save and restart**. Message the bot from an allowed account or group — you should get a reply. Messages from IDs not on the list are ignored with no response. ### Security best practices * **Treat the bot token like a password.** Store it only in Alter (Keychain). If it leaks, revoke it in [@BotFather](https://t.me/BotFather) with `/revoke` and paste the new token into Alter. * **Use an allowlist for personal bots.** An empty allowlist means anyone who discovers your bot can message it while Alter is running. * **Prefer numeric IDs over `@username`.** Usernames can change; numeric IDs are stable. * **Limit group exposure.** Turn [Group Privacy](#step-3--optional-use-the-bot-in-a-group) on in BotFather unless the bot must read all group messages. Add only trusted groups, and allowlist the group chat ID if the bot is in multiple groups. * **Be cautious with third-party ID bots.** They can see forwarded messages and group metadata. Remove them from sensitive groups when you no longer need them. ## Connect in Alter Open **Settings** (⌘,) → **Integrations** → **Gateways**. Click **Add gateway** → **Telegram**. | Field | What to enter | | ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | **Name** | A label you will recognize (for example `Telegram — Personal`). | | **Bot token** | The token from BotFather (**Step 1**). | | **Allowed Telegram user or chat IDs** | Comma-separated user IDs, chat IDs, or `@usernames`. Leave empty to allow anyone who can message the bot. Use `*` to allow everyone explicitly. | A **Telegram gateway setup guide** link at the bottom of the Connection section opens this page in your browser. **Ask Anything** is the default and works on Telegram out of the box. For a custom action, set **Availability** to **Telegram** or **All** under **Action Editor → Gateways**. Turn **Enabled** on, then click **Save and restart**. Wait for **Connected as @your\_bot\_username**. If connection fails, see [Gateways troubleshooting](/apps-tools/gateways#troubleshooting). ## Test the bot Gateways only work while Alter is open on your Mac. In your Telegram chat with the bot, send `/help`. The bot should list commands. Send a normal message. Alter should show **Thinking…**, then stream the reply. In private chats, Alter uses Telegram's native draft preview when available; otherwise it edits a regular message (rich replies can be up to about 32,000 characters). Send `/help` and use the **New chat**, **Choose action**, or **Past chats** buttons. While Alter is responding in a group, tap **Stop** or send `/stop` to cancel the current turn. Send a photo or document. Alter downloads supported attachments for the turn and can upload output files from tool runs when the action produces them. Send a **voice message** or audio file. Alter transcribes it with your selected voice processor (**Settings → Voice**) and sends the text to the active action. Audio-only messages work as chat turns even without typed text. ## Related pages * [Gateways overview](/apps-tools/gateways) * [Set up a Discord gateway](/apps-tools/gateways-discord) * [Alter Actions — Gateway availability](/workflows/alter-actions#gateways) * [Alter Settings](/how-to/settings-guide) # Overview Source: https://docs.alterhq.com/apps-tools/integrations-overview Understand local tools and external integrations in Alter Alter connects to your Mac in several distinct ways: * **Mac Apps (local tools)** — First-party integrations with Mail, Calendar, Messages, Notes, Reminders, Contacts, Maps, DEVONthink, Computer Use, and **Coding** (ChatGPT, Cursor, OpenCode, Claude Code). These run on your Mac with system permissions; no third-party API keys required for the built-in apps. * **Gateways** — Discord and Telegram bots that let you chat with Alter from those platforms while Alter runs on your Mac. Internal builds also support a [Buzz gateway (internal)](/apps-tools/gateways-buzz) for the dev team. Configure under **Settings → Integrations → Gateways**. * **External integrations** — MCP servers, skills, and cloud connectors (Slack, Notion, GitHub, web search APIs, etc.) configured in **Tools Manager**. ## Choose the right integration type * Use **Mac Apps** when the workflow stays on your Mac (inbox triage, calendar updates, iMessage, screen automation). * Use **Gateways** when you want to talk to Alter from **Discord** or **Telegram** without opening the Hub. Internal builds can also connect **Buzz** — see [Buzz gateway (internal)](/apps-tools/gateways-buzz). * Use **external integrations** when data or actions live in another service or the open web. Connect Discord and Telegram bots to Alter Step-by-step Discord bot setup Step-by-step BotFather setup Join a Buzz community — dev team only, internal builds ## Local tools (Mac Apps) Local tools run in your environment and are best for daily execution on Apple apps, coding agents, and Computer Use. Per-app references: Mail, Calendar, Messages, Notes, and more ChatGPT, Cursor, OpenCode, and Claude Code from Alter Goal-based screen automation agent

Coding tools

The **Coding** category in **Tools Manager → Local Tools** connects Alter to local coding agents you already run on your Mac: * **ChatGPT** — persistent tasks through the ChatGPT desktop app (Codex) * **Cursor** — sessions through the Cursor Agent CLI * **OpenCode** — CLI and terminal sessions, including work started outside Alter * **Claude** — Claude Code CLI sessions **Recommended:** install a specialized agent from the [Alter Marketplace](https://alterhq.com/marketplace) — the live [ChatGPT Agent](https://alterhq.com/marketplace/chatgpt-agent) is available now; Cursor, Claude, and OpenCode agents are coming soon. On first run, Alter enables the required coding tool automatically. Alter starts these sessions in the background from the Hub or an action, then **returns results into the same conversation**. Coding tools use a constrained permission profile mapped from your workspace — they do not require Alter **Full Access** for authorized project folders. Setup, permissions, provider comparison, and troubleshooting Local tools are included. Local workflows stay on your Mac. Alter can execute app actions, not only summarize data. Many local actions work without external services. ### Enable local tools In Alter, open the three-dot menu and select **Tools Manager**. Turn on the relevant local tools for the workflow you are running. Run a small prompt to confirm permissions and expected behavior. ## External integrations External integrations connect Alter with services such as Slack, Notion, GitHub, and research APIs via **Tools Manager → Remote MCP Servers** or installed skills. * Use these when your workflow spans multiple systems outside macOS built-ins. * Enable only the services required for your current task. * Mac App workflows (Mail, Calendar, Messages) do **not** require external connectors — see the **Mac Apps** section in this tab. ## Popular workflow entry points Plan and update your schedule from Alter. Draft replies and process inbox tasks. Send and manage iMessages faster. Extract and summarize visible UI content. ## 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) * [Gateways troubleshooting](/apps-tools/gateways#troubleshooting) * [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 **Important:** You need an API key from your provider (OpenAI, Mistral, etc.) before they will appear in Alter. ## 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 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" **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 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. ## Quick setup guide * **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) 1. Settings (`Cmd + ,`) → **API Keys** 2. Select your provider from the dropdown 3. Paste your key 4. Toggle **Enable Custom Provider** ON 1. Press `/` in the Alter prompt box 2. Look for the **Custom** section 3. You should see your provider's models listed ## 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! **Budget tip:** Using your own API key means you're billed directly by the provider. Monitor your usage on their dashboard to avoid surprises! ## 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 Alter data is local-only. There is no cloud history restore for chats, transcripts, or other local app data. 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 Download the version you want from [alterhq.com/changelog](https://alterhq.com/changelog) and replace the app in `Applications`. Copy your Alter data to another location or make sure your normal Mac backup is current. Use a simple app replacement first. Cleanup tools are best only when you want a full reset. ## 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 ⌘⇧Space or your custom shortcut won't open Alter **First, check the basics:** Is Alter actually running? Look for the Alter icon in your menu bar at the top of your screen. ## What's happening? You press your keyboard shortcut (default is **⌘⇧Space**), but: * Nothing happens at all * QuickHub or the notch doesn't appear * It works in some apps but not others **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 **Shortcuts → Global** 4. Look at **Open QuickHub** (or **Open notch** if QuickHub Mode is off) — this shows your current shortcut 5. Press **⌘⇧Space** (or your preferred combo) to reset or change it **Solution:** Find the conflict and change it Common apps that conflict with global shortcuts: * 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. **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 ## Quick test After making changes: 1. Click into any app (like Safari or Notes) 2. Press your shortcut (**⌘⇧Space** or whatever you set) 3. **Success:** QuickHub or the Alter notch should appear immediately **Pro tip:** You can also open Alter by hovering your mouse over the notch at the top of your screen, or by moving to the screen edge if Edge Bar is enabled. These bypass keyboard shortcuts entirely! ## 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 **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. ## 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 Alter doesn't have permission to access your microphone Local voice models aren't downloaded or configured Automatic language detection isn't working for your accent Alter is using the wrong microphone or system default isn't working ## How to fix it 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 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 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 If automatic detection isn't working: 1. In **Settings** → **Dictation** 2. Change **Dictation Language** from "Automatic" to your specific language 3. Try dictating again 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 ## 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 **Still having issues?** Try restarting Alter after granting permissions. Sometimes macOS needs a fresh start to recognize new permissions. ## Related help * [Voice settings](/how-to/settings-guide#voice) * [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 **Using the API Gateway?** This lets you use Alter's models in other apps like SillyTavern, NovelCrafter, or your own code. ## 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 Instead of just `gpt-5`, use: `OpenAI#gpt-5` The format is always: **Provider name** + **#** + **Model name** ## Setup steps 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` 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 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` | ## 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! **Pro tip:** The Alter API works exactly like OpenAI's API. If your app supports "OpenAI-compatible" endpoints, it will work with Alter. ## 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 **Quick check:** Does your chosen AI model support tools? Some smaller models don't have tool-calling capabilities. ## 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 Some AI models can't call tools – they only generate text The tool is available but not turned on in Tools Manager The AI needs clear instructions about what tool to use and how All tools are disabled via the global toggle in Active Tools ## Step-by-step fix 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. 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. 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) 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. 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 ## 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! **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. **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. ## 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 Run the same workflow without rewriting instructions each time. Assign the best model for each task. Enable only the tools needed for safer, faster runs. ## Create your first action Open the Alter window menu and select **Action Editor**. Create a new action, or duplicate a built-in action before customizing it. Define one concrete outcome, such as weekly summary, release notes, or inbox triage. Test with one real input and refine wording if needed. Built-in actions are read-only. Duplicate them to customize behavior. ## Pick a model and tools per action Use the **Model** and **Tools** tabs in the Action Editor 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. ## Ask Anything — the default action When you type in the prompt without choosing another action, Alter runs **Ask Anything**. Since **2.0.0-beta100**, it includes **Flow**, **Computer Use**, and **Ask User** by default so everyday prompts can orchestrate tools, automate the screen, or ask clarifying questions. To customize: open **Action Editor** (**⌘⇧E**) → **Ask Anything** → **Tools**. Duplicate Ask Anything if you want a variant without changing the built-in default. See [Use Flow for tool orchestration](/workflows/use-flow-orchestration#ask-anything-defaults-beta100) for how Flow fits the default setup. ## 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 `.xlsx`, `.docx`, `.pdf`, `.txt`, `.md`, `.org`, `.rtf` `.jpg`, `.png`, `.heic`, `.gif`, `.tiff`, `.svg` `.html`, URLs, and dragged text `.eml` and Apple Mail messages `.mp3`, `.wav`, `.m4a`, `.aac`, `.flac` Source files, config files, and scripts Alter supports directory drops, OCR for images and PDFs, and automatic text encoding detection. ## Audio and video transcription When you add audio or video, Alter starts transcription automatically. Drag media files to the notch or The Hub. Transcription starts automatically. Try: "Summarize key decisions" or "List action items by owner." For image analysis, use a model with vision capability. ## 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. Keep project context ready so Alter can work across large file sets quickly. Save reusable prompts for recurring tasks and consistent output quality. Enable only needed tools per workflow for better reliability. ## Build your first repeatable workflow Add the folders and files for a single project you touch every week. Turn a recurring task into a reusable action (for example weekly summary or release notes). Enable only the tools needed for that action, then run the flow end to end. Start with one workspace and one action. Small, reliable automations scale better than large, generic setups. ## 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. For most users, the default workflow is: join meeting -> Alter detects it -> record -> get transcript and follow-up items. ## What you can do from day one Dictate prompts for fast commands, drafts, and follow-up requests. Alter detects common meeting apps and prompts you to record. Turn transcripts into summaries, decisions, and action items. ## How meeting capture works When Alter detects a meeting, it shows a prompt to record or skip. Enable auto-record in settings, or start/stop recording yourself from the mic control. Ask Alter for summary, decisions, open questions, and action items with owners. ## 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." ## Speaker matching and cloud transcription **Speaker matching (beta93+):** In **Settings → Voice → Automation**, enable **Find speakers names (experimental)**, then choose **Calendars for speaker matching** and grant **Contacts** access so attendee emails resolve to real names. **Cloud quality (beta96+):** The **Cloud** voice processor uses the **Soniox V5** engine for meeting transcription when you are logged in and eligible for cloud dictation. Local **Whisper Pro** / **Parakeet** paths stay fully on-device. See the full [Meetings guide](/workflows/meetings) for auto-record, live captions, and transcript management. Dropping audio/video files is still useful for external recordings, but it is not required for normal meeting transcription inside Alter. ## Related pages * [Run your first workflows](/getting-started/first-workflows) * [Meetings — full guide](/workflows/meetings) * [How to access settings](/how-to/settings-guide#voice) * [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) ## Gateways Gateways connect Alter to **Discord** and **Telegram** so you can run actions from those chat apps while Alter stays on your Mac. Use these focused guides: * [Gateways overview](/apps-tools/gateways) * [Set up Discord](/apps-tools/gateways-discord) * [Set up Telegram](/apps-tools/gateways-telegram) ## Split Panel Split Panel divides the Hub into two conversation panes so you can research in one and write in the other. Context bridging — conversations, files, snippets, and attachments — flows between panes without copy-paste. Use this focused guide: * [Split Panel](/getting-started/split-panel) ## Coding tools Delegate implementation work to **ChatGPT**, **Cursor**, **OpenCode**, or **Claude Code** from the same Alter conversation. Alter runs the session locally, shows progress in task cards, and delivers the result back when the turn finishes. The fastest way to start is a **Marketplace coding agent** — download from [alterhq.com/marketplace](https://alterhq.com/marketplace) and run it once; Alter enables the linked coding tool on first use. Use this focused guide: * [Coding tools](/workflows/coding-tools) ## Search, filters, and thinking effort **Search and filter** — Find text inside an open conversation (**⌘F**), search all Hub history (**⇧⌘F**), filter the sidebar by conversation type, workspace, action, or tag, and jump through long Hub threads with the turn index. **Thinking effort** — On supported models, choose **Low**, **Balanced**, or **Max** from the model switcher or Action Editor. Alter remembers the choice per model and preserves reasoning context across follow-up turns. Use these focused guides: * [Window Types — Search and filter conversations](/getting-started/window-types-notch-hub-panels#search-and-filter-conversations) * [Choose your generative model — Thinking effort](/how-to/choose-generative-model#thinking-effort) ## Memory Memory saves concise facts across chats, workspaces, and meetings, then recalls the most relevant ones in new conversations. **New to Memory?** Start with [Memory Catch-Up](/workflows/memory-catch-up). In a fresh Hub chat, choose **Give Memory a head start** to review the last 30 days of chats and meetings and seed Memory in one pass—much faster than waiting for everyday learning to catch up. Use these focused guides: * [Memory Catch-Up](/workflows/memory-catch-up) — recommended first step to feed Memory from history * [Memory](/workflows/memory) — how recall, learning, and the Memory tool work * [Manage Memory](/how-to/manage-memory) — review, forget, and tune settings ## 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) # Edge Bar Source: https://docs.alterhq.com/getting-started/edge-bar Reveal quick actions from your screen edge — meetings, QuickHub, chats, and Computer Use sessions The **Edge Bar** is a vertical launcher that appears when you move your pointer to an enabled screen edge. It gives you one-click access to meetings, QuickHub, new chats, and attach — without hunting for a hotkey or the menu bar. During **Background Computer Use** runs, session cards and the live preview also live here. Edge Bar requires **QuickHub Mode**. If you turn QuickHub Mode off, Edge Bar settings are disabled and the launcher does not appear. See [QuickHub Mode](/getting-started/quickhub-mode) for the full interface model. ## When to use Edge Bar Use Edge Bar when: * You want a **mouse-driven** way to open QuickHub or start a meeting from any app * You work across **multiple monitors** and want edge triggers on outer (or all inner) edges * You run **Computer Use** in the background and want session status, stop controls, and **Watch preview** nearby * You prefer dragging files onto the edge launcher instead of into a floating QuickHub window For keyboard-first access, use **⌘⇧Space** (**Open QuickHub**) or **Open QuickHub and Attach** from **Settings → Shortcuts → Global**. Edge Bar complements those shortcuts; it does not replace them. ## How Edge Bar appears 1. Enable at least one edge under **Settings → General → Edge Bar** 2. Move your pointer to that **inner screen edge** (the edge of the display, not the notch) 3. The launcher **reveals** as you approach — closer to the edge means more visible 4. Click an icon to run that action 5. **Drag the bar vertically** along the edge to reposition it; Alter remembers the position **per edge and per monitor** On a **single display**, enabled left and right edges are always available. On **multiple displays**, only **outer** edges are used by default (the left edge of your leftmost monitor and the right edge of your rightmost monitor). This avoids accidental triggers when moving the cursor between screens. Turn on **All monitor edges** to enable your selected left/right edges on **every** monitor, including edges **between** displays. ## Edge Bar actions When no meeting is recording, the launcher shows these actions (top to bottom): | Action | What it does | | ------------------- | ---------------------------------------------------------------------------- | | **Start Meeting** | Begin meeting recording with microphone and system audio | | **Summarize Video** | Summarize the active browser video (shown when a supported page is detected) | | **Open QuickHub** | Open the floating QuickHub window | | **New Chat** | Start a fresh QuickHub conversation | | **Attach** | Attach QuickHub to the side of the frontmost app | While a **meeting is recording**, the launcher switches to meeting controls: **Start Meeting** (stop/toggle), **Live Notepad**, **Live Captions**, then **New Chat** and **Attach** below a separator. During **dictation**, a shorter set appears: **Start Meeting**, **New Chat**, and **Attach**. ## Computer Use sessions When a **Computer Use** task runs in the background, an **Edge Bar session card** appears alongside the launcher. Each card shows: * The task **goal** (truncated; hover for the full text) * **Status** — what the agent is doing (reading accessibility trees, clicking, scrolling, and so on) * **Target app** — icon, name, and window title once bound * **Stop** — cancel the run immediately Completed, failed, or stopped sessions update to a terminal state and auto-dismiss after a short delay. The **floating live preview** (picture-in-picture of the agent's target window) is managed from the same Edge Bar area — open it from the session card or from **Watch preview** in the Tool Inspector. See [Background Computer Use](/apps-tools/computer-use-background) for the full background-run workflow. ## Drop target While the Edge Bar is visible, you can **drag and drop** onto it — the same content types QuickHub accepts (files, text, URLs, and other supported pasteboard items). Alter routes dropped items into the active or new QuickHub conversation, similar to dropping onto the QuickHub window itself. ## Configure Edge Bar Open **Settings → General** (⌘,) and scroll to the **Edge Bar** section. All controls are disabled when **QuickHub Mode** is off. ### Left edge / Right edge Toggle **Left edge** and **Right edge** independently. Defaults: **Right edge** on, **Left edge** off. ### All monitor edges **All monitor edges** — *Use selected left/right edges on every monitor, including edges between displays.* When off (default), only outer edges on a multi-monitor setup are eligible. When on, every enabled edge on every connected display can reveal the launcher. ### Opening distance **Opening distance** — *0% sticks to the edge; 100% uses the default distance.* A slider from **0%** to **100%** in **25%** steps controls how far from the edge the launcher begins to reveal: * **0%** — You must push the pointer against the physical edge; the bar stays tight to the bezel * **100%** (default) — Standard reveal distance; the launcher appears before you reach the absolute edge * Intermediate values (25%, 50%, 75%) blend between those extremes Use a lower value if you trigger Edge Bar accidentally when moving between apps; use a higher value if you want the launcher to appear sooner. Full Edge Bar and QuickHub Mode settings live under **Settings → General**. Shortcut customization is in **Settings → Shortcuts** — see [Configuring Alter Settings](/how-to/settings-guide#general). ## Troubleshooting **Edge Bar never appears** * Confirm **QuickHub Mode** is on (**Settings → General → QuickHub Mode**) * Enable at least **Left edge** or **Right edge** * On multiple monitors without **All monitor edges**, try the **outer** left or right edge of your display group * Check that another app is not capturing mouse events at the screen edge **Launcher appears on the wrong monitor** * Enable **All monitor edges** if you need inner edges between displays * Reposition the bar by dragging it vertically on the edge where you want it; positions are saved per monitor **Computer Use card missing** * Edge Bar sessions require QuickHub Mode and an active `computer_use_task` run * Open **Watch preview** from the Tool Inspector if the floating preview is hidden **Settings are grayed out** * Edge Bar requires QuickHub Mode. The footer reads: *Edge Bar requires QuickHub Mode to be enabled.* ## Related docs Default interface, attach/detach, and shortcuts Edge Bar session cards and live preview QuickHub Mode and Edge Bar toggles QuickHub, Hub, and panel overview # 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 Start with unread mail + draft reply, or send a quick iMessage. Plan your day, add meetings, and route to places quickly. Turn conversation into notes, summaries, and reusable knowledge. Convert decisions into reminders and close the loop on tasks. ## 10-minute first run Start with one high-frequency job (for most users: Calendar, Notes, or Reminders). Use the copy/paste prompts from that workflow page and execute one real action. Keep the prompt style that worked, then repeat it in your next session. ## 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) 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. # 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 **New to Alter?** This guide covers the three main ways to open and use Alter on your Mac. ## Three Ways to Open Alter Hover over your Mac's camera notch Press **⌘⇧Space** (or your custom hotkey) Hold `Fn` key and speak *** ### The Notch The easiest way to open Alter is to hover your mouse over the camera notch at the top of your screen. ![Open Alter by hovering over the notch](https://hackmd.io/_uploads/rkBSeIydJg.gif) **External monitors:** On an external screen, you can hover anywhere on the top bar except directly on the mic icon. *** ### Hotkey - Alter Quick Menu Press your keyboard shortcut to open Alter instantly from any app. Press **⌘⇧Space** to open QuickHub (or the notch if QuickHub Mode is off) If you've changed it in settings, use your configured combination **Customize your shortcut:** Go to **Settings → Shortcuts → Global** and edit **Open QuickHub** (or **Open notch**). *** ### Voice Command Control Alter hands-free using your voice. 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 ![Hold to speak demonstration](https://hackmd.io/_uploads/ry2fML1dJe.gif) The currently active window is automatically selected as context when you use speech-to-prompt. 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 Your transcript appears in the context section of Alter, ready to be sent as a prompt or edited. **Configure voice settings:** Go to **Settings → Voice** (Shortcuts section) to customize your voice hotkey. *** ## Mouse Interaction ### Text Selection Select any text on your Mac to instantly invoke the **Alter Floating Menu**. * Shows system Alter actions * Favorite actions appear at the top * Quick access to common operations ### Right-Click Menu Right-click on any file or folder and select **Add to Alter** to send it as context. Locate the file or folder in Finder Open the context menu The file appears in your context section *** ## What's Next? Now that you know how to open Alter, explore these guides: Discover AppSense, Follow Mode, Workspaces, and Actions Learn about the Hub and QuickHub interfaces Set up intelligent tool orchestration and improve accuracy Learn how to keep conversations fast and reliable # Guides Source: https://docs.alterhq.com/getting-started/guides-index Choose a learning path to get the most out of Alter ## Pick your path New to Alter? Learn the basics first. Set up Flow and context habits for better speed and accuracy. Run meetings and workspace tasks with less manual work. Pick the right connector for quick search, deep research, or scraping. Build repeatable actions and connect integrations. Marketplace agents or manual setup for ChatGPT, Cursor, OpenCode, and Claude Code Chat with Alter from Discord or Telegram. Start with Memory Catch-Up to seed facts from history, then recall them in new chats. Two Hub panes side by side with context bridging. Tune shortcuts, General settings, and behavior. Choose the right model for your tasks. # 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 — pick your path Most new users work in **QuickHub Mode** (default). Choose what fits the moment: | Method | Best for | | ------------ | --------------------------------------------------------------------------------------------- | | **⌘⇧Space** | Open QuickHub from anywhere (default global shortcut) | | **Edge Bar** | Move to a screen edge to reveal the launcher — [Edge Bar guide](/getting-started/edge-bar) | | **Double ⌘** | Open QuickHub and **attach** beside the active app (configurable in **Settings → Shortcuts**) | | **⌘⇧H** | Open the full **Hub** window for tabs, workspaces, and transcripts | | **Notch** | Legacy path when QuickHub Mode is off — hover the camera notch | | **Voice** | Hold your speech-to-text key (default **Fn**) and speak | First time? Press **⌘⇧Space** to open QuickHub, or glide to the inner screen edge if you enabled [Edge Bar](/getting-started/edge-bar). ### QuickHub attach workflow When you need Alter beside your current app: 1. Press **⌃⌘←** or **⌃⌘→** to attach QuickHub left or right of the frontmost window 2. Or use **double ⌘** (default) to open and attach in one step 3. Press **⌃⌘↓** to detach back to floating QuickHub See [QuickHub Mode](/getting-started/quickhub-mode) for attach preferences and pin behavior. ## Send your first prompt 1. Open QuickHub (**⌘⇧Space**) or the Hub (**⌘⇧H**) 2. Type a simple request like "Summarize my notes" 3. Press **Enter** The default **Ask Anything** action runs **Flow**, **Computer Use**, and **Ask User** — so you can ask for app actions or screen automation without picking a special action first. ## Learn more * [Getting Started path](/getting-started/getting-started-path) * [QuickHub Mode](/getting-started/quickhub-mode) * [Window types: QuickHub, Hub, and panels](/getting-started/window-types-notch-hub-panels) * [Edge Bar](/getting-started/edge-bar) * [Dictation and voice](/workflows/dictation) # QuickHub Mode Source: https://docs.alterhq.com/getting-started/quickhub-mode Alter's default conversation interface — floating QuickHub vs the legacy notch **QuickHub Mode** is Alter's primary conversation interface. When enabled, every chat opens in **QuickHub** — a floating panel you can move, attach to app windows, or summon from the screen edge. New installs default to QuickHub Mode on (`useQuickHub = true` as of **2.0.0-beta100**). Turn QuickHub Mode off to return to the **notch**-centric experience: hover the camera notch to open the compact quick menu instead of QuickHub. ## QuickHub vs the notch | | **QuickHub Mode on** (default) | **QuickHub Mode off** | | -------------------------- | -------------------------------------- | ------------------------ | | Primary UI | Floating **QuickHub** panel | **Notch** hover menu | | Global open shortcut label | **Open QuickHub** | **Open notch** | | Edge Bar | Available | Disabled | | Attach to apps | Yes — dock beside any window | Limited notch layout | | Best for | Daily chat, attach workflows, Edge Bar | Minimal notch-only setup | QuickHub is not a separate product from the Hub — it is the **lightweight conversation surface**. Open any QuickHub chat in the full **Hub** window with **Open in Hub** (default **⌘O**) when you need tabs, sidebar, and workspace management. Most new users should leave **QuickHub Mode** enabled. The notch remains available in **Settings → Appearance → Display Notch** for status indication; it is no longer the only way to chat. ## Enable or disable QuickHub Mode 1. Open **Settings** (⌘,) 2. Go to **General** 3. Toggle **QuickHub Mode** — *Use QuickHub for all conversations instead of the notch* When you disable QuickHub Mode, **Edge Bar** settings gray out and the screen-edge launcher stops appearing. ## Opening QuickHub **From anywhere (global)** * **⌘⇧Space** — **Open QuickHub** (default; configurable in **Settings → Shortcuts → Global**) * **Open QuickHub and Attach** — opens QuickHub and attaches to a chosen side using your configured trigger (see below) * **Edge Bar** — move to an enabled screen edge and click **Open QuickHub** or **New Chat** — see [Edge Bar](/getting-started/edge-bar) **From the Hub** * **New Hub Chat** — **⌥Space** (default) starts a fresh Hub conversation; QuickHub conversations share the same shortcut categories under **Hub & QuickHub** ## Attach, detach, and pin QuickHub can **dock beside** the frontmost app window so you chat while working in Mail, Safari, Xcode, or any other app. ### Attach shortcuts Configure under **Settings → Shortcuts → QuickHub**: | Shortcut | Default | Action | | ----------------- | ------- | ----------------------------------------------------- | | **Attach Left** | **⌃⌘←** | Dock QuickHub to the left side of the active app | | **Attach Right** | **⌃⌘→** | Dock QuickHub to the right side of the active app | | **Detach Window** | **⌃⌘↓** | Return QuickHub to its floating position | | **Pin Window** | **⌘⌥P** | Pin or unpin QuickHub so it stays above other windows | You can also click **Attach** from the **Edge Bar** launcher when QuickHub Mode is on. ### Open QuickHub and Attach Under **Settings → Shortcuts → Global**, **Open QuickHub and Attach** combines open + attach in one gesture: * **Attach behavior** picker — **Attach Left** or **Attach Right** (default **Attach Right**) * **Shortcut** picker — choose the double-tap modifier that triggers attach-on-open: * **Double tap ⌘** (default) * **Double tap ⌥** * **Double tap ⌃** * **Double tap ⇧** * **None** — disables the double-tap trigger; use the recorded shortcut only Double-tap the chosen modifier quickly to open QuickHub and attach to the selected side without pressing **⌃⌘←** or **⌃⌘→** separately. ## Edge Bar dependency **Edge Bar** — the screen-edge launcher for meetings, chats, attach, and Computer Use session cards — **requires QuickHub Mode**. Edge hotspots summon QuickHub surfaces; they are not wired to the notch layout. If you rely on Edge Bar, keep QuickHub Mode enabled and configure edges under **Settings → General → Edge Bar**. ## Impact on shortcut labels Several shortcuts change their **display name** when QuickHub Mode is toggled: * **Settings → Shortcuts → Global → Open QuickHub** vs **Open notch** — same shortcut slot (**⌘⇧Space** default), different label and description * **Hub & QuickHub** category shortcuts apply to whichever surface is active (Hub tab or QuickHub conversation) Search shortcuts in **Settings → Shortcuts** with **⌘F** while the Shortcuts tab is focused, or type in the **Search shortcuts** field at the top of the tab. ## Typical workflows **Quick question while coding** Press **⌘⇧Space**, ask, press **Esc** or click away — QuickHub closes without opening the full Hub. **Side-by-side with an app** Press **⌃⌘→** (**Attach Right**) or use **Attach** from Edge Bar. QuickHub docks beside your editor or browser. **Long session → full Hub** Press **⌘O** (**Open in Hub**) to move the current QuickHub chat into a Hub tab with sidebar and history. **Background Computer Use** Start a Computer Use goal from QuickHub or the Hub. The agent runs in the background; session status appears in **Edge Bar** while you keep working. See [Background Computer Use](/apps-tools/computer-use-background). ## Troubleshooting **⌘⇧Space opens the notch instead of QuickHub** * Enable **QuickHub Mode** under **Settings → General** * Confirm **Settings → Shortcuts → Global** shows **Open QuickHub**, not **Open notch** **Attach shortcuts do nothing** * QuickHub must be open or opening; attach targets the **frontmost** app window * Some full-screen or elevated-security apps block window docking — try **Detach Window** (**⌃⌘↓**) and use floating QuickHub instead **Edge Bar missing** * Edge Bar requires QuickHub Mode and at least one enabled edge — see [Edge Bar](/getting-started/edge-bar) **Double-tap ⌘ opens QuickHub attached when I only wanted Command** * Change **Open QuickHub and Attach → Shortcut** to **None**, or pick a modifier you rarely double-tap * Or disable **Open QuickHub and Attach** by clearing its recorded shortcut ## Related docs Screen-edge launcher and Computer Use sessions QuickHub, Hub, and panels overview Full shortcut editor walkthrough Complete default shortcut inventory # Split Panel Source: https://docs.alterhq.com/getting-started/split-panel Work in two Hub conversation panes side by side and bridge context between them **Split Panel** (called **Split Right** in menus and shortcuts) divides the Alter Hub into two independent conversation panes. Keep research, source material, or an agent task trace in one pane while you write, compare, or iterate in the other — without copying text by hand. Split Panel is a **Hub-only** feature. QuickHub stays a single floating panel; open a chat in the Hub (**⌘⇧H** or **Open in Hub**) to use split layout. ## What Split Panel does When split is active, the Hub shows: 1. **Left pane (primary)** — your original conversation tabs 2. **Right pane (secondary)** — a second set of tabs, focused independently Each pane has its own tab bar, prompt box, context strip, and model selection. Drag the divider between panes to resize. Split layout persists when you quit and reopen Alter. | | **Single pane** | **Split Panel** | | ------------- | ----------------------- | ------------------------------------------------- | | Layout | One conversation column | Two columns, resizable | | Tabs | One tab bar | Separate tab bars per pane | | Context | Local to each tab | Can **bridge** to the other pane | | Inspector | Available (**⌃⌘I**) | Available (**⌃⌘I**) — opens as a trailing overlay | | Minimum width | Normal Hub width | \~700 px total (340 px per pane minimum) | ## When to use Split Panel Split Panel shines when one conversation feeds another: * **Research → draft** — keep source notes or a long transcript in the left pane; write the output in a fresh chat on the right * **Compare approaches** — run two model threads on the same problem and cross-reference answers * **Read while you chat** — preview a PDF or markdown file in the right pane while asking questions in the left * **Follow agent work** — open a `task` or `computer_use_task` trace in the other pane to watch progress without losing your main thread Split Panel is built around Alter's **context** system. The main payoff is moving conversations, files, snippets, and attachments between panes as context — not just seeing two chats at once. *** ## Open and close split ### Split Right In the Hub, click the **Split Right** icon (split-columns button) next to the **+** tab button on the left pane Press **⌘⌥N** (default) — configurable in **Settings → Shortcuts → Hub & QuickHub → Split Right** Choose **Window → Split Right** Press **⌘K**, type `split`, and choose **Split Right** Split Right opens a **new chat** in the right pane and moves keyboard focus there. The new tab inherits the model from your current left-pane tab. If split is already open, **Split Right** focuses the right pane instead of creating another split. ### Close Split Click the **×** on the right pane's tab bar Press **⌃⌘↓** (default) — **Close Split** in **Settings → Shortcuts → Hub & QuickHub** Choose **Close Split** from the **Window** menu or **⌘K** command palette Closing split **merges** all right-pane tabs into the left pane. Your conversations are preserved; only the layout closes. *** ## Navigate between panes | Shortcut (default) | Action | | ------------------ | ----------------------------------------------- | | **⌃⌘←** | Focus left pane | | **⌃⌘→** | Focus right pane | | **⌃⌘⇧←** | Move active tab to left pane | | **⌃⌘⇧→** | Move active tab to right pane | | **⌘⌥←** / **⌘⌥→** | Previous / next tab **within the focused pane** | You can also drag tabs between panes or use the tab context menu: * **Open in Split** — opens split (if needed) and moves the tab to the other pane * **Move to Other Pane** — moves the tab when split is already active Configure all split shortcuts under **Settings → Shortcuts → Hub & QuickHub**. *** ## Bridge context between panes Context bridging is Split Panel's core workflow. Context copied or added to the other pane becomes an **independent copy** in the destination tab's context strip — ready to `@`-mention, inspect, or send with your next prompt. ### Add a whole conversation as context Turn an entire conversation in one pane into context for the chat in the other pane: Right-click a conversation tab → **Open as Context in Split** (opens split automatically) or **Add as Context to Other Pane** (when split is already open) With split open, focus the pane that should **receive** context. Right-click a conversation in the sidebar → **Add as Context** Type **`@`** in the prompt box. When split is active, an **Other Pane** section lists the conversation open in the opposite pane. Select it to attach a snapshot. The snapshot includes the full conversation formatted as markdown. You cannot attach the same conversation to itself twice. ### Drag context cards When split is open: 1. Select one or more **context cards** in the conversation (files, snippets, app context, etc.) 2. Drag them to the other pane's prompt area or context strip 3. Alter copies them into the destination tab Works for files, text selections, images, calendar events, app snapshots, and most other context types. **Workspace** context cannot be transferred between panes. Attach workspace-backed files individually, or open the workspace in the destination tab separately. ### Right-click inside a conversation From messages in either pane: | Item | Menu action | Result | | --------------------------------------- | ------------------------------------- | -------------------------------------------------------- | | Context cards | **Add to Other Pane** | Copies the card to the other pane's context strip | | Images | **Add to Other Pane** | Adds the image as context in the other pane | | Document attachments | **Add to Other Pane** | Adds the file as context | | Document attachments | **Open in Other Pane** | Opens a read-only document preview tab in the other pane | | `task` / `computer_use_task` tool calls | **Open in Other Pane** (context menu) | Opens the task's read-only trace in the other pane | **Modifier-click shortcuts:** * **⌥-click** a document attachment — preview in the other pane (tooltip: *Click to open · ⌥-click to preview in split*) * **⌥-click** a `task` or `computer_use_task` card — open the task trace in the other pane If split is not open, **Open as Context in Split** and **Open in Other Pane** actions open split for you first. ### Drop files on the other pane You can also drag files from Finder onto the other pane's conversation area. They are added to that tab's context strip like a normal Hub drop. *** ## Typical workflows ### Research on the left, write on the right Open the Hub (**⌘⇧H**) with your research conversation on the left Press **⌘⌥N** to open a fresh chat on the right Right-click the left tab → **Add as Context to Other Pane**, or type **`@`** and pick the **Other Pane** conversation Prompt the right pane: "Using the attached research, draft a one-page summary with three recommendations." ### Preview a document while chatting Run a conversation that produces or references a document attachment **⌥-click** the document card, or right-click → **Open in Other Pane** The document opens as a read-only preview tab in the other pane while you continue prompting in the first ### Watch an agent task without losing your place Ask Alter to run a multi-step `task` or Computer Use job in your main pane **⌥-click** the task tool-call card, or right-click → **Open in Other Pane** Follow the read-only task conversation in the right pane while you queue follow-ups or start a related chat on the left *** ## Limitations and tips * **Read-only tabs** (document previews, task traces) cannot receive context drops — use a normal conversation tab in that pane as the destination * **Copied context is independent** — edits, follow mode, and removals in one pane do not sync back to the source * **Model per pane** — while split, each pane remembers its own model choice * **Inspector** — available while split (**⌃⌘I**); opens as a trailing panel alongside the split panes * **QuickHub** — split actions from QuickHub open or focus the Hub window automatically when needed *** ## Related resources Hub layout, tabs, and the context section What context is and how Alter uses it Files, apps, and @ mentions Full shortcut reference including split commands # 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. Add your active app to get context-aware help on what you are looking at right now. Keep context synchronized while you edit files, documents, or pages. Drag and drop project material for grounded answers and edits. ## Try it in 60 seconds Open any app, add **Current Application**, then ask: "Summarize what I am viewing and suggest next steps." Keep editing while chatting and ask: "What changed since the previous version?" Drag a related file or folder into Alter and ask for a concrete output (rewrite, summary, checklist, or edit plan). For best results, combine one app context with only the files needed for the task. Smaller, focused context usually gives better answers. ## 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. Add your active app in one click when Alter suggests **Current Application**. Keep updates synchronized across turns while you edit and ask follow-up questions. ## Start in under a minute Open Alter and click **Current Application** under the prompt box. You can also press `Down Arrow`, then `Enter`. Try: "Summarize what I am looking at and suggest the next three actions." Make a small change in the app, then ask: "What changed since your previous summary?" ## 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: QuickHub, Hub, and Panels Source: https://docs.alterhq.com/getting-started/window-types-notch-hub-panels Understand Alter's interface modes — QuickHub (default), the Hub, Edge Bar, and the legacy notch **QuickHub is the default.** New users get floating QuickHub for fast chat; use the Hub for deep work. See [QuickHub Mode](/getting-started/quickhub-mode) and [Edge Bar](/getting-started/edge-bar). ## Two Ways to Interact Full workspace with tabs, sidebar, and comprehensive management Default floating panel for quick queries, attach workflows, and voice commands *** ### General Concept Alter provides two main interfaces for interacting with AI: 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 The default lightweight panel (when **QuickHub Mode** is on). Open with **⌘⇧Space**, from the [Edge Bar](/getting-started/edge-bar), or attach beside any app with **⌃⌘←** / **⌃⌘→**. Perfect for: * Quick queries * Voice commands * Fast context additions * Side-by-side work with attach mode When **QuickHub Mode** is off, hover the camera notch for the compact quick menu. Most users should keep QuickHub Mode enabled — see [QuickHub Mode](/getting-started/quickhub-mode). *** ## Hub Interface 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 ### Opening The Hub Press `Shift + Cmd + H` Select "Open The Hub" from the Alter menu bar icon Open a conversation link from a floating panel ### Tab Types Chat sessions with AI models Collections of files, folders, and apps Meeting transcriptions and recordings Scheduled meetings and events Automated tasks and workflows ### Split Panel Split the Hub into two side-by-side conversation panes — each with its own tabs, prompt box, and context strip. Bridge context between panes by dragging context cards, using **Add as Context to Other Pane**, or typing **`@`** to pick the conversation in the other pane. Open split, move tabs between panes, and bridge context between conversations Default shortcut: **⌘⌥N** (**Split Right**). Close with **⌃⌘↓** or the **×** on the right tab bar. ### Keyboard Shortcuts | Shortcut | Action | | ---------------------- | ------------------------------------ | | `Cmd + B` | Toggle sidebar visibility | | `Cmd + W` | Close active tab | | `Cmd + Option + →` | Next tab | | `Cmd + Option + ←` | Previous tab | | `Cmd + Option + N` | Split Right (second pane) | | `Ctrl + Cmd + ←` / `→` | Focus left / right pane (when split) | | `Ctrl + Cmd + Down` | Close Split | | `Cmd + Shift + X` | Clear all contexts | | `Cmd + K` | Open Command Palette | | `Cmd + Delete` | Delete active conversation | ### Managing Contexts Drag and drop files, or use `@` in the prompt box Use arrow keys to move between contexts Press `Cmd + Shift + X` to remove all contexts ### Inspector Panel Metadata, export options, sharing links See all contexts in current conversation Statistics, files, and settings Toggle the Inspector using the sidebar icon or inspector button. *** ## QuickHub Interface QuickHub (the default when **QuickHub Mode** is on) is divided into three sections: Your selected files, apps, and references Where you type or speak your request Quick access to models and actions ### Navigation Use keyboard shortcuts in QuickHub: * `←`, `↑`, `→`, `↓` - Navigate between objects * `Enter` - Select an object * `@` - Add elements to context * `#` - Show conversation history * `>` - Show meeting history * `/` - List and choose model * `?` - Show help menu See the **Prompt Box** section below for more keyboard shortcuts. *** ## The Context Section The **Context** section displays elements sent to Alter for reference. Documents, images, audio files Selected text from any app Audio and YouTube transcripts Entire directories Saved workspace collections Current app context URLs and web content ### Keyboard Navigation | Key | Action | | ----------------- | -------------------- | | `←` `↑` `→` `↓` | Navigate contexts | | `Space` | Add/remove selected | | `Cmd + Shift + X` | Remove all contexts | | `Cmd + K` | Open Command Palette | ### 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. Start typing your prompt or an Alter Action title to send it to your AI model. ### 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 | **Invoke Actions:** Type any character in an Action's title to trigger it! ### Help Menu ![Help menu](https://beehiiv-images-production.s3.amazonaws.com/uploads/asset/file/5c14ac40-d9bd-4912-bf57-85f853ad441d/image.png?t=1741473617) Press `?` in the prompt box to see all available shortcuts. *** ## Conversation Windows ### Resizing Windows Customize conversation window size for your workflow: Drag edges horizontally to resize Drag edges vertically to resize Fit alongside other applications Size is remembered for future sessions **Useful for:** Side-by-side work, reviewing long documents, screen sharing, different display setups ### Continuous Speech-to-Prompt Have extended voice conversations without touching your keyboard: Press and hold `Fn` (or your configured key) Say your prompt out loud Let go to send to conversation Each voice prompt adds to the same thread **Hands-free workflow:** Perfect for brainstorming, dictation, or when your hands are busy. *** ## Conversation History ### Managing Chat History Access history by typing `#` in the prompt box or using The Hub's sidebar. History with tags ### Search and filter conversations **Find inside the open chat** Press **⌘F** in the Hub or QuickHub to search the current conversation. Use **⌘G** and **⇧⌘G** to jump between matches. The find bar stays scoped to the active tab. **Search all Hub history** Press **⇧⌘F** (default) or click the sidebar search field to search across saved conversations and meeting transcripts. Results update as you type. Alter indexes history in the background; Doctor shows indexing progress when a rebuild is running. **Filter the sidebar** Click the filter icon in the Hub sidebar to narrow the conversation list: | Filter | What it controls | | --------------------- | ------------------------------------------------------------------------- | | **Conversation type** | **Chats** vs **Transcripts** | | **Workspaces** | Conversations tied to a workspace, or **No workspace** | | **Actions** | Conversations started from a specific action, **No action**, or **Other** | | **Tags** | Custom tags you applied, or **No tag** | Each group supports **All** / **None** shortcuts inside the filter popover. Filters persist while the Hub is open and help when your history spans many workspaces or actions. **Jump through long Hub chats** In the Hub, a **turn index** appears beside longer conversations. Click a turn number to scroll directly to that message exchange without losing your place in a deep thread. ### Organizing with Tags Add tags like `#personal` to categorize chats: ``` # #personal #food ``` Search for conversations matching multiple tags. ### Renaming Conversations Right-click any conversation in the list Choose `Rename` from the menu Give it a descriptive name ### Exporting Conversations Export as markdown for documentation or sharing: Locate it in the history Open the context menu Choose the Export option Choose location and save as .md file * Documentation * Sharing with team * Archiving important discussions * Using in other tools ### Right-to-left conversations When macOS uses a right-to-left language layout, Hub and QuickHub conversations follow that direction automatically. Message order, the turn index, and context cards respect the active interface direction — no separate Alter setting is required. *** ## Related Resources Default UX, attach/detach, and shortcuts Screen-edge launcher and Computer Use sessions Workspaces, Actions, and more Complete shortcut reference # 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 Keep relevant context indexed and ready. Send focused context instead of large raw inputs every time. Work with bigger codebases and document sets. ## Create your first workspace Press `Shift + Cmd + H`. Open the Workspaces section in the sidebar. Click `+` in the workspace picker. Add only the resources needed for one workflow you run often. ## 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 | Audio and video files are not supported directly in workspaces. Transcribe them first by dropping them into Alter. ## 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. If responses get slower, reduce context and start a fresh conversation. ## 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: Add Context to a Prompt Source: https://docs.alterhq.com/how-to/add-context Add files, apps, and other context to your prompts ## Steps 1. Drag and drop files onto the notch. 2. Right-click a file and choose Add to Alter. 3. Type `@` in the prompt to add context manually. Drag and drop ## Bridge context between Hub panes When [Split Panel](/getting-started/split-panel) is open in the Hub, you can copy context from one pane to the other: * Drag context cards from the conversation—or items from the prompt **context strip**—to the other pane * Right-click a conversation tab → **Add as Context to Other Pane** * Type **`@`** and choose the conversation listed under **Other Pane** * Right-click context cards, images, or documents in a message → **Add to Other Pane** ## Related Docs * [Split Panel](/getting-started/split-panel) * [Your workspace](/getting-started/your-workspace) # 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 **Shortcuts → Global**. 3. Click **Open QuickHub** (or **Open notch** if QuickHub Mode is off) and press your new key combination. The default is **⌘⇧Space**. If you previously used Alt+Space, that was a custom choice — reset to the default here if needed. General settings ## Related Docs * [How to access settings](/how-to/settings-guide) * [Keyboard shortcuts reference](/references/shortcuts) # 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 In Alter, type `/` to open the model list. Select a model based on your task type, then send your prompt. Click the star next to a model to pin it for faster access. ## Set your default model Use `/` in the prompt box to open the model switcher, or press **/** anywhere in a Hub or QuickHub conversation. The selected model becomes your default immediately and stays active until you choose another one. The switcher groups **Current**, **Favorites**, and **Other models**. Each row shows context length, vision support, and — when the model supports it — a **Thinking effort** control. ## Thinking effort Supported models advertise graded thinking levels — typically **Low**, **Balanced**, and **Max**. Choose the level that matches your task: | Level | Best for | | ------------ | -------------------------------------------------------- | | **Low** | Quick replies, simple edits, lightweight follow-ups | | **Balanced** | Everyday chat and most actions (default when available) | | **Max** | Deep analysis, complex planning, and harder coding tasks | Change thinking effort from: * The **model switcher** in Hub or QuickHub — click the effort badge on a row, or use **←** / **→** while a row is highlighted * **Action Editor → Model** — set effort for a specific action's pinned model Alter remembers your choice **per model** and reuses it in future chats and actions. Reasoning context is preserved across follow-up turns on supported providers, so you can keep iterating without losing depth. Not every model exposes thinking effort. If a row has no effort badge, the model either runs at a fixed depth or does not advertise graded reasoning. ## 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. If you are unsure, start with `/best`, then switch only when you need lower latency or a specific capability. ## 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 Memory Source: https://docs.alterhq.com/how-to/manage-memory Configure Memory, review saved facts, open sources, and forget entries you no longer want ## Goal Control what Alter remembers, review saved facts, and remove anything you no longer want in Memory. ## Open Memory settings Use any of these paths: * Menu bar → **Settings...** * **⌘ ,** (Command + Comma) * Hub or notch **⋯** menu → **Settings** In the left sidebar under **General**, choose **Memory**. The Memory pane has three areas: 1. **Controls** at the top 2. **Search and filters** 3. **Your saved memory list** ## Core controls ### Use Memory **Use Memory** is the master switch. * **On:** Alter can recall saved facts, run automatic learning in eligible chats, and use the Memory tool. * **Off:** Alter stops using and saving Memory, but **keeps your existing entries** on disk. Turn this off when you want a clean break from recall without deleting what was already saved. ### Ask before saving **Ask before saving** controls how new facts enter Memory during normal chats. | Setting | Current-chat facts you state directly | Facts from tools or recalled history | | ----------------- | ------------------------------------- | ------------------------------------ | | **Off** (default) | Can save automatically after a turn | Always need your approval | | **On** | Always need your approval | Always need your approval | When approval is required, Alter shows a confirmation sheet with the proposed fact, its kind, scope, and supporting sources. If you want maximum control, turn **Ask before saving** on. If you want Alter to learn quietly from what you say in chat, leave it off and rely on notifications plus **Undo**. ## Review saved memories Each row shows: * The saved fact * Its **kind** (Fact, Preference, Goal, Decision, Recent, or Experience) * Its **scope** (Personal, a workspace name, or Deleted workspace) * The date it was last updated ### Search and filter Use the toolbar to narrow the list: * **Search** across fact text, kind, and scope label * **Scope** filter: All memories, Personal, a specific workspace, or Deleted workspaces * **Kind** filter: All kinds or one kind **Deleted workspaces** appears when you still have memories from a workspace you removed. Those entries remain visible so you can forget them intentionally instead of leaving hidden orphans. ### Inspect sources Many memories include one or more **sources**—the chat, meeting, or tool result that supported the save. 1. Expand **N sources** under a memory. 2. Choose a source to open the original chat or meeting in the Hub. If the underlying chat or transcript no longer exists, Alter keeps the saved memory and shows **Source unavailable**. ## Forget a memory To remove one saved fact: 1. Click the trash icon on the memory row. 2. Confirm **Forget**. Forgetting removes the saved fact and its provenance links. It does **not** delete the original chat or meeting transcript. You can also ask Alter in chat to forget a specific goal or fact. Alter recalls the exact entry first, asks for confirmation, then removes it. ## Undo an automatic save When Alter saves a fact automatically, it posts an in-app notification such as **Saved to Memory** or **Updated Memory**. * Choose **Undo** to reverse that specific save. * Choose **Dismiss** or let the notification time out to keep the memory. Undo is available only for the save that notification represents. If Undo fails because the memory changed again, open **Settings → Memory** to review the latest version. ## What happens when you delete a workspace Deleting a workspace removes that workspace's saved memories as part of workspace cleanup. Personal memories are not affected. If any workspace memories could not be removed during deletion, they may appear later under **Deleted workspaces** in Memory settings. ## Link Memory to an Alter Action Some workflows need explicit access to saved facts or historical chats and meetings. Menu bar → **Action Editor**, or press **⌘⇧E**. Select the action, then open the **Tools** section. Find **Memory** and choose **Link Memory**. If Memory is disabled globally, Alter offers **Turn On & Link**. Linking Memory does not turn it on for every action automatically. Only actions you link receive the Memory tool. Trusted Alter actions such as **Memory Catch-Up** ship with Memory already linked. ## When Memory settings are empty **No saved memories yet** means Alter has not stored durable facts yet. That is normal on a fresh install or right after you turn Memory on. **Recommended first step:** Run [Memory Catch-Up](/workflows/memory-catch-up). Open a fresh Hub chat and choose **Give Memory a head start**. Alter reviews the last 30 days of your chats and meetings and saves durable facts without asking for each one. This is much faster than waiting for everyday post-turn learning to accumulate context. Other ways to add your first memories: * Chat normally and share a preference or goal you want Alter to keep * Ask Alter to remember a specific fact, then confirm if prompted ## Troubleshooting ### Memory is temporarily unavailable If the list fails to load, choose **Try again**. This usually means Alter could not read the local Memory database at that moment. ### Alter is not recalling what I expect Check these first: * **Use Memory** is on * You are in a persistent Ask Anything chat, not a transient task thread * The fact is in the scope for the current workspace * The fact was not already stated in the current conversation (the Memory Brief omits duplicates) For deeper behavior, see [Memory](/workflows/memory). ### I turned Memory off but old facts still appear in Settings That is expected. Disabling Memory stops new recall and saves; it does not erase existing entries. Forget individual rows, or turn Memory back on if you only wanted to pause recall. ## Related docs * [Memory overview](/workflows/memory) * [Memory Catch-Up](/workflows/memory-catch-up) * [Configuring Alter Settings](/how-to/settings-guide) * [Local data and privacy](/references/local-data-and-privacy) # Manage context window Source: https://docs.alterhq.com/how-to/managing-context-window Optimize your AI interactions by understanding and managing context window usage 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. ## Why Context Window Matters Every interaction with AI consumes context space. When your context window fills up: Larger payloads take longer to process, increasing response times More tokens per request consumes your fair use policy budget faster Older messages may be dropped, causing the AI to "forget" earlier parts of the conversation 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 **Tools are the silent context consumer.** Enabling 10+ tools can easily consume 30-50% of your context window before you even start typing. ### 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% | These are approximate values. Actual usage varies based on tool complexity and description length. *** ## 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. 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 **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: Go to **Tools Manager** (**⌘⇧T** or menu bar) and see what's enabled Toggle off tools you haven't used in the past week You can always re-enable tools — they remember your authentication ### 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. Press **⌘⇧E** or choose **Action Editor** from the menu bar Select the "Ask Anything" action Expand the Advanced section Select only the tools you absolutely need (or just Flow) #### Custom Actions When creating custom actions, think carefully about which tools are actually needed: 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. Only enable tools your specific workflow requires. If your action just formats text, you probably don't need any tools. #### Flow vs Specific Tools **Use Flow** when you want flexibility and don't know which specific tools you'll need. It handles tool selection automatically. **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. **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 Workspaces help organize files and manage context more efficiently ### 4. Clear Context Regularly Use **⌘⇧X** (Command + Shift + X) 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: Slower responses often indicate high context usage More enabled tools = more context consumed. Review Tool Manager regularly. *** ## Quick Wins Checklist Configure "Ask Anything" to use only Flow instead of all tools Set specific tools for custom actions — disable tools you don't need Disable tools you haven't used recently Organize large projects in workspaces instead of attaching files ad-hoc Press **⌘⇧X** when starting new tasks *** ## Related Docs The best way to reduce tool-related context usage Learn how to manage your tool integrations Organize files and manage context efficiently # 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. Do not use uninstall cleaners such as CleanMyMac before reinstalling. They can remove Alter's local data. ## Safe way to reinstall or downgrade Go to [alterhq.com/changelog](https://alterhq.com/changelog) and download the release you want to install. Fully quit the app before replacing it. Drag the downloaded Alter app into your `Applications` folder and choose **Replace**. Launch Alter and confirm your existing chats, transcripts, and settings are still there. ## 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**. Menu Bar Access

General Settings

In the **General** tab, you configure QuickHub Mode, Edge Bar, selection assist, default model parameters, and notification rules. #### Quick access * **Selection Button** — Show a quick access button next to the mouse cursor when selecting text * **QuickHub Mode** — Use QuickHub for all conversations instead of the notch (default **on** for new users). When off, global shortcuts label **Open notch** instead of **Open QuickHub**. See [QuickHub Mode](/getting-started/quickhub-mode). #### Edge Bar Edge Bar settings appear below QuickHub Mode and are **disabled when QuickHub Mode is off**. * **Left edge** / **Right edge** — Enable screen-edge launchers independently (default: right on, left off) * **All monitor edges** — Use selected left/right edges on every monitor, including edges between displays. When off, only outer edges on multi-monitor setups are eligible * **Opening distance** — Slider from **0%** (stick to the edge) to **100%** (default distance) in 25% steps The section footer explains reveal behavior and multi-monitor rules. Full walkthrough: [Edge Bar](/getting-started/edge-bar). Global shortcuts for opening QuickHub (**⌘⇧Space** default), the Hub (**⌘⇧H**), and new chats (**⌥Space**) are configured in **Settings → Shortcuts → Global**, not on this tab. **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) General Settings

Memory Settings

Open **Settings → Memory** from the General section in the left sidebar. **Use Memory** * Master switch for recall, automatic learning, and the Memory tool * Default: **on** * Turning Memory off preserves existing saved entries on your Mac **Ask before saving** * When **off** (default), facts you state directly in the current chat can save automatically after a turn * Facts learned from tools or recalled history still require approval * When **on**, every proposed save waits for your confirmation The Memory pane also lists every saved fact. Search, filter by scope or kind, open source chats or meetings, and forget entries you no longer want. **Just turned Memory on?** If the list is empty, run [Memory Catch-Up](/workflows/memory-catch-up) from a fresh Hub chat (**Give Memory a head start**) to seed facts from the last 30 days of chats and meetings before relying on everyday learning. For a full walkthrough, see [Manage Memory](/how-to/manage-memory), [Memory](/workflows/memory), and [Memory Catch-Up](/workflows/memory-catch-up).

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 / Local Plus**: Run on your Mac with downloaded Whisper or Parakeet models * **Cloud**: Online transcription via **Soniox V5** (beta96+); best accuracy for meetings when eligible 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. Modifier-only shortcuts are supported — for example **⌘**, left or right **Control**, or left or right **Option** alone. * **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. 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 (experimental)**: Cloud-only speaker identification; enable calendar and Contacts matching (beta93+) * **Calendars for speaker matching**: Choose Apple calendars used to match events and suggest attendee names * **Contacts for speaker matching**: Resolve attendee emails to display names * **Keep dictation in pasteboard**: Retain voice input in clipboard **Cloud processor:** When **Cloud** is selected as the voice processor, meeting and dictation transcription uses the **Soniox V5** engine (beta96+) for improved accuracy. Requires login and cloud dictation eligibility. 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 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") 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. 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. 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 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**: Center, Top Left, Top Right, Bottom Left, Bottom Right, Top Center, or Last Position (Top Right is the default for new installs) * **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 Appearance Settings - Dark Theme Appearance Settings - Light Theme 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") 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. 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 For **LM Studio**, **OpenRouter**, **Ollama**, **Bifrost**, and **Gemini** providers, Alter automatically detects each model's context window, thinking capability, and vision support when you refresh the model list — no manual metadata entry required. **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 API Keys - Providers Configured API Keys - No Providers API Keys - Provider Configuration API Keys - Add Provider Modal 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 Router Settings

9. Gateways Settings

The **Gateways** tab (under **Integrations** in the settings sidebar, alongside **API keys** and **Router**) connects Alter to **Discord** and **Telegram** bots. Internal builds also support **Buzz**. Open **Settings** (⌘,) → **Integrations** → **Gateways**. Full setup walkthroughs: * [Gateways overview](/apps-tools/gateways) * [Set up a Buzz gateway (internal)](/apps-tools/gateways-buzz) * [Set up a Discord gateway](/apps-tools/gateways-discord) * [Set up a Telegram gateway](/apps-tools/gateways-telegram) **List and add gateways** * **Add gateway** — Create a **Discord** or **Telegram** connection. Internal builds also offer **Buzz**. * Each row shows the gateway **Name**, platform, and an enabled/disabled indicator. **Keep gateways online with the lid closed** (MacBook) At the top of the Gateways page: * **Toggle** — When on (default), Alter keeps active gateway bots connected while the MacBook lid is closed. Normal sleep returns when the last gateway stops. * **Allow…** — One-time administrator permission to change a protected macOS sleep setting (`pmset disablesleep`). Required the first time lid-closed availability activates while a gateway is running. * **Options…** — Opens **Lid-closed availability**: * **Gateway availability** status (for example *Keeping this Mac awake*, *Paused for low battery*) * **Pause below** — Battery floor while unplugged (default 20%, range 5–50%). Alter restores normal sleep at or below this level and re-enables after charging above it. * **Pause in Low Power Mode** — Always on; honors the system power-saving preference. * **Remove administrator permission…** — Revokes the installed permission. Turning the main toggle off does **not** remove permission. **Per-gateway fields** | Section | Fields | | --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | General | **Name**, **Enabled** | | Connection (Buzz, internal) | **Agent name**, **Buzz invite link**, **Connect Alter**, **Advanced connection settings** (community URL, Nostr private key, optional owner auth tag), channel selection, **Default scheduled destination**, **Allowed Nostr pubkeys or npubs**, **Require a mention in shared channels**, **Buzz gateway setup guide** link | | Connection (Discord) | **Bot token**, **Server ID (optional)**, **Ready message channel ID (optional)**, **Allowed Discord user IDs**, **Require a mention in servers**, **Discord gateway setup guide** link | | Connection (Telegram) | **Bot token**, **Allowed Telegram user or chat IDs**, **Telegram gateway setup guide** link | | Behavior | **Default action** — action used for new conversations on this gateway; **Start server discussions in threads** (Discord only, on by default for new gateways); **Start Buzz discussions in threads** and **Limit this Buzz agent to its default action** (Buzz only, internal) | | Available actions | Lists actions enabled for this platform; click one to open **Action Editor → Gateways** | | Footer | **Delete gateway**, **Save and restart**, connection status | Bot tokens are stored in the macOS Keychain. After **Save and restart**, the status line shows whether the bot connected (for example **Connected as @username**). Gateways are not the same as **Settings → Router** (OpenAI-compatible API). See [API Gateway Guide](/api-router/api-gateway) for third-party app integrations via the API.

10. Computer use Settings

The **Computer use** tab configures how Alter's UI automation agent drives apps, browsers, and the floating live preview introduced in **2.0.0-beta100**. Open **Settings** (⌘,) and select **Computer use** in the sidebar — it appears under the API section with the cursor-rays icon, alongside **API keys** and **Router**. The tab is organized into three sections that match the app UI exactly: **Browser**, **Preview**, and **Blocked apps**. #### Browser Give Computer Use its own browser so agent-driven pages stay separate from your daily browsing. **Agent browser** — *The browser the computer-use agent drives* * **macOS default** — `open_urls` inside Computer Use uses your system default browser (out-of-the-box behavior) * **Dedicated browser** — Pick an installed browser (Chrome, Safari, Arc, etc.). During a Computer Use run, pages the agent opens go into this browser only. Links you open yourself, and `open_urls` **outside** Computer Use, still use your macOS default. This lets you stay signed in to sensitive sites in your main browser while the agent uses an isolated profile. **Clean up when finished** * When enabled, Alter closes tabs the agent opened after the **last** Computer Use session ends * For browsers that cannot close individual tabs (for example Firefox), the agent browser is **quit** instead — but **only if the agent launched it**, never a browser you already had open * Requires a dedicated **Agent browser** (disabled when **macOS default** is selected) #### Preview The floating preview shows a live picture-in-picture of the window Computer Use is controlling. **Show preview automatically** — *Reveal the floating preview when a computer-use task starts* * On (default): preview opens when a task starts * Off: runs still happen in the background; open the preview anytime via **Watch preview** in the Tool Inspector on the running task **Preview size** — *Small or large presets, or Custom to keep the size you drag it to* | Option | Width | | ---------- | --------------------------------------------------------- | | **Small** | 320 pt preset | | **Large** | 560 pt preset | | **Custom** | Remembers the size you set by dragging the preview corner | The preview keeps a fixed aspect ratio; you can hide it with the on-window **Hide** control without stopping the run. #### Blocked apps Computer Use refuses to **open, read, or control** apps on this list. Password managers and other sensitive apps are blocked by default: * Keychain Access * Bitwarden * Passwords (macOS) * 1Password / 1Password 7 **Add app…** — Choose one or more `.app` bundles from `/Applications` to block **Restore defaults** — Reset the list to Alter's built-in sensitive-app defaults Remove an app with the minus button on its row. If a goal targets a blocked app, the agent reports the block and stops trying — adjust the list only when you intentionally want Computer Use to control that app. When no apps are blocked, the section shows **No apps are blocked.** in secondary text. #### Permissions reminder Computer Use requires **Accessibility** (to read AX trees and send clicks) and **Screen Recording** (for the live preview and `computer_use_screenshot`). Grant both under **Settings → Permissions** before your first run. If something still fails, open **Settings → Doctor** for a consolidated permission report. Background runs, Edge Bar session cards, and preview behavior are documented in [Background Computer Use](/apps-tools/computer-use-background). Permission issues: [Tools Not Working](/common-issues/tool-not-working) or **Settings → Doctor**.

11. Shortcuts Settings

The **Shortcuts** tab is a searchable editor for every Alter keyboard shortcut. Open **Settings → Shortcuts** (under the **General** section in the sidebar). #### Search and navigation * **Search shortcuts** — Filter by action name, description, category, or key combination * **⌘F** — Focus search while the Shortcuts tab is frontmost * **Esc** — Clear the search field when search is focused Each row shows the action name, a short description, and a **recorder** control. Click the recorder and press your desired keys. If you change a shortcut from its default, a **reset** button (↺) appears to restore the factory binding. #### Global System-wide shortcuts that work from any app (subject to macOS permissions): | Action | Default | Notes | | ---------------------------------- | ----------------------------- | ---------------------------------- | | **Open QuickHub** / **Open notch** | **⌘⇧Space** | Label depends on **QuickHub Mode** | | **Open QuickHub and Attach** | Double **⌘** + attach pickers | See QuickHub attach below | | **Open or Focus the Hub** | **⌘⇧H** | | | **New Hub Chat** | **⌥Space** | | | **Dictation Shortcut** | **Fn** | Empty recorder falls back to Fn | | **Meeting Shortcut** | **⌘⇧M** | Toggle meeting recording | | **Live captions** | **⌘⇧↓** | | | **Live Notepad** | **⌘⇧→** | | #### Open QuickHub and Attach **Open QuickHub and Attach** has two extra pickers beside the shortcut recorder: * **Attach behavior** — **Attach Left** or **Attach Right** (default **Attach Right**) * **Shortcut** — Double-tap trigger: **Double tap ⌘** (default), **Double tap ⌥**, **Double tap ⌃**, **Double tap ⇧**, or **None** Double-tap the chosen modifier to open QuickHub and dock it to the selected side. Documented in [QuickHub Mode](/getting-started/quickhub-mode). #### Hub & QuickHub Shared shortcuts that apply to whichever conversation surface is active: | Action | Default | | ------------------------ | ----------- | | **Command Palette** | **⌘K** | | **New Chat or Tab** | **⌘T** | | **Close Chat or Tab** | **⌘W** | | **Delete Conversation** | **⌘Delete** | | **Previous Chat or Tab** | **⌘⌥←** | | **Next Chat or Tab** | **⌘⌥→** | | **Clear All Contexts** | **⌘⇧X** | | **Quick Actions** | **⌘/** | | **Retry Last Message** | **⌘R** | #### QuickHub Attach and navigation shortcuts specific to the floating QuickHub panel: | Action | Default | | ----------------- | ------- | | **Open in Hub** | **⌘O** | | **Attach Left** | **⌃⌘←** | | **Attach Right** | **⌃⌘→** | | **Detach Window** | **⌃⌘↓** | | **Pin Window** | **⌘⌥P** | #### Hub Hub-window shortcuts including workspace and export actions: | Action | Default | | --------------------------------- | --------------------------------- | | **New Workspace** | **⌘⌥N** | | **Create Workspace from Context** | **⌘J** | | **Switch to Workspace** | **⌘⌥O** | | **Save Conversation as Markdown** | **⌘⇧S** | | **Close All Tabs** | **⌘⌥W** | | **Close Window** | **⌘⇧W** | | **Search** | **⌘F** | | **Jump to Tab 1-9** | **⌘1**–**⌘9** (read-only display) | #### Windows Open Alter's auxiliary windows: | Action | Default | | ----------------- | ------- | | **Alter Hub** | **⌘⇧H** | | **Action Editor** | **⌘⇧E** | | **Tools Manager** | **⌘⇧T** | | **Settings** | **⌘,** | #### Conversation Input and scroll behavior inside QuickHub and Hub conversations: | Action | Default | | --------------- | ------------- | | **Cycle Mode** | **⇧Tab** | | **Scroll Up** | **Page Up** | | **Scroll Down** | **Page Down** | #### Tools The **Tools** section lists **read-only** shortcuts for configured quick-action tools. To edit them, click **Open Quick Actions** — Alter opens **Tools Manager** to the Quick Actions section (**⌘⇧T** or `alter://toolsManager?section=quickActions`). #### Conflicts and reset macOS and other apps may claim the same key combinations. If a shortcut does not fire: 1. Check **System Settings → Keyboard → Keyboard Shortcuts** for conflicts 2. Pick an unused combination in Alter's recorder 3. Click the ↺ reset button to restore Alter's default for that row For a full inventory beyond the settings UI, see [Shortcuts reference](/references/shortcuts). To change only the global open shortcut, [How-To: Change Hotkey](/how-to/change-hotkey) is a focused guide.

12. Marketplace Settings

The **Marketplace** tab (under **Account** in the settings sidebar) controls your public Alter Marketplace profile and notification preferences. What you save here can appear on agent listings and community pages; local-only Alter settings are unaffected. #### Public Profile * **Display Name** — Username shown on your public profile * **Bio** — Up to **160 characters**; a live counter shows `count/160` * **Avatar** — Click the camera badge to pick an image; **Remove** clears the current avatar * **Save Profile** — Uploads changes (disabled until you edit something) Profile data syncs to Alter's account service when you save. Errors appear in red below the form. #### Social Links Optional URLs displayed on your marketplace profile: * **Website** * **GitHub** * **Twitter / X** * **LinkedIn** * **Discord** * **YouTube** Leave a field empty to hide that link publicly. Values are stored with your account profile. #### Notifications * **Comment notifications** — *Get notified when someone comments on your agents or replies to you.* Toggle off to silence marketplace comment alerts while keeping your public profile visible.

13. Doctor Settings

**Doctor** (under **System** in the settings sidebar) runs a health and permission diagnostic across Alter. Use it when tools fail mysteriously, voice processing misbehaves, or you need a redacted report for support. Doctor runs automatically when you open the tab, then shows a summary and detailed sections. #### Summary header * **Alter Doctor** title with **last checked** time * Overall status pill: **OK**, **Warning**, **Failed**, or **Idle** * Count pills: **OK**, **Idle**, **Warn**, **Fail** #### Refresh and Copy Report * **Refresh** — Re-run all checks (shows a progress indicator while running) * **Copy Report** — Copy a **redacted** plain-text report to the clipboard (home directory paths shortened to `~`; JWT/token-like strings replaced). Button briefly shows **Copied** Paste the report into Discord or email when contacting support alongside a [shared task trace](/workflows/share-task-traces) if relevant. #### Diagnostic sections **Environment** * **macOS** — Operating system version string * **Architecture** — `arm64` or `x86_64` **Application** * **Version** — Short version, build number, and configuration (Debug/Release) * **Application Support** — Whether Alter's support directory exists **Permissions** * **Accessibility** — Required for selection read and app control. Links to **Settings → Permissions** when not granted * **Screen Recording** — Required for meeting/screen context and Computer Use preview * **Microphone** — Required for dictation and meeting audio * **Automation** — System Events access for AppleScript-style automation. Starts as **Idle** until you click **Check Automation**; Alter prompts for permission and refreshes the report **Gateways** * **Configured gateways** — **Idle** when no gateways exist * Per gateway: **connection** status (connected, connecting, reconnecting, failed, or disabled) with a shortcut to **Settings → Integrations → Gateways** * Per gateway: **access** — **Warning** when an enabled gateway has no allowlist; **OK** when access is limited to configured IDs **Voice Processor** * **Selected processor** — Current speech engine (Apple, cloud, Whisper, etc.) with link to **Settings → Voice** * **Plan access** — Whether your subscription supports the selected processor * **Local model** / **Local model runtime** (Apple Silicon + Whisper only) — Download and load status **Storage** Disk usage for Application Support, Alter Prompts, Caches, WebKit, and HTTP Storage paths. **Database** Local Core Data schema status: up to date, needs migration, or no store yet. **Actions** Loaded Alter Actions count (enabled, user-authored, total). **Tools** * **Activated tools** — Count with **Open the Tools Manager** shortcut to the Active Tools section * **MCP configuration** — Connected apps and remote MCP servers * **MCP clients** — Per-server runtime status (running, stopped, error) **Search** * **Conversations** / **Transcripts** — Indexed record counts; **Warning** while re-indexing * **Notes** — Whether Apple Notes tools are active #### Section actions Some sections include footer buttons: * **Open Permissions**, **Open Voice**, **Open Billing** — Jump to the relevant settings tab * **Open the Tools Manager** — Deep-link to MCP or active tools sections * **Check Automation** — Trigger System Events permission check (Permissions section) #### Doctor vs common-issues pages | Situation | Start here | | ----------------------------------- | ---------------------------------------------------------------------------------------------- | | Broad "something is wrong" | **Settings → Doctor** | | Hotkey stopped working | [Keyboard Shortcut Not Working](/common-issues/hotkey-not-working) | | Mic not transcribing | [Microphone Not Working](/common-issues/mic-not-transcribing) | | Tool or MCP failure | [Tools Not Working](/common-issues/tool-not-working) + Doctor **Tools** section | | Gateway connection or access issues | Doctor **Gateways** section + [Gateways troubleshooting](/apps-tools/gateways#troubleshooting) | | Computer Use permission errors | Doctor **Permissions** + [Computer use settings](/how-to/settings-guide#computer-use) | ## 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) * [Gateways](/apps-tools/gateways) * [Computer Use overview](/apps-tools/computer-use) * [Background Computer Use](/apps-tools/computer-use-background) * [QuickHub Mode](/getting-started/quickhub-mode) * [Edge Bar](/getting-started/edge-bar) * [Share task traces](/workflows/share-task-traces) * [Shortcuts reference](/references/shortcuts) # 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. Flow reduces context usage by acting as a single tool that routes requests to the appropriate integration automatically. 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**. ## Coding tools **Tools Manager → Local Tools → Coding** lists four local coding integrations: | Provider | Connect when | | ------------ | ----------------------------------------------------- | | **ChatGPT** | You use the ChatGPT desktop app for agentic coding | | **Cursor** | You have the Cursor Agent CLI (`agent`) installed | | **OpenCode** | You use the OpenCode CLI, including terminal sessions | | **Claude** | You use Claude Code (`claude`) in Terminal | **Fastest path:** install a specialized agent from **[Marketplace → Browse](https://alterhq.com/marketplace)** — for example the live [ChatGPT Agent](https://alterhq.com/marketplace/chatgpt-agent). On first run, Alter prompts you to enable the linked coding tool. See [Coding tools — Marketplace onboarding](/workflows/coding-tools#get-started-from-the-marketplace-recommended). Connect only the providers you need. Each exposes run, list, control, and settings tools to Alter's model when enabled for the current action. Prerequisites, workspace permissions, and provider differences ## 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. 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 with QuickHub, Edge Bar, and deep Hub workflows Learn the basics and start using Alter in minutes. ## Start in 10 Minutes Go to the [Quickstart guide](/quickstart) and complete the install and setup steps. Open [QuickHub Mode](/getting-started/quickhub-mode) and try: * **⌘⇧Space** to open QuickHub * [Edge Bar](/getting-started/edge-bar) from a screen edge * Speaking a simple request with voice 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) ## Quick Access Default floating chat, attach to apps, and open shortcuts. Screen-edge launcher for meetings, chats, and Computer Use sessions. Learn how Alter understands your app context and files. Start dictation, transcription, and meeting follow-up workflows. Pick local vs cloud model workflows based on privacy and speed. Build repeatable workflows with Workspaces and Actions. ## Popular Topics Step-by-step guides for common actions. Solutions to common issues and problems. Connect Alter with your favorite tools. Answers to frequently asked questions. ## Need Help? Join our community Watch tutorials Contact support # 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 Download Alter from our [website](https://alterhq.com/beta). System requirements: * macOS 14.6 or later (Sonoma) * Apple Silicon or Intel Mac 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) Alter needs these permissions to provide full functionality like reading selected text and capturing context. ### Step 2: Initial Configuration 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. In **Settings → Shortcuts → Global**: * Set **Open QuickHub** (or **Open notch** if QuickHub Mode is off) — default: **⌘⇧Space** * Configure other global shortcuts (Hub, New Hub Chat, dictation) as needed In **Settings → General**, enable the **Selection Button** for quick access when selecting text. ### Step 3: Start Using Alter 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 Press `/` in the prompt box to see available AI models and select your favorite! ## Next steps Now that you're set up, explore these key features: Discover AppSense, Follow Mode, actions, and workspaces. Master speech-to-text and voice automation. Let one tool orchestrator handle the right actions automatically. Keep your conversations accurate and fast over time. **Need help?** Check our [FAQ](/references/faq-core), join our [Discord](https://discord.gg/gvCMmfBRWZ), or email [hi@alterhq.com](mailto:hi@alterhq.com). # 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 AI models available through the Alter API Router. Use these model names when making API requests. **Model lists change frequently.** New models ship with each beta. This page is a snapshot — verify live availability in **Settings → Router** or your API client's model picker. Names follow `Provider#Model-name` (for example `OpenAI#gpt-5`). ## 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 | ## Recent additions (beta71–beta100) These models were added in recent betas. Availability may vary by plan and region. | Model Name | Added | Notes | | ---------------------------- | --------- | ----------------------------- | | `GLM#glm-5.2` | beta100 | Zhipu GLM 5.2 | | `Deepseek#deepseek-v4-flash` | beta100 | Fast Deepseek V4 | | `Deepseek#deepseek-v4-pro` | beta100 | Full Deepseek V4 | | `Minimax#minimax-m3` | beta100 | Minimax M3 | | `Cerebras#gemma-4-31b` | beta100 | Cerebras-hosted Gemma 4 31B | | `GLM#glm-5.1` | beta80–82 | Prior GLM release | | `Minimax#minimax-2.7` | beta80–82 | Minimax 2.7 | | `Qwen#qwen-3.6-plus` | beta80–82 | Qwen 3.6 Plus | | `Cerebras#zai-glm-4.7` | beta63+ | High-speed Cerebras inference | Exact provider prefixes and slug spelling match the Alter router catalog. If a name fails, check **Settings → Router** for the current string or use `Alter#best` for automatic selection. ## 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` * `Cerebras#gemma-4-31b` **For Quality** * `Alter#best` * `OpenAI#gpt-5` * `Claude#claude-opus-4-6` * `Gemini#gemini-2.5-pro` * `Deepseek#deepseek-v4-pro` **For Coding** * `OpenAI#gpt-5` * `Mistral#codestral-2501` * `Claude#claude-sonnet-4-6` * `GLM#glm-5.2` **For Vision** * `OpenAI#gpt-5` * `Gemini#gemini-2.5-pro` * `Mistral#pixtral-large-latest` **For Cost** * `Alter#fair` * `Alter#light` * `OpenAI#gpt-5-nano` * `Deepseek#deepseek-v4-flash` ## Related * [Choose your generative model](/how-to/choose-generative-model) * [API Router overview](/references/api-router-overview) # 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) | | Guides index | [Guides](/getting-started/guides-index) | | QuickHub Mode | [QuickHub Mode](/getting-started/quickhub-mode) | | Edge Bar | [Edge Bar](/getting-started/edge-bar) | | Open Alter | [Open Alter](/getting-started/open-alter) | | 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) | | Split Panel | [Split Panel](/getting-started/split-panel) | | Context bridging (split) | [Split Panel — Bridge context between panes](/getting-started/split-panel#bridge-context-between-panes) | | Conversation History | [Window Types: Notch, Hub, and Panels](/getting-started/window-types-notch-hub-panels#conversation-history) | | Find in conversation | [Window Types — Search and filter](/getting-started/window-types-notch-hub-panels#search-and-filter-conversations) | | Search all conversations | [Shortcuts — Alter Hub Window](/references/shortcuts#alter-hub-window) | | Hub sidebar filters | [Window Types — Search and filter](/getting-started/window-types-notch-hub-panels#search-and-filter-conversations) | | Turn navigation | [Window Types — Search and filter](/getting-started/window-types-notch-hub-panels#search-and-filter-conversations) | | Thinking effort | [Choose your generative model — Thinking effort](/how-to/choose-generative-model#thinking-effort) | | 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) | | Memory | [Memory](/workflows/memory) | | Start feeding Memory (Catch-Up) | [Memory Catch-Up](/workflows/memory-catch-up) | | Memory Catch-Up | [Memory Catch-Up](/workflows/memory-catch-up) | | Manage Memory | [Manage Memory](/how-to/manage-memory) | | 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) | | Thinking effort | [Choose your generative model — Thinking effort](/how-to/choose-generative-model#thinking-effort) | | 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) | | Speaker matching | [Meetings Guide](/workflows/meetings#speaker-identification) | | Live Captions | [Meetings Guide](/workflows/meetings#live-captions) | | Accessing Transcripts | [Meetings Guide](/workflows/meetings#managing-transcripts) | ## Settings | Section | Location | | ------------------ | ---------------------------------------------------------- | | Accessing Settings | [Alter Settings](/how-to/settings-guide) | | General | [Alter Settings](/how-to/settings-guide#general) | | Memory Settings | [Alter Settings](/how-to/settings-guide#memory) | | Manage Memory | [Manage Memory](/how-to/manage-memory) | | Voice Settings | [Alter Settings](/how-to/settings-guide#voice) | | 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) | | Gateways | [Alter Settings](/how-to/settings-guide#gateways) | | Computer use | [Alter Settings](/how-to/settings-guide#computer-use) | | Shortcuts | [Alter Settings](/how-to/settings-guide#shortcuts) | | Marketplace | [Alter Settings](/how-to/settings-guide#marketplace) | | Doctor | [Alter Settings](/how-to/settings-guide#doctor) | ## Integrations & Tools | Section | Location | | ----------------------------- | -------------------------------------------------------------------------------------------------- | | Integrations Overview | [Integrations Guide](/apps-tools/integrations-overview) | | Gateways | [Gateways](/apps-tools/gateways) | | Buzz gateway setup (internal) | [Buzz gateway (internal)](/apps-tools/gateways-buzz) | | Discord gateway setup | [Set up a Discord gateway](/apps-tools/gateways-discord) | | Telegram gateway setup | [Set up a Telegram gateway](/apps-tools/gateways-telegram) | | Local Tools | [Integrations Guide](/apps-tools/integrations-overview#local-tools) | | Coding tools | [Coding tools](/workflows/coding-tools) | | Marketplace coding agents | [Coding tools — Marketplace](/workflows/coding-tools#get-started-from-the-marketplace-recommended) | | ChatGPT Agent (Marketplace) | [ChatGPT Agent](https://alterhq.com/marketplace/chatgpt-agent) | | ChatGPT coding tasks | [Coding tools — ChatGPT](/workflows/coding-tools#chatgpt-codex) | | Cursor coding tasks | [Coding tools — Cursor](/workflows/coding-tools#cursor) | | OpenCode sessions | [Coding tools — OpenCode](/workflows/coding-tools#opencode) | | Claude Code sessions | [Coding tools — Claude](/workflows/coding-tools#claude-code) | | 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) | | Share task traces | [Share and Export Task Traces](/workflows/share-task-traces) | | Background Computer Use | [Background Computer Use](/apps-tools/computer-use-background) | | Computer Use agent | [Computer Use](/apps-tools/computer-use) | | Computer Use agent tools | [Computer Use Agent Tools](/apps-tools/computer-use-agent-tools) | ## 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) | | Add context | [How-To: Add Context](/how-to/add-context) | | Seed Memory from history | [Memory Catch-Up](/workflows/memory-catch-up) | | 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 | [Meetings Guide](/workflows/meetings) | | Memory Workflow | [Memory](/workflows/memory) | | Seed Memory from history | [Memory Catch-Up](/workflows/memory-catch-up) | | Memory Catch-Up | [Memory Catch-Up](/workflows/memory-catch-up) | | 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 **⌘⇧Space** (default quick-open shortcut; customize in **Settings → Shortcuts → Global**). 3. Hold `Fn` and speak. 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. 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. 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. Settings menu See [Alter Settings](/how-to/settings-guide) for more details. ## How do I configure dictation? **Settings → Voice**, then choose processor, language, and replacements. 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 requires **macOS 14.6 or later** (Sonoma) 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 | | -------------------------------- | ----------------------------------------------------- | ------------------------------------ | | Gateways settings | *(not yet captured)* | Settings → Integrations → Gateways | | Discord — create application | `/images/gateways/discord/create-app.png` | Developer Portal General Information | | Discord — Add Bot | `/images/gateways/discord/add-bot.png` | Developer Portal Bot page | | Discord — Message Content Intent | `/images/gateways/discord/message-content-intent.png` | Privileged Gateway Intents | | Discord — bot token | `/images/gateways/discord/created-bot.png` | Reset Token on Bot page | | Discord — OAuth2 bot scope | `/images/gateways/discord/oauth2-bot-scope.png` | OAuth2 URL Generator scopes | | Discord — OAuth2 bot permissions | `/images/gateways/discord/oauth2-bot-permissions.png` | OAuth2 URL Generator permissions | | Discord — bot authorization | `/images/gateways/discord/bot-auth-page.png` | Invite URL authorization page | | Telegram — BotFather search | `/images/gateways/telegram/botfather-search.png` | Finding @BotFather | | Telegram — /newbot command | `/images/gateways/telegram/newbot-command.png` | Starting bot creation | | Telegram — bot username prompt | `/images/gateways/telegram/newbot-name-username.png` | Choosing a bot username | | Telegram — token message | `/images/gateways/telegram/bot-token-message.png` | BotFather success + token | | 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. **Private and local-first:** Alter does not use cloud sync to keep a backup of your chats, meeting transcripts, or local history. ## What stays on your Mac * Chat history * Meeting transcripts and recordings * Saved Memory facts and their local provenance links * 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 Do not uninstall Alter if you want to keep your existing data. 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 * **Cmd + Shift + Space** (default): Open QuickHub — configurable in **Settings → Shortcuts → Global** as **Open QuickHub** (or **Open notch** when QuickHub Mode is off) * **Option + Space** (default): New Hub Chat — configurable in **Settings → Shortcuts → Global** * **Speech-to-text hotkey**: Start voice input — configurable in **Settings → Voice → Shortcuts** (default: Fn key) ### QuickHub When QuickHub Mode is on (default). Configure in **Settings → Shortcuts → QuickHub** and **Global**: * **Shift + Cmd + Space** (default): Open QuickHub — **Settings → Shortcuts → Global → Open QuickHub** * **Double tap ⌘** (default): Open QuickHub and Attach — **Settings → Shortcuts → Global → Open QuickHub and Attach** (attach side: **Attach Left** or **Attach Right**) * **Ctrl + Cmd + ←**: Attach Left — dock QuickHub beside the active app * **Ctrl + Cmd + →**: Attach Right * **Ctrl + Cmd + ↓**: Detach Window — return to floating QuickHub * **Cmd + Option + P**: Pin Window * **Cmd + O**: Open in Hub — move current QuickHub chat to the Hub window See [QuickHub Mode](/getting-started/quickhub-mode) and [Edge Bar](/getting-started/edge-bar). ### Hub & QuickHub (shared) When a Hub tab or QuickHub conversation is focused (**Settings → Shortcuts → Hub & QuickHub**): * **Cmd + K**: Command Palette * **Cmd + T**: New Chat or Tab * **Cmd + W**: Close Chat or Tab * **Cmd + Delete**: Delete Conversation * **Cmd + Option + ←** / **→**: Previous / Next Chat or Tab * **Cmd + Shift + X**: Clear All Contexts * **Cmd + /**: Quick Actions * **Cmd + R**: Retry Last Message ### Hub-only #### Split Panel When the Hub is focused (**Settings → Shortcuts → Hub & QuickHub**): | Shortcut | Action | | -------- | ------------------------------------------------- | | **⌘⌥N** | **Split Right** — open a second conversation pane | | **⌃⌘←** | Focus left pane | | **⌃⌘→** | Focus right pane | | **⌃⌘⇧←** | Move active tab to left pane | | **⌃⌘⇧→** | Move active tab to right pane | | **⌃⌘↓** | **Close Split** — merge panes into one | Also available from **Window → Split Right**, the tab bar split icon, or **⌘K → Split Right**. See [Split Panel](/getting-started/split-panel) for context bridging between panes. * **Cmd + Shift + S**: Save Conversation as Markdown * **Cmd + Ctrl + W**: New Workspace * **Cmd + J**: Create Workspace from Context * **Cmd + Option + O**: Switch to Workspace * **Cmd + Option + W**: Close All Tabs * **Cmd + Shift + W**: Close Window ### QuickHub (legacy notch — QuickHub Mode off) When QuickHub Mode is off, the compact panel opens from the notch: * **←**, **↑**, **→**, **↓**: Navigate between objects * **Enter**: Select an object ### Conversation When a QuickHub or Hub conversation is focused (**Settings → Shortcuts → Conversation**): * **Shift + Tab**: Cycle input mode * **Page Up** / **Page Down**: Scroll the conversation or result list one page #### Find in conversation When a conversation tab is active in the Hub or QuickHub: | Shortcut | Action | | -------- | ------------------------------------------------------- | | **⌘F** | **Find in Conversation…** — search inside the open chat | | **⌘G** | **Find Next** match | | **⇧⌘G** | **Find Previous** match | Find in Conversation is also available from the **Edit** menu. It searches message text in the current conversation only — not your full Hub history. ### Tools (per-tool shortcuts) Tool-specific shortcuts are **not** in `AppShortcuts.swift` — they are configured per enabled tool: 1. Open **Tools Manager** (**⌘⇧T**) 2. Select a tool with shortcut support 3. Assign or edit its shortcut View and search all tool shortcuts in **Settings → Shortcuts → Tools**. Read-only entries link back to Tools Manager for editing. Quick Actions shortcuts are edited from Tools Manager → **Quick Actions** (also reachable via **Open Tools Manager** in the Shortcuts tab). Common window shortcuts from **Settings → Shortcuts → Windows**: | Shortcut | Action | | -------- | ------------- | | **⌘⇧H** | Alter Hub | | **⌘⇧E** | Action Editor | | **⌘⇧T** | Tools Manager | | **⌘ ,** | Settings | ### Context Section * **←**, **↑**, **→**, **↓**: Navigate between contexts * **Space Bar**: Add/remove selected context(s) * **Cmd + Shift + X**: Clear all contexts from the active conversation * **Cmd + K**: Open Command Palette (Hub & QuickHub switcher) * **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 * **⇧⌘F** (default): **Search All Conversations…** — focus the Hub sidebar search field and search across saved chats and meeting transcripts (**Settings → Shortcuts → Hub → Search All Conversations**) * **⌘F**: **Find in Conversation…** when a conversation tab is focused (see [Find in conversation](#find-in-conversation) above) * **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 + Shift + X**: Clear all contexts (requires active contexts) * **Cmd + K**: Open Command Palette * **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 + Opt + N**: Split Right (second pane) * **Ctrl + Cmd + ←** / **→**: Focus left / right pane (when split) * **Ctrl + Cmd + Shift + ←** / **→**: Move tab to left / right pane (when split) * **Ctrl + Cmd + ↓**: Close Split * **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 **Alter Actions** are customizable AI workflows that let you create specialized assistants for specific tasks. Combine AI instructions, voice triggers, tools, and conditional execution to automate anything on your Mac. ## What is an Alter Action? An **Alter Action** is an advanced automation that combines: * **AI Instructions** - System prompts defining how the AI behaves * **Triggers** - Voice commands, hotkeys, or conditional execution * **Context** - Access to selected text, files, active applications * **Tools** - Configured integrations with your Mac and 2000+ external services * **Output** - How results are displayed (markdown, code, inline insertion) Think of an Alter Action as a "specialized AI assistant" customized for a specific task. ## Opening the Action Editor ### Method 1: Menu Bar (Fastest) 1. Click the **Alter menu icon** in the menu bar (top right) 2. Select **Action Editor** Menu Bar ### Method 2: Options Menu 1. Open Alter window 2. Click **⋯** (three dots) in top right 3. Select **Action Editor** Options Menu ### Method 3: Keyboard Shortcut Press **⌘⇧E** (Command + Shift + E) to open the Action Editor directly The keyboard shortcut is the fastest method once you've memorized it. ## Action Editor Walkthrough The Action Editor has 7 main sections, each controlling different aspects of your action. Use the left panel to navigate between tabs. ### 1. General Settings Configure basic metadata and execution context. General Tab **Fields:** * **Name** - Human-readable action name (e.g., "Code Explainer") * **Description** - What this action does (optional) * **Category** - Organize actions by type (code, productivity, business, etc.) * **Workspace** - Assign to a specific workspace (optional) * **Include Profile** - Include user profile information in AI context **Visibility Options:** * **Show only when running** - Action only appears if an app is running * **Show only when active** - Action only appears if an app has focus * **Workspace context** - Choose which workspace(s) see this action Each action gets a unique UUID automatically. ### 2. System Prompt Define AI instructions and parameters for the model. System Prompt Tab **System Prompt** - Core AI instructions describing the AI's behavior and expertise. **Example:** ``` # 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. 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. When to Show Tab **Visibility Conditions:** * **Installed Applications** - Show action only in specific apps (VSCode, Xcode, Safari, etc.) * **Application is running** - Action requires the app to be running * **Application has focus** - Action only works when app is in foreground * **Web browser tab contains** - Show action when browsing specific domains * **Has content** - Show action only when context is available ### 5. Automation Configure execution behavior, schedules, and background processing. Automation Tab **Fields:** * **Background Job** - Run action in background without showing UI * **Schedules** - Execute action at specific times (e.g., "Every Monday at 9 AM") * **Quick Action** - Execute the next "Quick Action" automatically after this completes Use this for action chaining: first action → output → next action executes automatically. ### 6. Tools Scope which tools are available for this action. Tools Tab **Tool Configuration:** * **Disable Tools** - Toggle off individual tools to restrict functionality * When empty: All tools are available * When configured: Only selected tools are available **Ask Anything defaults (beta100+):** The built-in **Ask Anything** action enables **Flow**, **Computer Use**, and **Ask User** out of the box. Customize or duplicate it if you want a narrower tool set. **Memory:** Link the **Memory** tool when an action should read saved facts or search prior chats and meetings. Memory is not enabled for every action by default. See [Memory](/workflows/memory) and [Manage Memory](/how-to/manage-memory). The built-in **Memory Catch-Up** action ships with Memory already linked. It is Alter's trusted way to bootstrap Memory from the last 30 days of chats and meetings—recommended when you first enable Memory or want to backfill recent history. See [Memory Catch-Up](/workflows/memory-catch-up). **Coding tools (post-beta106):** The fastest path is a [Marketplace coding agent](/workflows/coding-tools#get-started-from-the-marketplace-recommended) — download from **Tools Manager → Marketplace → Browse** (for example the live [ChatGPT Agent](https://alterhq.com/marketplace/chatgpt-agent)) and run it once; Alter enables the required coding integration on first use. Alternatively, under **Local Tools → Coding**, connect **ChatGPT**, **Cursor**, **OpenCode**, and/or **Claude** in **Tools Manager** first, then scope which providers each action may use — for example a release action might enable **Cursor** only. Coding sessions run asynchronously; results return to the originating conversation. See [Coding tools](/workflows/coding-tools). **Why Scope Tools?** * Reduce AI decision overhead (focus on relevant tools) * Speed up action execution * Improve security (limit what actions can access) ### 7. Model Select AI model, thinking effort, and creativity level. Model Tab **Fields:** * **Model** — Searchable picker grouped into **Current**, **Favorites**, and **Other models**. Leave empty to use the user's default model setting, or pin a specific model for this action. * Each row shows context length, vision support, and favorites * When the model supports it, adjust **Thinking effort** (**Low**, **Balanced**, **Max**) inline * **Temperature** - Adjust creativity vs. precision * **0.0** - Deterministic (consistent, predictable) * **0.5** - Balanced (default) * **1.0** - Creative (unpredictable, exploratory) Alter remembers thinking effort **per model** across Hub, QuickHub, and the Action Editor. Use **⌘F** in the Action Editor sidebar to search actions. Click the filter icon to narrow by background jobs, schedules, warnings, modified actions, or **Folders** (action categories). Folder filters include **All** and **None** shortcuts. ### 8. Gateways Choose the exact gateway connections that can use this action. Every configured Buzz, Discord, and Telegram gateway has its own toggle, so two accounts on the same platform can have different access. **Buzz gateway (internal)** — Buzz appears only in internal Alter builds for the dev team. See [Buzz gateway (internal)](/apps-tools/gateways-buzz). **Availability** — Gateway toggles: | Setting | Effect | | ------------------- | --------------------------------------------------------------- | | All toggles off | Local-only (Hub, QuickHub, etc.) | | A gateway on | Available only from that named gateway connection | | Several gateways on | Available from exactly those connections, even across platforms | | All toggles on | Available from every currently configured gateway | The bundled **Ask Anything** action initially appears on all compatible gateways. Custom actions start local-only until you enable one or more gateway toggles. Changing any toggle saves an explicit list of gateway connections, so a gateway added later does not inherit that action automatically. On Gateways, **parameterless actions** (no input fields) run immediately when picked from **Choose action**; **parameterized actions** wait for the user's next message. **Scheduled gateway delivery** — When an action runs on a schedule, enable **Start scheduled conversations on a gateway**, choose an enabled **Discord**, **Telegram**, or **Buzz** *(internal)* gateway, then pick a **Destination** (channel, chat, or Buzz stream). Alter posts the action's opening response there instead of only running locally. Buzz gateways can also set a **Default scheduled destination** in **Settings → Integrations → Gateways**. See [Gateways](/apps-tools/gateways) for setup, chat commands, scheduled delivery, and gateway settings. ## Best Practices "Code Explainer" describes what it does. Avoid generic names like "Action 1". Be detailed with AI instructions. Generic prompts produce generic outputs. Enable only the tools your action needs. Reduces overhead and improves speed. `{{ textSelection }}` always works. Manual copy/paste is error-prone. "Code Explainer" only in VSCode + Xcode reduces menu clutter. Test with real data before deploying to your team. ## Common Action Examples ### Example 1: Code Explainer **Setup:** * **Name:** Explain Code * **Category:** code * **Installed Apps:** VSCode, Xcode * **System Prompt:** You are an expert programmer who explains code clearly * **User Prompt:** `Please explain this code:\n\n{{ textSelection }}` * **Consumer:** markdown * **Temperature:** 0.5 ### Example 2: Email Draft Creator **Setup:** * **Name:** Draft Email * **Category:** productivity * **When to Show:** Mail app active * **System Prompt:** You are a professional business communicator * **User Prompt:** `Transform this into a professional email:\n\n{{ textSelection }}` * **Tools:** Enable only Mail * **Consumer:** in-place * **Temperature:** 0.6 ### Example 3: Scheduled Daily Brief **Setup:** * **Name:** Daily Brief * **Category:** productivity * **Automation:** Schedule for 9:00 AM daily * **Background Job:** Enabled * **System Prompt:** Generate a daily brief of priorities ## Voice Triggers Assign voice hotkeys to trigger actions hands-free: Go to **Settings > Voice Triggers** Click **+ Add Trigger** Choose action from dropdown Enter trigger phrase (e.g., "explain" for Code Explainer) Click Save and you're ready **Usage:** Hold voice hotkey + say trigger phrase → Action executes with current context ## x-callback-url Integration Trigger Alter actions from **any application** using special URLs. This enables powerful cross-app automation workflows. ### What is x-callback-url? x-callback-url is an inter-app communication protocol that lets applications trigger actions in each other through formatted URLs. * **Inbound** - Trigger Alter actions from other apps (Shortcuts, Notes, Safari, etc.) * **Outbound** - Create links in Alter that open other apps (Bear, OmniFocus, Drafts, etc.) ### Getting Your Action's Callback URL Press **⌘⇧E** Choose the action you want to expose Navigate to General tab Look for "URL Callback" section Copy the `alter://` URL **Format:** ``` alter://action/{action-id}?input=VALUE¶m2=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 Trigger action from Calendar → Generate meeting notes → Create email draft Notion button → Trigger Alter action → Update task status Copy text → Trigger action with callback → Open result in external app (no manual copying needed) ## Keyboard Shortcuts | 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 * Check **When to Show** settings * Verify app is running/active (if configured) * Ensure action is **enabled** * Review **System Prompt** — be more specific * Adjust **Temperature** (lower for precision, higher for creativity) * Check **User Prompt** — ensure variables are correct * Verify hotkey is configured in Settings * Check microphone permissions * Test with manual trigger first * Go to **Tools** tab * Verify tools aren't disabled * Check system permissions for the tool ## 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 **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. ## 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. In Alter's notch menu, find the **Open The Hub** section (or **Shift + , Cmd + H**) Click **+ New Workspace** New Workspace Select your blog repository, or any folder containing your content structure. Workspace Add Files Give it a memorable name like "Blogging Workspace" and save ### 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`. Skill Folder Structure 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. 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. ### 3. Import your custom skill into Alter Once your skill is created, add it first to Alter then to your blogging workspace. In Alter's notch menu, find the **Tools Manager** section (or **Shift + , Cmd + T**) 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. import skill Back in the Hub, find your "Blogging Workspace" and open it Look for an option to add capability. Select your newly created skill. add capability add custom skill Confirm that your skill is now mounted in this workspace skill enabled ### 4. Create a mode to activate everything instantly Modes let you switch your entire setup (workspace + skills) with a single hotkey. In Alter's notch menu, find the **Action Editor** section (or **Shift + , Cmd + E**) Click **+** to create a new action. * **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`) Tool Manager Add Mode Save the mode. Now you can activate it anytime with your hotkey. ### 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 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") # Coding tools Source: https://docs.alterhq.com/workflows/coding-tools Run local coding sessions from Alter through ChatGPT, Cursor, OpenCode, and Claude Code **Coding tools** let Alter start and manage **persistent local coding sessions** on your Mac. Ask in natural language from the Hub, QuickHub, or a custom action — Alter launches the session in the background and **brings the result back into the same conversation** when the turn finishes. Alter does not replace your coding agent. It orchestrates the tools you already use — **ChatGPT** (Codex), **Cursor Agent CLI**, **OpenCode**, and **Claude Code** — so you can plan, delegate, steer, and review from one place. ## What you can do * Start a coding task against a project folder or a detached scratch session * Continue the same session across follow-up messages in one Alter chat * Steer, stop, or answer approval prompts for running tasks (provider-dependent) * Scope coding tools per action in the Action Editor * Route coding requests through **Flow** when you have several integrations enabled ## Prerequisites Install and sign in to the providers you want before running a coding agent. | Provider | What Alter needs | Sign-in | | ------------ | ---------------------------------------------------------------------------------------------------- | ------------------------------------------- | | **ChatGPT** | [ChatGPT](https://chatgpt.com) desktop app (`ChatGPT.app` or `Codex.app`) with the bundled Codex CLI | Your ChatGPT account in the app | | **Cursor** | [Cursor Agent CLI](https://cursor.com) (`agent` on your PATH) | Cursor account in the CLI | | **OpenCode** | [OpenCode CLI](https://opencode.ai) (`opencode` on your PATH) | Provider credentials configured in OpenCode | | **Claude** | [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code) (`claude` on your PATH) | Run `claude auth login` in Terminal | Alter detects these tools from standard install locations (`/Applications`, `~/.local/bin`, Homebrew, and your login shell `PATH`). If a provider is missing, open its app detail page in **Tools Manager** for install guidance. ## Get started from the Marketplace (recommended) Alter publishes **specialized coding agents** on the [Alter Marketplace](https://alterhq.com/marketplace). Each agent is a pre-built Alter Action scoped to one coding provider — system prompt, tool links, and defaults included — so you do not have to wire up coding tools yourself. Press **⌘⇧T** and select **Browse** under **Marketplace**, or open a listing at [alterhq.com/marketplace](https://alterhq.com/marketplace). Choose the agent for your coding tool and click **Download**. Alter imports it as an enabled action under **Installed**. Click **Try Now** or run the action from the Hub. On first use, Alter opens **Set Up Tools** and enables the required coding integration when you confirm. Describe the task — include a project path when Alter does not already have workspace context. ### Marketplace coding agents **Available** — Programming agent for ChatGPT (Codex). Includes ChatGPT Settings, Run/List/Read/Control/Manage ChatGPT Task. **Coming soon** — Cursor Agent CLI sessions from Alter. **Coming soon** — Claude Code CLI sessions from Alter. **Coming soon** — OpenCode CLI and terminal sessions from Alter. The live **[ChatGPT Agent](https://alterhq.com/marketplace/chatgpt-agent)** listing is in the **Programming** category. It ships with these tools pre-linked: * **ChatGPT Settings** — list models and read or set defaults * **Run ChatGPT Task** — start or continue a Codex session * **List ChatGPT Tasks** — find sessions in this conversation or across ChatGPT * **Read ChatGPT Task** — inspect status, activity, or output * **Control ChatGPT Task** — steer, stop, or answer approval prompts * **Manage ChatGPT Task** — rename or archive sessions After the first successful run, the ChatGPT coding integration stays enabled in **Tools Manager → Local Tools → Coding** for other actions and Hub chats. Prefer a custom workflow? Duplicate a Marketplace agent in the Action Editor, or enable coding tools manually below and scope them per action. See [Alter Actions](/workflows/alter-actions). ## Enable manually in Tools Manager Use this path when you want coding tools in **Ask Anything**, a custom action, or **Flow** without installing a Marketplace agent. Press **⌘⇧T** or choose **Tools Manager** from the menu bar. In the sidebar, select **Local Tools**. Under **Coding**, connect **ChatGPT**, **Cursor**, **OpenCode**, and/or **Claude**. Turn on only the providers you use. From the Hub, ask something small like "List the README headings in this repo" and confirm the task card appears. **Flow** can discover enabled coding providers automatically. Enable **Flow** under **Local Tools → Alter** if you want Alter to pick the right coding tool for mixed requests. See [Use Flow for Tool Orchestration](/workflows/use-flow-orchestration). ## How a coding task runs Describe the change, bug, or review you want — include the project path when Alter does not already have workspace context. The provider runs asynchronously on your Mac. Alter shows a **coding task card** in the conversation with status, task ID, and an **Open in…** link when available. You do not need to poll ChatGPT, Cursor, OpenCode, or a terminal. Keep working in Alter or elsewhere on your Mac. When the session completes, fails, or needs input, Alter inserts an **external task** message in the same conversation and continues the thread so the model can summarize or act on the output. **Keep Alter running** while coding tasks are active. If you quit with ChatGPT or Cursor tasks still running, Alter warns you because it must stay in the menu bar to deliver results and approval requests. ## Workspace permissions Coding tools use a **constrained permission profile** mapped from your active workspace permission. They can edit and test an **authorized project directory** without requiring Alter **Full Access**. | Alter workspace permission | Typical coding access | | -------------------------- | --------------------------------------------------------------------- | | Read-only | Read and plan in the authorized folder | | Read/write | Edit files in the authorized folder | | Full Access | Edit files and run project-scoped commands through the external agent | This is separate from Alter's direct **`workspace_bash`** tool, which still requires **Full Access** on the workspace. Prefer coding tools when you want a dedicated agent to implement changes; use workspace file tools for lighter in-chat edits. When Alter needs access to a folder for the first time, it prompts you to authorize the project path for that session. ## Provider comparison | | **ChatGPT** | **Cursor** | **OpenCode** | **Claude** | | ----------------------------- | --------------------------- | ----------------- | ---------------------- | ------------------------------------- | | **Runs through** | ChatGPT desktop app (Codex) | Cursor Agent CLI | OpenCode CLI / server | Claude Code CLI | | **Steer mid-turn** | Yes | Yes | Yes | No — wait for the turn, then continue | | **Stop / interrupt** | Yes | Yes | Yes | Yes | | **Answer approvals** | Yes | Yes | Yes | Not from Alter mid-turn | | **Pick up terminal sessions** | — | — | Yes | — | | **Model / effort settings** | Model + thinking effort | Model | Model + effort variant | Model + effort | | **Open link label** | Open in ChatGPT | Open in Agent CLI | Open in OpenCode | Open in terminal |

ChatGPT (Codex)

Best when you already use the **ChatGPT desktop app** for agentic coding. Alter talks to the app's Codex runtime, syncs tasks started elsewhere in ChatGPT when possible, and can steer or answer ChatGPT approval prompts from the Hub.

Cursor

Best when you live in **Cursor** and want Alter to delegate to the **Agent CLI** (`agent`). Alter can steer running turns, handle approval questions, and open the session in Cursor's agent UI. In **Tools Manager → Cursor**, **Run without confirmations** lets Cursor execute commands without per-step approval on writable projects (read-only projects stay limited to questions and planning).

OpenCode

Best for **OpenCode CLI** users who want Alter to continue sessions started in a terminal or pick up existing OpenCode server sessions. OpenCode's model variants map to **effort** on each run.

Claude Code

Best when you standardize on **`claude`** in Terminal. Alter launches print-mode turns with the permissions Claude needs; you authenticate with `claude auth login`. Claude turns **cannot be steered safely mid-flight** — let the turn finish, then ask Alter to continue the same session with a follow-up prompt. ## Tools available to the model Each connected provider exposes a consistent tool set to Alter's model: | Tool pattern | Purpose | | ---------------- | ------------------------------------------------------------------------------------ | | `*_run_task` | Start or continue a session (`prompt`, optional `task_id`, `cwd`, `model`, `effort`) | | `*_list_tasks` | List sessions; use `conversation_only=true` when several tasks exist in one chat | | `*_read_task` | Inspect status, activity, or output for a session | | `*_control_task` | Steer, stop, approve, deny, or answer questions (where supported) | | `*_manage_task` | Rename or archive sessions | | `*_settings` | List models, read defaults, or set model/effort for future or specific tasks | You rarely call these yourself — describe the outcome in natural language and let Alter or **Flow** choose the right tool. ## Use with workspaces and actions **Workspaces** — Attach a workspace when the task spans a codebase Alter should reference. Coding tools honor the workspace's authorized roots and permission level. **Actions** — In the Action Editor **Tools** tab, enable only the coding providers that action needs. For example, a "Ship patch" action might enable **Cursor** and **Flow** but disable **ChatGPT**. **Ask Anything** — The default action does **not** enable coding tools automatically. Install a [Marketplace coding agent](#get-started-from-the-marketplace-recommended), enable providers in **Tools Manager**, or duplicate **Ask Anything** and add coding tools to the **Tools** tab. ## Example prompts * "Use Cursor to add unit tests for `UserStore` in `/Users/me/code/myapp`." * "Continue the OpenCode session we started for the auth refactor." * "Ask ChatGPT to fix the TypeScript errors in this workspace and summarize what changed." * "Run Claude Code on the docs folder — update the README install section only." ## Task cards and inspector While a session runs: * The conversation shows a **coding task card** with provider, title, status, and links * Open the **Tool Inspector** (Hub inspector rail) to see arguments, live status, and **Open in…** actions * Notifications appear when a task completes, fails, or needs input When a task needs approval or answers, respond in the **same Alter conversation** — Alter forwards your choice to the running session. ## Troubleshooting Confirm you clicked **Enable** in the **Set Up Tools** panel when the action first ran. If you skipped a tool, open **Tools Manager → Local Tools → Coding** and connect the provider manually, or re-run the action and accept the setup prompt. Install the desktop app or CLI for that provider, then restart Alter. Confirm the binary is executable from Terminal (`agent --version`, `opencode --version`, `claude --version`, or open ChatGPT.app). Approve the project path when prompted. Coding tools only touch directories you authorize for that workspace or task. Refer to the earlier task in plain language ("continue the Cursor task for the API refactor"). Alter reuses `task_id` when the topic matches; if several sessions exist in one chat, it lists tasks scoped to the conversation first. Expected behavior. Wait for the Claude turn to finish or stop it, then send the next instruction as a continuation of the same session. Confirm Alter is still running in the menu bar and the originating conversation is open. Quitting Alter stops undelivered background work for ChatGPT, OpenCode, and Claude; Cursor tasks are stopped on quit as well. ## Related docs Download the live Marketplace coding agent Connect integrations and manage the Coding category Route coding requests without loading every tool Scope coding tools per action Index codebases and set permission levels How coding tools fit with Mac Apps and external integrations General integration troubleshooting # 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**. Verify Exa pricing and request limits during setup. Free tiers can change. ## 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. Verify current Firecrawl limits, rate caps, and retention before scaling usage. ## 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. Confirm current LinkUp quotas and terms on the official pricing page. ## 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**. Verify current Tavily pricing and limits before production use. Provider plans can change. ## 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 **Speak naturally, work faster.** Alter's dictation goes beyond simple transcription with intelligent voice commands and text transformation. ## 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 In the Action Editor, assign a trigger word or phrase to any Alter Action Hold your voice hotkey (default: `Fn` key) or the mic icon Speak your trigger word or phrase (e.g., "Hey Charlie", "Hey Google") Let go of the hotkey – the action fires immediately ### Practical Examples "Hey Charlie" – Start a conversation with your Mental Model expert "Hey Google" – Trigger a web search action "Hey Translate" – Activate your translation action Create triggers for any frequently-used action ### Setting Up Voice Triggers