Documentation

Current for ahsk 6.14 on macOS. Shortcuts that changed are marked below.

What changed in 6.14

• Changed: Alan is out of beta. Hold Fn + Option and he can also read what is on your screen and write a reply right at your cursor (“reply to this”).
• New: hands-free shows your words live as you speak. Esc cancels a hands-free take without transcribing it. Turn the live text off in Settings › Voice › Live transcript.
• New: image search in the launcher: type find and describe a picture or screenshot. An optional one-time download, Apple silicon only.
• Changed: dictation fits the app: emails get a greeting and sign-off, lists are tidied, and in code editors and terminals file names and commands come out exact.
• Changed: a refreshed design (Liquid Glass pill, cards and launcher), a new onboarding, rebuilt Settings and new, subtler sounds. No shortcut changed.

What changed in 6.13

• New: keep your Mac awake with the lid closed so agents keep running. Menu bar › Keep Awake with Lid Closed, or type awake 2h (or awake, awake off) in the launcher. An eye and the time left show in the menu bar; click it to change or stop. It stops at the time you chose, at 15% battery, or on restart.
• Fixed: Warp no longer shows “Copied to clipboard” when the dictation was pasted.

What changed in 6.12

• Changed: when a dictation can't be pasted (no text box selected, or the app didn't take it), it stays on your clipboard and a card says “Copied to clipboard”. Click where you want it and press ⌘V.
• Fixed: Automatic mic no longer jumps to AirPods or to a MacBook mic behind a closed lid, and a mic you pick by hand is always the one used.

What changed in 6.11.2

• Fixed — a rare freeze during dictation that left the app unresponsive until Force Quit.
• Fixed — a “kAFAssistantErrorDomain error 1107” message on the pill; it came from the live preview and no longer discards the dictation.

What changed in 6.11.1

• Changed — dictation works on slow connections, and if the network cannot carry a dictation within a few seconds the pill says so.
• Changed — the Automatic microphone prefers wired mics (the one in Sound settings, then the built-in) and uses Bluetooth earphones only when nothing else is available. Pin your earphones from the menu-bar Microphone submenu to dictate into them at a desk.

What changed in 6.11

• Added — Alan: hold Fn + Option (or click his face on the pill), say what you want done, let go. Calendar, reminders, contacts and iMessage; Undo after every action; a sent message or a delete asks first. Settings › Alan shows what he can do and what he remembers.
• Deprecated — Respond no longer lives on Fn + Option; ask Alan instead, or use Screenshot + AI (⌥⇧S) for a question about your screen.
• Added — Download Video (⌥⇧D) takes a Spotify track link; the song is fetched from YouTube as audio.

What changed in 6.10

• Changed — Automatic microphone now follows the input your Mac is using — the one in System Settings › Sound, which macOS moves to a headset the moment it connects — then the built-in mic. Virtual devices and the iPhone’s Continuity mic are never picked automatically. Pin a mic from the menu-bar Microphone submenu or Voice › Input.
• Changed — the spoken language defaults to your Mac’s language instead of Auto-detect (Settings › Voice).
• Added — Settings › Tutorials has nine narrated videos with the keys to press under each, and a full-screen button.

What changed in 6.9

• Added — the dictation key is yours to choose: fn by default, or Right Option / Command / Control (onboarding › Edit shortcut, or Settings › Shortcuts). Every chord below follows the key you pick.
• Back, optional — fn + Space starts hands-free again (Space, Return or Tab, chosen in the Shortcuts sheet). A tap of the key alone still does the same.
• Added — hover the pill for Dictate and Record meeting buttons; Settings › Tutorials holds a short video per feature.

What changed in 6.8

• Added — ⌥⇧R starts and stops a meeting recording: your mic and the Mac’s own audio, turned into notes with action items and a mind map. Find them under Settings › Notes. 10 hours/month on every plan; needs macOS 14.2+.

What changed in 6.7

• Renamed — Voice › Output language is now Spoken language, and it is finally sent to the transcriber (it never was before). Default is Auto-detect; name your language for better accuracy with an accent.
• Added — onboarding asks for your spoken language and the language Fn + Shift translates into, with a live try-out. Nothing about the gestures changed.

