Skip to content
Athena mark Athena mark Athena

Installation

From source

Section titled “From source”
git clone https://github.com/luckeyfaraday/athena-whisper.git
cd athena-whisper
python3 -m venv .venv
. .venv/bin/activate           # Windows: .venv\Scripts\activate
pip install -e ".[dev,gui]"

Linux — for X11 desktop insertion:

sudo apt-get install xdotool xclip

If PyQt6 reports an XCB platform plugin error, install the common X11 Qt runtime libraries:

sudo apt-get install libxcb-cursor0 libxcb-xinerama0 libxkbcommon-x11-0

Windows — no additional tools required. The windows-keystrokes and windows-clipboard-paste backends use ctypes to call Win32 SendInput and keybd_event directly.

Run the widget

Section titled “Run the widget”
.venv/bin/athena-dictate widget      # Linux
.venv\Scripts\athena-dictate widget  # Windows

The repository includes an athena-dictate.toml configured for automatic platform-specific insertion. On Linux/X11, auto uses keystrokes instead of clipboard paste, so terminal apps such as Codex, Claude Code, opencode, and shell-based TUIs do not receive Ctrl+V image-paste shortcuts. On Windows, auto uses Win32 keystrokes.

CLI usage

Section titled “CLI usage”

Check the current desktop/session environment:

athena-dictate doctor

Transcribe an existing audio file:

athena-dictate transcribe-file path/to/audio.wav
athena-dictate transcribe-file path/to/audio.wav --language es     # explicit language
athena-dictate transcribe-file path/to/audio.wav --language auto   # auto-detect
athena-dictate transcribe-file path/to/audio.wav --task translate  # translate to English

Record one short dictation and insert the result:

athena-dictate record-once --seconds 5 --paste
athena-dictate record-once --multilingual   # language changes within one recording
athena-dictate record-once --seconds 5 --no-paste   # record without inserting

Test keystroke insertion without recording or transcribing:

athena-dictate type-text "hello from athena"

Development checks

Section titled “Development checks”
.venv/bin/pytest
.venv/bin/python -m compileall src tests

Packaging status

Section titled “Packaging status”

The current repository does not include PyInstaller packaging scripts or released desktop installers. Run Athena Whisper from the source checkout for now.