GitHub - softcane/aloud: Aloud reads Claude Code and Codex replies out loud on your Mac. · GitHub

/" data-turbo-transient="true" />

Skip to content

Search or jump to...

Search code, repositories, users, issues, pull requests...

-->

Search

Clear

Search syntax tips

Provide feedback

--><br>We read every piece of feedback, and take your input very seriously.

Include my email address so I can be contacted

Cancel

Submit feedback

Saved searches

Use saved searches to filter your results more quickly

-->

Name

Query

To see all available qualifiers, see our documentation.

Cancel

Create saved search

Sign in

/;ref_cta:Sign up;ref_loc:header logged out"}"<br>Sign up

Appearance settings

Resetting focus

You signed in with another tab or window. Reload to refresh your session.<br>You signed out in another tab or window. Reload to refresh your session.<br>You switched accounts on another tab or window. Reload to refresh your session.

Dismiss alert

{{ message }}

softcane

aloud

Public

Notifications<br>You must be signed in to change notification settings

Fork

Star

main

BranchesTags

Go to file

CodeOpen more actions menu

Folders and files<br>NameNameLast commit message<br>Last commit date<br>Latest commit

History<br>8 Commits<br>8 Commits

src/aloud

src/aloud

tests

tests

.gitignore

.gitignore

LICENSE

LICENSE

README.md

README.md

pyproject.toml

pyproject.toml

View all files

Repository files navigation

Aloud

Aloud reads Claude Code and Codex replies aloud on macOS.

Turn it on with aloud on in any Claude Code or Codex session. Aloud speaks a short summary after each assistant reply. Use Cmd + Ctrl + H for the full reply, or Cmd + Ctrl + . to stop playback.

Aloud uses Kokoro for local text-to-speech. The Python package installs Kokoro. Kokoro downloads its model files the first time speech generation starts, then reuses the local cache. Aloud does not send agent replies to an external TTS service.

Requirements

macOS.

Python 3.11 or 3.12.

Homebrew.

Claude Code, Codex CLI, or both.

Install

brew install python@3.11 pipx<br>pipx ensurepath<br>pipx install --python python3.11 git+https://github.com/softcane/aloud.git<br>aloud install<br>aloud doctor

Restart Claude Code or Codex after install. In Codex, open /hooks and trust the Aloud hooks. In macOS System Settings, give Hammerspoon Accessibility permission for the hotkeys.

The installer:

creates the Aloud config, cache, log, and session directories;

starts a launchd daemon for speech generation;

installs Hammerspoon hotkeys;

installs Claude Code commands and Codex prompt shortcuts;

merges Aloud hooks into Claude Code and Codex settings;

writes timestamped backups before editing hook settings.

Use

Inside Claude Code or Codex:

aloud on

Aloud arms only that session. Later replies in that session speak a short summary. The agent does not receive aloud on as a prompt.

Claude Code also supports /aloud-on and /aloud-off. In Codex, use aloud on and aloud off; Codex prompt shortcuts are available as /prompts:aloud-on and /prompts:aloud-off after Codex reloads its prompt list.

Controls:

aloud off: stop speaking this session.

Cmd + Ctrl + H: speak the full reply from the last session Aloud spoke.

Cmd + Ctrl + .: stop playback.

aloud full: speak the full reply from a terminal.

aloud stop: stop playback from a terminal.

Multiple sessions are tracked separately. If session A speaks, the full-reply hotkey reads session A even if session B finishes later.

Commands

aloud doctor<br>aloud self-test --no-audio<br>aloud voices<br>aloud voices --play<br>aloud uninstall

doctor checks the installed files and hooks. self-test --no-audio checks the registry without using Kokoro or audio hardware. voices --play previews Kokoro voices on the current macOS output device.

Files

Aloud writes mutable files under ~/Library:

config: ~/Library/Application Support/Aloud/config.json

socket and session registry: ~/Library/Application Support/Aloud/

WAV cache: ~/Library/Caches/Aloud/

daemon log: ~/Library/Logs/Aloud/daemon.log

launchd plist: ~/Library/LaunchAgents/io.aloud.daemon.plist

Edit config.json to change voice, speed, or retention settings.

launchctl unload ~/Library/LaunchAgents/io.aloud.daemon.plist<br>launchctl load -w ~/Library/LaunchAgents/io.aloud.daemon.plist

Uninstall

aloud uninstall<br>pipx uninstall aloud

Uninstall removes the launchd plist, Hammerspoon hotkeys, Claude Code commands, Codex prompt shortcuts, and hook entries. It leaves state, cache, and logs in place for inspection.

To remove those files too:

rm -rf ~/Library/Application\ Support/Aloud ~/Library/Caches/Aloud ~/Library/Logs/Aloud

Development

git clone https://github.com/softcane/aloud.git<br>cd aloud<br>python3.11 -m venv .venv<br>.venv/bin/python -m pip install -e '.[dev]'<br>.venv/bin/ruff check .<br>.venv/bin/ruff format --check .<br>.venv/bin/pytest<br>.venv/bin/aloud doctor<br>.venv/bin/aloud self-test --no-audio

Before release, also run live smoke tests in Claude Code and Codex CLI, then run one real audio smoke on...