What changed in 6.5

• Changed — while an answer card is open, Fn no longer starts a new dictation. Hold it (or Option) to ask a follow-up; Return inserts the answer, Esc closes.
• Changed — the microphone defaults to Automatic (since 6.10: the input your Mac is using, then the built-in). Pin a mic from the menu-bar Microphone submenu or Voice › Input.
• Changed — the free tier is your first 10,000 dictated words, counted from this release; Pro is unlimited. Credits are no longer shown.
• Moved — notifications are one switch under Voice › Preferences; the tab is gone.
• Since 6.2 — Fn + Space is retired; a quick tap of Fn starts hands-free dictation instead, and hands-free ends after 30 seconds of silence.

Installation

Getting started with Ahsk is simple. Follow these steps to install and set up the app on your Mac:

1. Download the Ahsk.dmg file from the homepage
2. Open the .dmg file and drag Ahsk to your Applications folder
3. Launch Ahsk from Applications
4. Grant necessary permissions when prompted (Accessibility, Screen Recording, Microphone)

Note: Ahsk requires these permissions to detect text selection, capture screenshots, and enable voice input across all your apps.

Getting Started

Once installed, Ahsk runs quietly in your menu bar, ready to assist you anytime. There are two primary ways to interact with Ahsk:

• Text Selection: Select any text anywhere on your Mac and the Actions menu will automatically appear with AI-powered actions
• Voice Input: Use keyboard shortcuts and voice commands to access features directly without selecting text

Quick Tip: Hold Fn (Globe) to record and release to paste at your cursor — or tap the same key to keep listening hands-free, and tap again to finish. Both work in any app on your Mac.

Free Trial: New users get 10,000 free words to explore all of Ahsk's features. Try voice typing, AI search, translations, and more to see how Ahsk can enhance your workflow.

Spotlight LauncherNEW IN 5.3

A Cmd+Space style launcher that brings everything to your fingertips. Redesigned in v5.1 with a cleaner layout and improved readability. Search clipboard history, expand snippets, find files, kill processes, run system commands, search the web, and query AI — all from one unified interface.

Feature	How to Use
Clipboard History	Search and paste from your clipboard history
Snippet Expansion	Type `;keyword` or `!keyword` to expand saved snippets
File Search	Type `find` or `open` + filename
Image Search	Type `find` + what is in the picture (e.g., `find receipt from the hotel`); see Image Search
Keep Awake	Type `awake 2h`, `awake` or `awake off`; see Keep Awake
Process Kill	Type `kill` + app name to force quit
System Commands	Type `sleep`, `lock`, or `empty trash`
Web Search	Type keyword + space + query (e.g., `g best mac 2026`)
URL Bookmarks	Type keyword + Enter (e.g., `gm` → Gmail)
AI Query	Any unmatched text shows "Ask AI" — press Enter to chat

There's a ton more inside the app. The features listed above are just the defaults. You can fully customize the Spotlight launcher — add your own web search engines, create custom snippets, set up URL bookmarks, and more. Everything is configurable in Settings.

CapturesNEW IN 5.3

Captures lets you save text and AI responses for later review. Whenever you come across something useful — a generated response, a piece of text, or any output — add it to your Captures and revisit it anytime.

Feature	Description
Save Text	Save any text or AI response to your Captures collection
Review Later	Browse and revisit all your saved captures anytime
Quick Access	Access your captures directly from the app for fast reference

SnippetsNEW IN 5.3

Create reusable text snippets and expand them instantly from the Spotlight launcher. Perfect for emails, signatures, code templates, and frequently typed text.

Creating Snippets

Create snippets in Settings → Snippets tab.

Field	Example
Keyword	`;email`
Expansion	Thanks for reaching out. I'll get back to you shortly.

Placeholders

Placeholder	Result
`{date}`	Inserts current date
`{time}`	Inserts current time
`{clipboard}`	Inserts clipboard content

Example: ;sig → Best regards, Jithin - Sent on {date}

Create as many as you need. There's no limit to the number of snippets you can create. Build your own library of email templates, code snippets, signatures, addresses, and anything you type frequently.

