DEV Community: Clavio App

Building per-app dictation on macOS: focus, profiles, and optional send

Clavio App — Sat, 12 Sep 2026 09:31:41 +0000

Dictating a coding prompt and dictating an email can involve the same microphone and speech recognizer. They should not necessarily involve the same writing style—or the same action after the text appears.

We build Clavio, hands-free dictation for Mac, at Just Tools LTD. This is a developer's explanation of one part of the app: how we separate application identity, writing preferences, listening mode, and delivery. The implementation details below are based on our Mac code; the short pseudocode is illustrative, not a drop-in library.

The video above is our existing walkthrough, including wake-word setup and a separate profile for Claude.

1. “The active app” is more than one value

On macOS, NSWorkspace exposes the frontmost application and an application-activation notification. That gives a useful starting point: identify an app by its bundle identifier, not its display name.

But reading the frontmost app only when transcription finishes is too late. Someone can start dictating in an editor, click the dictation panel, and finish speaking while that panel has focus. The panel should not become the writing-style target merely because it is visible.

We distinguish three values:

Value	What it represents	Why keep it?
Live frontmost app	The latest activated app, including Clavio	Current UI and focus decisions
Last external app	The latest activated app other than Clavio	Preserve useful context when our own UI appears
Session target	The target selected when a recording session starts	Keep processing associated with that session

Clavio seeds the focus cache on launch and updates it from activation notifications. Published UI state is updated on the main queue. This also avoids repeatedly requesting application information in UI hot paths.

There is an important edge case: starting dictation inside Clavio must not blindly reactivate an older external app. A remembered target is context, not permission to send text anywhere.

Apple documents the underlying application-activation notification.

2. Model the profile as independent choices

A profile is not just a long prompt. Clavio stores user preferences keyed by the application's bundle ID, including:

Polish intensity and tone overrides.
Listening mode and pause timing overrides.
Optional custom wake phrases.
The action, if any, after text insertion.

These choices answer different questions. “Professional tone” describes the output. “Wake word” describes when capture begins. “Press Return” describes a later interaction with the destination app. Combining them into one setting makes surprising behavior harder to explain.

The app profile exposes listening choices separately from writing preferences.

For example, someone might choose a keyboard-triggered mode and a professional tone for email, then wake-word activation and a direct tone for a coding assistant. Automatic sending remains a separate decision in each app.

This is application-level identity. A browser bundle ID alone does not identify Gmail versus another website in a neighboring tab. Website-specific routing is a separate problem; it should not be implied by an app-level profile.

3. Resolve tone and intensity separately

An unset override should mean “inherit,” not “erase the default.” Clavio's writing-settings resolver handles intensity and tone independently.

For intensity, it checks the explicit app preference, then an app/catalog-derived default, then the user's global preference, and finally a built-in fallback. Tone has its own path: explicit app tone, catalog tone, user tone, or no specific tone.

An illustrative version looks like this:

intensity = firstAvailable(
    app.intensityOverride,
    catalogEntry.defaultIntensity,
    user.defaultIntensity,
    builtInIntensity
)

tone = firstAvailable(
    app.toneOverride,
    catalogEntry.defaultTone,
    user.preferredTone,
    noSpecificTone
)

Why two paths? A user may want a particular tone while leaving the amount of rewriting inherited. Treating the whole profile as either “custom” or “default” would lose that distinction.

When both values have explicit app overrides, the resolver skips the catalog lookup. When a default cannot be obtained, it falls back instead of making dictation depend on a catalog response. That fallback does not make speech transcription offline; it only keeps preference resolution from being an unnecessary blocker.

Tone and editing intensity describe different dimensions of the result.

4. Listening mode is a runtime policy

The listening-mode resolver checks an explicit per-app override and otherwise inherits the global mode. The recording coordinator consumes that result when application activation changes.

The distinction between Wake Word and Always On must remain meaningful. If a wake detector cannot operate, silently treating ordinary speech as an Always On session would change what the user agreed to. The resolver preserves the selected mode; runtime components can suspend capture without relabeling it as another mode.

Custom app wake phrases also need a destination check. In Clavio, the detector can listen for a combined set of custom phrases, but the trigger is checked against the current app. The shared brand wake phrases remain separate from those app-specific additions.

5. Inserting text and sending it are separate operations

The overall flow is easier to reason about when its stages stay explicit:

Application activation → update focus context
Recording starts       → choose session target
Recording finishes     → transcribe and resolve writing settings
Text is ready          → check delivery destination and insert
Post-paste action      → perform only the configured action, if any

Posting a paste shortcut is not the same as proving that an app accepted the text. Electron apps, native fields, focus changes, and timing can all affect delivery. Clavio keeps delivery diagnostics separate from the act of posting the event, and its insertion paths include checks for security-sensitive destinations such as password fields.

The same distinction matters for Return: depending on the destination, it can send a message or simply insert a new line. Automatic sending is useful for some prompting workflows, but users should be able to leave it disabled wherever they want to review text first.

Cases worth testing in any per-app implementation

Start in an editor, then click the dictation panel before processing completes.
Start in the dictation app itself after previously using another app.
Override only tone, leaving intensity inherited.
Switch between an app with an explicit listening mode and one using the global mode.
Change focus before insertion, including to a password prompt.
Keep post-paste actions disabled and verify that text remains available for review.

These are useful engineering tests even if the recognizer itself is already accurate. A perfect transcript in the wrong app, with an unexpected Return key, is still a poor result.

