Dictare / Docs / Getting Started

Getting Started

Dictare is a voice layer for AI coding agents. It runs 100% locally, captures your voice, transcribes it, and delivers the text to agents like Claude Code, Codex, Gemini CLI, or Aider via the OpenVIP protocol.

No cloud. No subscriptions. MIT licensed.

Here's the simplest way to get started. There are many options, but this is what we recommend:

1. Install

macOS:

brew tap dragfly/tap
brew install dictare
dictare setup

Linux or direct install:

curl -fsSL https://raw.githubusercontent.com/dragfly/dictare/main/install.sh | bash

This installs Dictare, creates a dedicated runtime under ~/.local/share/dictare, installs the dictare command, and registers the background service.

If you already have Dictare installed with the runtime-store installer, run dictare upgrade to switch to the latest stable release.

Release-candidate testers can install 0.6.0rc1 explicitly:

dictare upgrade --version 0.6.0rc1

2. Grant permissions

macOS — grant all three when prompted:

  1. Microphone — prompted automatically on first launch
  2. Input Monitoring — System Settings → Privacy & Security → Input Monitoring → enable Dictare
  3. Accessibility — System Settings → Privacy & Security → Accessibility → enable Dictare (needed for keyboard mode)

After granting all three: dictare repair

Linux:

sudo usermod -aG input $USER   # required for hotkey — log out/in after

For keyboard mode on Wayland: sudo apt install ydotool

3. Check the tray icon

After installation, a tray icon appears in your menu bar (macOS) or system tray (Linux):

  • Purple — Dictare is running and ready
  • Gray — Dictare is off

Right-click the tray icon to toggle listening, switch agents, open settings, and more. See the Tray App page for full details.

On Linux, you may need to install gir1.2-appindicator3-0.1 and start the tray manually: dictare tray start.

4. Launch your agent

dictare agent freddie

This opens Claude Code (the default profile) in a transparent passthrough session. The agent owns the terminal; Dictare state is shown in the tray and, on demand, through a system notification.

5. Start talking

  • Single tap the hotkey (Right Command on macOS, Scroll Lock on Linux) to toggle listening
  • The tray icon shows whether Dictare is listening or off
  • Speak — your transcription appears directly in the agent
  • Double tap the hotkey to submit (sends Enter)

6. Switch agents

Want to use a different coding agent? Just say "agent ozzy" or specify a profile:

dictare agent ozzy --profile codex      # OpenAI Codex
dictare agent gilmour --profile gemini  # Google Gemini CLI
dictare agent bowie --profile aider     # Aider

Or switch mid-session with your voice: say "agent ozzy" and Dictare routes your voice to that connected session.

Verify It Works

Check the service is running:

dictare status

You should see the engine status, connected agents, and STT model info.

What's Next

  • Installation for detailed platform setup and troubleshooting
  • Basic Usage for voice commands, submit, mute, and agent switching
  • Configuration to customize audio, STT, TTS, and hotkey settings
  • Agents for agent profiles and multi-agent setup