Web SearchNEW IN 5.3

Search 18+ engines directly from the Spotlight launcher. Type keyword + space + query.

Search Engines

Keyword	Engine	Example
`g`	Google	`g best mac 2026`
`yt`	YouTube	`yt swift tutorials`
`r`	Reddit	`r macbook reviews`
`gh`	GitHub	`gh swiftui components`
`so`	Stack Overflow	`so swift async await`
`tw`	X / Twitter	`tw apple event`
`npm`	npm	`npm framer-motion`
`w`	Wikipedia	`w machine learning`
`amz`	Amazon	`amz usb c hub`
`hn`	Hacker News	`hn startup funding`

AI Engines

Keyword	Engine
`ps`	Perplexity
`gpt`	ChatGPT
`gem`	Gemini
`cl`	Claude

Social & Google

Keyword	Engine
`pin`	Pinterest
`li`	LinkedIn
`tf`	TikTok
`img`	Google Images
`drive`	Google Drive
`maps`	Google Maps

URL Bookmarks

Add keyword-only shortcuts in Settings → Web Searches. Leave %s out of the URL to create a bookmark instead of a search.

Keyword	Name	URL
`gm`	Gmail	https://mail.google.com
`cal`	Calendar	https://calendar.google.com

Tip: Type gm + Enter to open Gmail directly. No search term needed for bookmarks.

Utility ActionsNEW IN 5.3

Quick system actions available directly from the Spotlight launcher.

Command	Example
`kill <app>`	`kill Slack` — force quits Slack
`find <file>`	`find report.pdf` — searches and opens file
`open <file>`	`open notes.txt` — same as find
`sleep`	Puts Mac to sleep
`lock`	Locks the screen
`empty trash`	Empties the Trash
`awake 2h`	Keeps the Mac running with the lid closed for 2 hours (`awake` until you stop it, `awake off` to stop)
`image search`	Sets up, shows or removes Image Search

AI Fallback: Any text that doesn't match a keyword shows an "Ask AI" option at the bottom of the results. Press Enter to chat with AI in the agent sidebar.

Image SearchNEW IN 6.14

Find a picture by what is in it, not by its file name. Open the launcher, type find and describe it:find whiteboard with the roadmap, find error about the certificate. Text inside screenshots counts too. Images in Desktop, Downloads, Documents, Pictures and your screenshots folder are searched.

Setting it up

• Type image search in the launcher (or pick the offer under a find search) and start the download
• It is optional and one-time, about 450 MB, and needs a Mac with Apple silicon
• Your images are indexed in the background, newest first; new ones are added as you save them
• The same image search command shows what is indexed and removes it

Runs on your Mac: images are read and matched on device. Nothing is uploaded.

Keep Awake with the Lid Closed

Start Claude Code, Codex or any other long job, close the lid, and the Mac keeps working. Choose 30 minutes to 4 hours, or until you stop it.

• Menu bar › Keep Awake with Lid Closed, or type awake 2h in the launcher (awake runs until you stop it, awake off stops it)
• An eye and the time left sit in the menu bar; click it to change the time or stop
• It stops by itself when the time is up, when the battery reaches 15% (change it in Settings › Account) or when the Mac restarts
• The first time, macOS asks you to allow ahsk once in System Settings › Login Items

Voice Input Modes

Every voice feature in ahsk starts from the same key. Hold Fn to talk, tap it to go hands-free, or add a second key for questions, translation, and screen-aware answers:

Feature	Activation	Description
Push-to-Talk	`Hold Fn (Globe)`	Hold to record, release to transcribe and paste at cursor
Hands-Free	`Tap Fn (Globe)`	Keeps listening after you let go and shows your words as you speak; tap Fn again to stop and paste, Esc to cancel
AI Search	`Fn + Control`	Voice-activated web search with streaming responses
Translation	`Fn + Shift`	Speak in one language, paste in your second language
Alan	`Fn + Option`	Say what you want done: reply to what is on screen, calendar, reminders, messages
Follow-up (answer card open)	`Hold Fn` or `Hold Option`	Ask the next question in the same conversation; release to send
Insert answer	`Return`	Pastes the answer where your cursor is; `Cmd + C` copies it instead
Close answer	`Esc`	Dismisses the answer card

