Low-latency Rust terminal overlay for Codex and Claude Code with local Whisper STT, PTY passthrough, wake words, macros, and a customizable HUD.

Whisper runs locally by default - no cloud API keys required. Release history: CHANGELOG.

If you are new, use this path:

1. Quick Start
2. Install Guide
3. Usage Guide
4. Troubleshooting

Quick Nav

• Install and Start
• How It Works
• Hands-Free Quick Start
• Features
• Supported Backends
• IDE Support
• UI Overview
• Controls
• Documentation
• Contributing
• For Developers
• Support

Install and Start

Install one supported AI CLI first:

Codex:

npm install -g @openai/codex

Claude Code:

npm install -g @anthropic-ai/claude-code

Anthropic also provides a native installer: curl -fsSL https://claude.ai/install.sh | bash.

Then choose one VoiceTerm setup path:

Homebrew (recommended)

brew tap jguida941/voiceterm
brew install voiceterm
cd ~/your-project
voiceterm

If needed, authenticate once:

voiceterm --login --codex
voiceterm --login --claude

PyPI (pipx / pip)

pipx install voiceterm
# or: python3 -m pip install --user voiceterm

cd ~/your-project
voiceterm

If needed, authenticate once:

voiceterm --login --codex
voiceterm --login --claude

From source

Requires Rust toolchain. See Install Guide for details.

git clone https://github.com/jguida941/voiceterm.git
cd voiceterm
./scripts/install.sh

If you are running from source while developing, run:

make ci
make build
./scripts/start.sh

scripts/start.sh selects or downloads a Whisper model before launching the local release binary. Running rust/target/release/voiceterm directly requires an explicit --whisper-model-path unless the model is under the repository's whisper_models/ directory.

macOS App

Double-click app/macos/VoiceTerm.app, pick a folder, and it opens Terminal with VoiceTerm running.

For model options and startup tuning:

• Install Guide
• Whisper docs
• Troubleshooting

How It Works

VoiceTerm listens to your mic, converts speech to text on your machine, and types the result into your AI CLI input.

Requirements

• macOS or Linux (Windows needs WSL2)
• Microphone access
• ~0.5 GB disk for the default small model (base is ~142 MB, medium is ~1.5 GB)

Hands-Free Quick Start

VoiceTerm supports a fully hands-free workflow - no typing needed at all.

voiceterm --auto-voice --wake-word --voice-send-mode insert

1. Say the wake phrase (hey codex or hey claude)
2. Speak your prompt
3. Say send or submit to deliver it

Features

Main features

Feature	What it does
Local speech-to-text	Whisper runs on your machine - no cloud calls needed
Fast voice-to-text	Local Whisper turns speech into text quickly
Keep your CLI as-is	Your backend CLI layout and behavior stay the same
Auto voice mode	Keep listening on so you can talk instead of typing
Wake mode + voice send	Say hey codex/hey claude, then say send/submit
Image prompts	Use Ctrl+X for screenshot prompts, or enable persistent image mode
Live dictation	Dictate the next instruction while an agent is working; Codex stages it immediately, while Claude delivers it when ready
Codex + Claude support	Primary support for Codex and Claude Code

Everyday tools

Tool	What it does
Voice navigation	Spoken scroll, send, show last error, copy last error, explain last error
Voice macros	Expand phrases from .voiceterm/macros.yaml - see Voice Macros
Built-in themes	11 themes including ChatGPT, Catppuccin, Dracula, Nord, Tokyo Night, and Gruvbox
Transcript history	Ctrl+H to search and replay past text
Notification history	Ctrl+N to review recent status messages
Saved settings	Stored in ~/.config/voiceterm/config.toml
HUD controls	Mouse and keyboard both work by default
Live Theme Studio	Preview HUD borders, style, panel, colors, and glyph changes immediately without repainting the conversation

For full details: Usage Guide.

Supported AI CLIs

VoiceTerm is optimized for Codex and Claude Code. For full backend status and setup details, see Usage Guide - Backend Support.

Backend	Status	Notes
Codex	Supported	Default backend
Claude Code	Supported	Full support on current releases
Gemini CLI	Experimental	Not working in current releases
Other/custom backends	Experimental	See the usage guide for current limits

IDE Support

IDE host	Codex	Claude Code	Notes
Cursor terminal	Fully supported	Fully supported	Recommended host
JetBrains terminals (IntelliJ, PyCharm, WebStorm, CLion)	Fully supported	Fully supported	Validated with current Codex and Claude terminal flows
AntiGravity	Not yet supported	Not yet supported	Not available in current releases
Other IDE terminals	Unverified	Unverified	Treat as experimental

For more IDE details: Usage Guide - IDE Compatibility.

UI Overview

Theme Studio

Press Ctrl+Y to edit HUD and theme visuals. Theme Studio keeps a live HUD preview beneath its isolated panel, so border, HUD style, right-panel, color, and glyph changes appear immediately without scrolling or repainting the conversation.

For details: Theme Studio · HUD styles.

Theme Picker

For details: Themes · CLI Flags.

Settings Menu

For details: Settings Menu · Themes · HUD styles.

Transcript History

Ctrl+H opens conversation history with mic, you, and ai rows. You can search all rows and replay microphone/user inputs; AI output remains read-only.

For details: Transcript History.

Shortcuts Overlay

Press Shift+? to open the shortcuts overlay with grouped hotkeys and clickable links to Docs and Troubleshooting.

For details: Core Controls.

Controls

For shortcuts and behavior, see:

• Core Controls
• Settings Menu
• Voice Modes

For CLI flags and command-line options:

• voiceterm --help (or voiceterm -h)
• CLI Flags

Voice Macros

Note: Voice macros are still in development and may have rough edges.

Voice macros are project-local shortcuts in .voiceterm/macros.yaml. Turn macros on in Settings when you want phrase expansion. Setup and examples: Project Voice Macros.

Documentation

Start with the shortest useful doc for your goal:

Audience	Document
User	Quick Start
User	Guides Index
User	Install Guide
User	Usage Guide
User	CLI Flags
User	Troubleshooting
Developer	Contributor Guide
Developer	Scripts

Contributing

PRs welcome. See CONTRIBUTING.md. Before opening a PR, run:

• make ci
• make integration
• markdownlint -c .markdownlint.yaml -p .markdownlintignore README.md QUICK_START.md CHANGELOG.md guides/*.md scripts/*.md scripts/tests/*.md app/*.md pypi/*.md .github/*.md .github/ISSUE_TEMPLATE/*.md .github/PULL_REQUEST_TEMPLATE/*.md .github/workflows/README.md

For Developers

Looking to contribute or dig into the codebase? Start with the Contributor Guide, the scripts reference, and the Rust source under rust/.

When do I run what?

When	Command
Quick sanity check while coding	make check
Before pushing to GitHub	make prepush
Full CI-equivalent check locally	make ci
Rust tests only	cd rust && cargo test --bin voiceterm
PyPI launcher tests	python3 -m unittest discover -s pypi/tests
Integration smoke test	make integration
Validate release versions	make release-check V=X.Y.Z

Support

• Troubleshooting: guides/TROUBLESHOOTING.md
• Bug reports and feature requests: GitHub Issues
• Security concerns: .github/SECURITY.md

License

VoiceTerm is source-available under the proprietary evaluation license in LICENSE.

• No third-party commercial use, production use, hosting, redistribution, or derivative commercialization is allowed without prior written permission.
• Separate commercial or production rights require a direct written license from the Licensor.