If you want to try the implementation rather than build it, Clavio is available for Apple Silicon Macs running macOS 14.2 or later. Dictation transcription and text polishing use online processing; wake-word and voice-profile functions run on the Mac. The current plans explain the Free allowance and Pro features, including the advanced controls shown in the walkthrough.

For this kind of Mac utility, the design work extends beyond converting speech into text: the app must keep track of which settings apply, which destination belongs to a session, and which actions the user actually selected.

Clavio for Mac: six spoken briefs for coding assistants

Clavio App — Wed, 09 Sep 2026 10:51:23 +0000

“Make the form work better” is easy to say. It is much harder to implement: better validation, a different layout and clearer loading feedback are three different tasks.

A useful spoken brief gives the assistant something it can inspect and something you can verify. Start with four landmarks: goal, context, constraints and done when.

I'm Stas, director of Just Tools LTD, the company behind Clavio, an AI dictation app for Mac. Below are six structures you can use with Clavio, another dictation tool, or a keyboard. The examples are illustrative tasks, not customer results.

See voice input in action

This short Claude demo shows dictation and optional automatic sending. For the coding tasks below, keep the brief visible, review it and send it when you are ready.

1. Report a reproducible bug

Structure: When I… I expect… Instead… Reproduce it by… Keep… Fixed means…

When I submit an empty comment, I expect a validation message. Instead, the submit button stays in its loading state. Open a post, leave the comment empty and press Send. Keep the existing API response format. Fixed means the message appears and the button can be used again.

Give the assistant a trigger and an observable failure. Paste the exact error message afterwards if you have one. Saying “there is a network error” loses information that a status code or stack trace might contain.

2. Request a small feature

Structure: The user needs… Put it in… It should… Preserve… Ready means…

The user needs to copy a support reference from the error panel. Put a copy button beside the reference. Show a short confirmation after copying. Preserve normal text selection. Ready means the button works with a keyboard, the copied value matches the reference, and a failed copy does not show success.

Keep the request centred on one user action. The last condition matters: a visual confirmation should reflect what happened, rather than appear whenever a button was pressed.

3. Ask for a focused review

Structure: Review… Focus on… For each finding, explain… For now…

Review the changes to comment submission. Focus on duplicate requests and failed retries. For each finding, explain the trigger, the user-visible result and the relevant code. For now, report findings before changing files.

That final sentence defines the output you want. If the task is diagnosis, say so. Otherwise a review can quietly turn into a larger implementation task.

4. Describe a bounded refactor

Structure: The repeated logic is… Simplify… Preserve… Avoid… Check…

The loading-state logic is repeated in three settings panels. Extract shared state handling where it improves readability. Preserve each panel's error messages and public interface. Avoid a new dependency. Check saving, retrying and closing a panel while a request is in progress.

A refactor needs a behaviour boundary. Name what must stay true, and let the assistant inspect the code before deciding what can reasonably be shared.

5. Request a test for a failure mode

Structure: Protect against… Start with… Trigger… Assert… Also cover…

Protect against losing a draft after a failed save. Start with an edited draft, make the save request fail, and assert that the text remains available for another attempt. Also cover a successful retry. Use the project's existing test tools.

This describes the failure the test should catch. It gives more direction than “add tests” without prescribing the test's internal implementation.

6. Prepare a PR description

Structure: The problem was… The change now… Scope is… Checks completed were… Still uncertain is…

The problem was that the save button stayed disabled after a network failure. The change restores the button and keeps the draft. The scope is the editor's retry state. The completed check was a manual failed-save and successful-retry sequence. Automated checks have not been run yet.

Only include validation that happened. If you cannot remember whether a check passed, verify it before putting it in the description.

The review pass matters as much as the template

Read the resulting brief once before sending it. Check four details:

Names: Are file, function and service names correct?
Numbers: Did a timeout, version or limit survive accurately?
Negations: Did “do not change the API” keep the “not”?
Stopping point: Is it clear whether the assistant should investigate, edit or report?

Type or paste exact identifiers and symbols when that is easier. Speaking the explanation and typing a function name is a useful combination.

Here is a simple check for your next task: could someone read the final instruction and tell whether the result satisfies it? If “done” still means “make it nicer,” add one observable condition.

Using the briefs with Clavio on Mac

For a first coding brief, focus the assistant's message field and start with Hold key. Use Clean if you want punctuation and filler cleanup while keeping the wording close. Leave After paste set to None so the result stays visible for review.

Clavio's general Polish settings. This screenshot shows the available controls; Tidy is selected here. For the first coding brief above, choose Clean.

An app profile lets you keep a technical writing style for Claude and a more conversational tone for email. Listening modes can differ too: for example, a wake phrase in Claude and Hold key in your email app.

Listening and pause controls inside an app profile. This example inherits the global listening mode; the same panel offers app-specific choices.

Clavio also offers wake-word and Always On modes, with app-specific settings. Its per-app style, tone and pause controls are listed under Pro. The free allowance of 3,000 polished words per month does not make every advanced control free. Clavio requires Apple Silicon and macOS 14.2 or later; ordinary transcription and polishing use online processing.

You can check the current features and plans on the Clavio website.

Which detail do you most often have to add to a coding task after the first attempt: context, constraints or the definition of done?

AI disclosure: This article was drafted with AI using my product notes. The task examples are illustrative.