Push-to-Talk

Voice type anywhere on your Mac. Hold the Fn (Globe) key, speak naturally, and release. Your text appears at your cursor when you let go. Perfect for quick messages, notes, or filling out forms.

Hands-Free

Ideal for longer dictation when you don't want to hold a key. Tap Fn once and ahsk keeps listening after you let go. Speak as long as you need, then tap Fn again to stop and transcribe. While you talk, a card shows your words as you say them (turn it off in Settings › Voice › Live transcript). Press Esc to throw the take away without transcribing. If it hears nothing for thirty seconds it stops on its own. Great for writing emails, documents, or taking meeting notes.

Optional: Fn + Space

Removed in 6.2, back as an option in 6.9: hold your dictation key and press Space to go hands-free, if that is what your hands remember. Onboarding’s Shortcuts sheet lets you pick Space, Return, Tab or none. A tap of the key on its own does the same and needs no setup.

Dictation That Fits the App

ahsk looks at where your words are going and writes them the way that place expects. Nothing to switch on.

Where	What you get
Email (Mail, Outlook, Gmail and other webmail, or Mail mode)	Greeting on its own line, the body in paragraphs, then the sign-off and your name. The To, Cc and Subject fields stay one line.
Lists, anywhere	Say the items and they land as a tidy list; a long dictation is split into paragraphs where the topic changes.
Code editors and terminals	Spoken file names become `@file` references (“login view dot swift” → `@LoginView.swift`), function names are written as code, and a dictated command comes out exact (“git status” → `git status`). Made for coding agents like Claude Code and Cursor.

AI Search (Fn + Control)

Get instant answers to any question using your voice. AI Search combines voice recognition with web search to deliver concise, AI-powered answers in real-time. No need to open a browser or type out your query.

How to Use

• Press Fn, then Control while holding Fn to start recording
• A globe icon appears during recording to indicate AI Search mode
• Speak your question naturally and release to get web-sourced answers
• Follow-up questions: Hold Option key to ask follow-up questions and continue the conversation (up to 10 turns)
• Press ESC to close the search window

Pro Tip: AI Search is perfect for quick fact-checks, looking up definitions, getting current information, or researching topics while you work - all without leaving your current app.

Alan (Fn + Option)

Say what you want done and Alan does it. He reads what is on your screen and writes at your cursor: “reply to this” over a mail or chat thread puts a reply in the reply box, ready for you to send. He also runs your calendar and reminders, finds people in Contacts and sends iMessages: “move my 3 o’clock to five”, “remind me to call the dentist tomorrow morning”, “text Anna that I’m running late”. He acts first and offers Undo after; he asks first only before deleting something or sending a message.

How to Use

• Hold Fn + Option (or hover the pill and click his face), say what you want done, release
• A quick action ends in one line by the pill; anything longer opens his card, where Undo reverses the last turn and you can speak or type a follow-up
• Memory: tell him things like “my meetings are 30 minutes” and he applies them every time. See and edit them in Settings › Alan › What he remembers
• When he must ask (before a delete or a message, or when two contacts share a name), Return approves and Esc declines
• Needs Calendars, Reminders, Contacts and Automation (Messages) permissions the first time each is used

Good for: replying to a message thread you are looking at, filling in a form from a document on screen, or explaining an error without leaving your editor.

Keyboard Shortcuts

Access Ahsk's features instantly with these keyboard shortcuts. All shortcuts work system-wide, so you can use them in any application.

Default Shortcut	Action	Description
`Hold Fn`	Voice Typing	Hold to record, release to transcribe and paste
`Tap Fn`	Hands-Free Dictation	Keeps listening after you let go — tap Fn again to finish
`Esc`	Cancel Hands-Free	Throws away a hands-free take without transcribing it
`Fn + Control`	AI Search	Ask a question by voice, get a web-sourced answer
`Fn + Shift`	Voice Translation	Speak, paste in your second language
`Fn + Option`	Alan	Say what you want done: reply to what is on screen, calendar, reminders, messages (replaced Respond in 6.11)
`⌘ Space`	Spotlight Launcher	Search, snippets, clipboard history, and utilities
`⌥⇧S`	Screenshot + AI	Capture screen area and analyze with AI
`⌥⇧D`	Download Video	Download from YouTube, TikTok, Instagram, X, and Spotify track links
`⌥⇧T`	Translate	Translate selected text
`⌥⇧R`	Meeting Notes	Record a meeting (mic + system audio) into notes with a mind map
`⌥ (hold)`	Voice Follow-up	Hold Option in chat windows for voice follow-up

