HoldSpeak connects voice typing, meetings, project records, and AI work on one Desk. You choose the models, data sources, and authority for each kind of work.
Use it to dictate into an editor, prepare a decision brief, review a meeting, or direct a Coder session. The Interview mode helps you describe your work and develop useful suggestions through a conversation.
These documents describe the code on main. A published release can have fewer features.
See the change history for release information.
Read Getting Started for platform requirements and installation options.
For a source installation, install Python 3.10 or later, uv, and Node.js 22.12 or later first.
The Python build hook also builds the Web app.
git clone https://github.com/karolswdev/HoldSpeak.git
cd HoldSpeak
uv venv
source .venv/bin/activate
uv pip install -e .
holdspeakOn Linux, use uv pip install -e '.[linux]' for the transcription backend.
System audio dependencies and desktop permissions depend on your platform.
- Open the local URL that HoldSpeak prints.
- Select Dictate one sentence.
- Edit the transcript if necessary.
- Select Copy or Keep as Note.
This first result creates the initial Desk contents.
If capture fails, use the recovery action on the screen or run holdspeak doctor.
| Task | How HoldSpeak helps | Guide |
|---|---|---|
| Dictate into another app | Hold the global hotkey, speak, then release it to insert text. | Voice typing |
| Refine a coding prompt | Use project facts, project context, and an optional model in the dictation pipeline. | Dictation pipeline |
| Teach a dictation correction | Select Wrong on a result, correct the words or the route, then Teach. The next dictation that carries the phrase is corrected. | Speak |
| Review a meeting | Record or import a meeting. Review the transcript, decisions, action items, and artifacts. | Meeting mode |
| Develop your working context | Revisit Interview sections for goals, Projects, cadences, decisions, and delegation. | Interview |
| Prepare architecture work | Draft a decision brief, review questions, or an agent brief from available records. | Architecture work recipes |
| Follow project changes | Connect Project sources and configure supported Watches. | Project Rooms |
| Find earlier work | Search Notes, Meetings, Decisions, Threads, Project items, Workbench results, and Cadence loops from one Desk memory window. Connected evidence arrives with the relationship that reached it. | Relationship-aware memory |
| Let the calendar set the clock | Connect an ICS calendar. See the week on the arrival, arm recordings before meetings under your consent, and read the weekly brief. | The clock |
| Direct AI work | Use Threads, Workflows, Coder steering, or an MCP client. | Automation |
| Change your workspace | Select a place, save favorites, or use Settle in. | Places |
The arrival shows work that needs you, unfinished Thoughts, a brief, and recent Meetings. The Floor shows your records as objects that you can open, move, and file in Zones. Speak, Meetings, Settings, and other tools open in Desk windows.
Threads save your conversation on the hub. Your sent prompt appears before the answer arrives. Routine tool calls stay inside the collapsed Actions control. Requests for a decision, tool questions, and failures remain visible. You can keep a reply as a separate Note or Artifact.
Interview uses the existing Thread conversation and MCP tools. It saves context with source references and records suggestions that you can revisit. Try draft sends a request for a manual draft. Keep idea saves your choice about a suggestion. Neither action installs a recurring automation.
The current Interview supports manual preparation and the existing Project setup path. General agent delegation and recurring setup through Interview remain outside this increment. Model quality also varies. Check source claims, assumptions, and draft placeholders before you use a result.
Open Settings > Models to use the Concierge. It detects engines and proposes an assignment for each capability group. Check the engine and host for each group before you select Use these. Use Adjust for individual capability assignments. See Models for local runtimes and endpoint setup.
HoldSpeak stores its database on the hub. Whisper transcription runs on the hub. Configured model endpoints, providers, remote clients, and outbound actions can transfer data to other systems. The boundary and Receipt for a run identify where that work went. See Security & Privacy for storage, credentials, and network boundaries.
The default Control mode is YOLO. Eligible actions to configured destinations can execute without another HoldSpeak approval prompt. Secure and Normal provide different approval rules. See Control modes before you configure actions with external effects.
| Capability | macOS on Apple Silicon | Linux X11 | Linux Wayland |
|---|---|---|---|
| Whisper transcription | MLX Whisper | faster-whisper | faster-whisper |
| Global hotkey and text insertion | Requires desktop permissions | Supported | Depends on compositor restrictions |
| Meeting capture | Microphone and optional BlackHole system audio | Microphone and PulseAudio/PipeWire system audio | Microphone and PulseAudio/PipeWire system audio |
The Web app also accepts browser microphone input. On Wayland, clipboard paste can provide an alternative when direct text insertion is unavailable. See Getting Started for setup and recovery.
The MCP sidecar exposes 222 tools across 40 families. It shares the product service layer. A tool name does not grant permission to execute it. Some live delivery operations require the running Web runtime and are absent from the sidecar.
Meeting intelligence includes 14 built-in plugins. You can add meeting plugins or activity connectors. Automation explains the available triggers, execution paths, and limits.
The iPad app connects to a HoldSpeak hub for capture and review. AIPI-Lite provides a portable device for meeting controls and spoken replies. Both depend on the hub and its configured capabilities.
The main configuration file is ~/.config/holdspeak/config.json.
Use Settings for normal configuration changes.
Run holdspeak backup before an upgrade when you need a recoverable snapshot.
See Release and recovery before you use holdspeak restore.
See Contributing for development setup, documentation rules, checks, and the commit workflow. The documentation index links the user guides and technical references.
HoldSpeak uses the Apache License 2.0.
- Getting Started: install and capture your first sentence.
- User Guide: operate the product each day.
- Architecture: understand the runtime and data flow.
- Documentation index: find a task, reference, or internal specification.