Amical

Amical is an open-source, local-first AI dictation app that lets you type hands-free using your voice, with no audio ever sent to the cloud. It runs Whisper (via whisper.cpp) for speech-to-text and optional local LLMs (via Ollama or OpenAI-compatible APIs) for intelligent formatting — all on your own hardware.

What makes Amical stand out is its context-aware pipeline: it reads the active application’s bundle identifier via OS accessibility APIs and adjusts its LLM prompt accordingly — applying email conventions in Apple Mail or Outlook, conversational tone in Slack or Discord, and structured Markdown in note-taking apps. This isn’t a generic transcription tool — it’s a dictation layer that adapts to whatever you’re doing.

The app ships as an Electron desktop client for macOS and Windows, with an Android app already available and an iOS beta in progress. A floating widget with configurable global hotkeys lets you start and stop recording from anywhere without switching windows. A voice-based notes mode with Lexical rich-text editing rounds out the feature set.

What You Get

• Context-Aware Dictation — Detects the active application by bundle ID on macOS (or exe path on Windows) and applies app-type-specific LLM formatting rules, so emails come out structured and chats stay conversational without manual adjustment.
• Local Whisper Transcription — Runs whisper.cpp natively as a Node.js addon with a VAD (voice activity detection) pre-filter powered by ONNX runtime, reducing hallucinations and improving accuracy on silent segments.
• Floating Dictation Widget — A persistent overlay with configurable global hotkeys (push-to-talk or hands-free toggle) lets you start and stop recording from any app without leaving your workflow.
• Multi-Provider LLM Formatting — Connects to Ollama for fully local LLM formatting, OpenRouter for cloud models, or any OpenAI-compatible API endpoint, switchable per-session from settings.
• Custom Vocabulary & Snippets — Define domain-specific terms (medical jargon, product names, technical acronyms) that are injected into the Whisper prompt to boost recognition accuracy for your field.
• Voice Notes with Rich Text — A dedicated Lexical-powered notes editor captures voice memos and formats them as structured Markdown, with summaries and task extraction planned.
• Multi-Language Support — Whisper handles 100+ languages natively; language selection is persisted per user and passed as context to the transcription pipeline.
• MCP Integration (Planned) — Voice commands that invoke Model Context Protocol tools, enabling hands-free control of connected applications.

Common Use Cases

• Drafting emails hands-free — A sales rep dictates follow-up emails in Apple Mail; Amical detects the Mail bundle ID and applies email formatting rules — adding salutations, separating paragraphs, maintaining professional tone — automatically.
• Writing code comments and docs — A developer dictates inline documentation or Jira ticket descriptions directly into VS Code; the IDE is classified as a default surface and Whisper’s custom vocabulary list ensures technical terms like ‘Kubernetes’ and ‘PostgreSQL’ are spelled correctly.
• Capturing meeting notes offline — A consultant records a client meeting on a plane with no internet; Amical transcribes locally via whisper.cpp and organizes the output as structured Markdown notes with action items.
• Faster Slack messaging — A remote team member dictates messages in Slack; Amical detects the Slack bundle ID and keeps the output conversational, short, and emoji-friendly without over-punctuating.

Under The Hood

Architecture Amical is a Turborepo monorepo with two user-facing apps — an Electron desktop client and a Next.js documentation/marketing site — backed by shared packages for types, UI primitives, native helpers, and the Whisper C++ wrapper. The desktop app follows a clean layered design: the Electron main process hosts a ServiceManager that owns long-lived services (transcription, VAD, settings, model management, auth), a RecordingStateMachine implements event-driven FSM logic for push-to-talk and hands-free modes, and a tRPC bridge (via electron-trpc-experimental) exposes typed procedures to the React renderer. The transcription pipeline is abstracted behind provider interfaces, allowing local Whisper and Amical Cloud backends to be swapped without touching call sites. LibSQL with Drizzle ORM provides embedded SQLite persistence with versioned migration support.

Tech Stack TypeScript is used across all packages and apps. Electron 38 hosts a Vite-built React 19 frontend using TanStack Router for client-side navigation and tRPC for typed IPC. The transcription pipeline embeds whisper.cpp as a native Node.js addon (@amical/whisper-wrapper) compiled per-platform, with a forked worker process isolating the heavy inference from the main thread. VAD runs via onnxruntime-node using a Silero VAD ONNX model. LLM formatting supports Ollama, OpenRouter, and generic OpenAI-compatible APIs through the Vercel AI SDK. The notes editor is built on Lexical with Yjs for real-time CRDT state, persisted via a custom y-libsql sync provider. UI components come from Radix UI and shadcn with Tailwind CSS v4.

Code Quality The test suite uses Vitest with real SQLite databases rather than mocks — each test case gets an isolated database in a temp directory with migrations auto-applied and a rich fixture system (empty, withTranscriptions, withVocabulary, withModels, withNotes, withAuth, full). Electron APIs and native modules are mocked at the module level. The recording pipeline is covered with unit tests for VAD audio filtering, GPU policy selection, formatter prompt logic, and gRPC client behavior. Error handling uses typed AppError / ErrorCodes enums throughout. The recording state machine eliminates entire classes of concurrency bugs by encoding valid state transitions explicitly.

What Makes It Unique Amical’s context-aware formatting pipeline is the most differentiated feature: it queries macOS accessibility APIs (or Windows UIA) to read the active application’s bundle identifier, maps it to a semantic app type (email / chat / notes / default), and builds an LLM prompt with type-specific rules and few-shot examples. The same dictated sentence becomes a properly formatted business email in Mail, a short casual message in Slack, or a Markdown task list in Notion — without any user intervention. Pairing this with a fully local inference stack (whisper.cpp + Ollama) means the entire pipeline runs offline with no subscription, making it one of the few dictation tools that is simultaneously context-intelligent and fully private.

Self-Hosting

Amical is released under the MIT License, which is a permissive open-source license. You can use it commercially, modify the source code, distribute it, and incorporate it into proprietary products without any obligation to open-source your changes. There are no copyleft implications — the license only requires that the copyright notice and license text are included in any distribution. The project is primarily a desktop client with no server-side components required for core dictation functionality.

Running Amical yourself means managing the Electron desktop app installation across your users’ machines, keeping up with GitHub releases for updates (the app has a built-in auto-updater via GitHub releases), and maintaining local model files for Whisper. The Whisper models range from ~150 MB (tiny) to ~3 GB (large-v3) and are downloaded in-app; you’ll need sufficient disk space and a reasonably modern CPU or GPU for real-time transcription. If you use Ollama for LLM formatting, you’re also responsible for running and updating the Ollama server. There is no infrastructure to operate beyond the client itself — no database server, no message broker, no container orchestration.

Amical does offer a cloud tier (Amical Cloud) for transcription, which provides a managed Whisper service and presumably faster inference on capable hardware without requiring local model downloads. Users who opt into Amical Cloud gain access to the managed transcription pipeline and any future cloud-based features, while self-hosters stick entirely to local models. Community support is available via Discord; there are no documented SLAs, enterprise support tiers, or high-availability guarantees for the self-hosted path. The project moves quickly — 95 releases since mid-2025 — so staying current requires tracking the GitHub releases page.