Customization: All shortcuts can be customized in Settings → Keyboard Shortcuts to match your existing workflow and preferences.

ActionsNEW

Actions is a customizable bubble menu that appears when you select text in any application. It gives you quick access to AI-powered actions right where you work — and it's built to be extended with plugins over time.

Action	Description
Ask	Ask AI a question about the selected text
Rewrite	Rewrite the selected text with AI
Copy	Copy text to clipboard
Translate	Translate to your preferred language
Dictionary	Add selected word to your custom dictionary for improved voice detection accuracy

Plugin Support Coming Soon: Actions is designed with a plugin-ready architecture. More actions and custom workflows will be available as plugins in upcoming releases.

Force Actions Menu

Some applications may not trigger the Actions menu automatically due to how they handle text selection. For these apps, you can configure a "Force Bubble" key:

• Set a Force Bubble key in Settings (None by default)
• Options: None, Control (⌃), Option (⌥), Command (⌘), Shift (⇧)
• After selecting text, press your chosen key to force the Actions menu to appear

Voice Input Settings

Customize how voice input works to match your preferences. Access these settings from the Ahsk menu bar icon → Settings.

Setting	Options	Description
Voice Input Key	Fn (Globe), Option+Shift+V, Command+Shift+V	Choose which key activates voice recording
Voice Mode	Informal, Formal, Mail, or your own	Shapes how dictation is written — shorthand and symbols, full words, or a formatted email
Microphone	Built-in, or any connected input	Pinned for ahsk only — your Mac's own input device is never changed
Live transcript	On, Off	Shows your words as you speak during hands-free dictation
Force Actions Menu	None, ⌃, ⌥, ⌘, ⇧	Key to manually trigger the Actions menu after text selection

Voice modes apply to dictation only. Questions you ask through AI Search, Respond, or Ask and Rewrite are sent exactly as you said them, so a mode like Mail can never reshape a question before ahsk reads it.

Screenshot Analysis (⌥⇧S)

Capture any part of your screen and get instant AI-powered analysis. Perfect for understanding complex visuals, debugging user interfaces, extracting text from images, or getting explanations of diagrams and charts.

How it works: Start the shortcut, drag to capture, and Ahsk opens an AI response view with context from the screenshot.

You can continue with follow-up questions to inspect details in the same captured image.

How to Use

1. Press Option + Shift + S from anywhere
2. Click and drag to select the screen area you want to analyze
3. AI instantly analyzes the captured image and provides insights
4. Ask follow-up questions about the screenshot to dive deeper

• Analyze images, diagrams, flowcharts, or any visual content
• Get detailed explanations and insights about what you're seeing
• Extract and understand text from images or screenshots
• Debug user interfaces by having AI analyze error messages or UI elements

Video Download (⌥⇧D)

Download videos from popular social media platforms directly to your Mac. Save videos for offline viewing, reference, or archiving without needing third-party websites or browser extensions.

How it works: Ahsk reads the copied URL, validates the source, then downloads directly to your chosen folder.

The flow is optimized for quick save-and-continue without leaving your current task.

Supported Platforms

• YouTube
• TikTok
• Instagram
• X (Twitter)
• Spotify track links (the song is saved as audio)

How to Use

1. Copy the video URL to your clipboard from any browser
2. Press Option + Shift + D
3. The URL auto-fills from your clipboard
4. Choose your preferred quality and click download

Meeting Notes (⌥⇧R)

Record both sides of any meeting — your microphone and the Mac’s own audio (Zoom, Meet, Teams, a browser tab) — and get polished notes when you stop. The system audio is captured digitally, so headphones work and room noise never enters that track. Dictation keeps working while a meeting records.

1. Press Option + Shift + R (or choose Record Meeting from the menu bar) when the meeting starts
2. A red aura on every screen and a REC pill in the top-right corner show that recording is on — both can be switched off under Settings › Notes
3. Press Option + Shift + R again (or click the REC pill) to stop
4. ahsk transcribes the recording and writes a summary, key points, decisions, checkbox action items and a mind map — saved as Markdown in ~/Documents/ahsk meetings and shown under Settings › Notes, where each meeting is a tile that opens in its own window

Every plan includes 10 hours of meeting recording per month. Requires macOS 14.2 or later; the first recording asks for macOS’s system-audio permission. Also on Windows (1.14) with Ctrl + Win + R.

Translation (⌥⇧T)

Translate any text on your Mac to your preferred language instantly. Whether you're reading foreign articles, communicating with international colleagues, or learning a new language, Ahsk makes translation seamless.

How it works: Select text, trigger translation, and Ahsk returns localized output immediately in your preferred language.

Set a default target language in Settings to skip manual language selection every time.

How to Use

1. Select the text you want to translate in any app
2. Press Option + Shift + T or click the Translate button in the Actions menu
3. Choose your target language from the list
4. View the translation and easily copy it to your clipboard

Tip: Set your default translation language in Settings to skip the language selection step and get instant translations.

Voice Chat Windows

When you use Ask or Rewrite features, a chat window opens where you can continue the conversation. Instead of typing follow-up questions, you can use your voice for a more natural interaction.

• Voice Follow-up: Hold the Option key to record a voice follow-up question
• Visual Feedback: A waveform animation shows your recording status so you know when you're being heard
• Conversation Memory: The AI maintains context throughout the conversation for up to 10 turns, so you can have natural back-and-forth discussions
• Close Window: Press ESC at any time to close the chat window

Window Controls

Simple keyboard controls for managing Ahsk windows:

Key	Action
`ESC`	Close any active Ahsk window (Assistant, Chat, Search, etc.)
`Option (hold)`	Record a voice follow-up in chat windows

System Requirements

Ahsk is designed to run smoothly on modern Macs. Here's what you need:

• macOS 11.0 (Big Sur) or later - Ahsk supports all recent macOS versions
• Microphone access - Required for voice input, transcription, and AI search features
• Accessibility permissions - Enables text selection detection and automatic pasting of transcriptions
• Screen recording permission - Required for the screenshot analysis feature

Note: You'll be prompted to grant these permissions when you first launch Ahsk. You can also manage permissions later in System Settings → Privacy & Security.

Privacy

Your privacy is our priority. Ahsk is designed with privacy in mind:

• Local storage: Your transcription history, dictionary and settings stay on your Mac. Audio is sent for transcription and is never stored on our servers
• Minimal Account Data: We only store your email address for authentication purposes
• No AI Training: Your queries and transcriptions are never used to train AI models

Troubleshooting

Having issues? Here are solutions to common problems:

Actions menu not appearing when I select text

First, ensure Accessibility permissions are granted: Go to System Settings → Privacy & Security → Accessibility and make sure Ahsk is enabled.

If the menu still doesn't appear in certain apps, try configuring a Force Actions Menu key in Settings. After selecting text, press your chosen key to manually trigger the menu.

Voice input not working

Make sure Microphone permissions are granted: Go to System Settings → Privacy & Security → Microphone and enable Ahsk. You may need to restart the app after granting permission.

Fn + Space stopped working

It was removed in 6.2 and is optional again since 6.9. A quick tap of Fn on its own always works — tap once to start, tap again to stop and paste. To bring the chord back, run the onboarding Shortcuts sheet or check Settings › Shortcuts.

Pressing Fn opens the emoji picker

macOS claims the Fn (Globe) key by default. Open System Settings → Keyboard and set Press globe key to → Do Nothing. ahsk's setup walks you through this, and you can re-run it any time from the menu bar icon.

Screenshot analysis not working

Screen Recording permission is required: Go to System Settings → Privacy & Security → Screen Recording and enable Ahsk. A restart may be required after granting this permission.

Need more help?

Contact our support team at support@ahsk.app - we're happy to help!