voxtex 0.1.1

Voxtex: talk to your thesis, get LaTeX that compiles.

You point it at a LaTeX project and talk, in Greek, English or both. It reads how your thesis is set up (packages, citation commands, macros, labels, the bibliography, how you write) and turns what you say into clean academic LaTeX. Your chapter opens in voxtex's terminal editor, which works like Wispr Flow: press ctrl+space, talk, press it again. What you said is written at the cursor in your own words, only formatted as LaTeX (punctuation, citations, \en{} terms, maths). Select text first and what you say is an instruction for it ("make this more formal", "add the Broekstra citation"). The mic records only between the two presses, so typing and clicks never end up in the thesis, and nothing you say is ever dropped. Every write is checked first.

Install

With uv:

uv tool install "voxtex[gpu]"     # NVIDIA GPU; on other machines: uv tool install voxtex

On Linux and WSL, the microphone needs three system packages:

sudo apt install -y libportaudio2 libasound2-plugins pulseaudio-utils

A TeX installation (pdflatex or xelatex) is optional. With one, voxtex compiles anything unusual it writes inside your real preamble before writing it.

First run

cd my-thesis                             # the folder with your main .tex file
voxtex                                   # first time: a one-minute setup, then the editor

Setup looks at your machine first (GPU, Ollama, keys you already have) and only asks what it can't decide: whether everything should stay on this machine, and a free Groq key, tested on the spot. Run voxtex init to change it later and voxtex doctor to check everything.

voxtex edit chapters/results.tex         # open a specific chapter
voxtex index                             # show what voxtex learned about the thesis

In the editor, ctrl+space starts and stops recording (esc cancels); the text goes at the cursor, or replaces the selection if you selected something. Say punctuation ("κόμμα", "full stop") and it becomes the mark; say "undo" ("αναίρεση", "undo twice") to take back the last edit. If Whisper only heard noise, or wasn't sure of the language and another one fits better, nothing odd is written: a message shows what it heard so you can say it again. ctrl+t switches to unfiltered: what you say goes in exactly as heard, with no AI (press it again for AI formatting). ctrl+p picks a theme (charcoal by default, voxtex, catppuccin, nord, gruvbox, dracula, tokyo-night, solarized, rose-pine, ...); the background always stays your terminal's. ctrl+g shows or hides small graphs of what's in use (AI calls and tokens, speech time, and the GPU when speech or the local model runs on it). ctrl+z undoes, ctrl+o opens any .tex file in the thesis folder (type to filter, esc to go back), ctrl+q quits. voxtex saves after every voice edit, a moment after you stop typing, and on ctrl+s (with a backup in .voxtex/backups/ before the first save), so your PDF viewer and other editors see the changes right away.

To keep using your own editor, there are two other ways in. voxtex listen writes at a %> HERE line in the file. voxtex watch works with any dictation app (Voxtype, Windows Win+H, macOS dictation): dictate onto lines that start with %> and save, and each block of %> lines becomes LaTeX.

What you control

• The files. voxtex writes where your cursor is (or rewrites what you selected) in the chapter you opened, and nowhere else. Saves are atomic, so other programs never see half a file. Before the first save of a session it copies the file to .voxtex/backups/. Voice edits are part of the editor's undo, and a change to a selection you've since edited is written beside it instead.
• What leaves your machine. The AI model gets what you said, about 800 characters of text before the cursor (and the selection, if any), and the few bibliography entries and labels that match. Your audio stays local when speech-to-text runs locally. --private keeps everything on your machine: local Whisper and a local model through Ollama.
• What gets written. Before anything touches a file, voxtex checks that every citation key is in your .bib, every reference points to a real label, new labels follow your naming pattern, every number was actually said, braces and environments balance, and (for unfamiliar commands) that it compiles. A failure gets one automatic retry. If that fails too, the text is still written, tinted yellow, with a short message saying what to look at (listen and watch add a % voxtex-check: comment instead). If no AI answers at all, your words go in exactly as heard.
• The cost. The default setup is free: a chain of free tiers (Groq, then Gemini and OpenRouter if you add keys) that ends in a local model. When one runs out, the same request moves to the next. A decision uses about 1,300 input tokens; .voxtex/timings.log records every call.

Commands

Configuration

voxtex init writes ~/.config/voxtex/config.toml, and keys go in ~/.config/voxtex/.env. A .voxtex.toml (or .env) in the thesis folder overrides them for that thesis. Everything is optional:

[llm]
chain = ["groq-gptoss", "groq-qwen", "gemini", "openrouter", "local"]

[providers.local]
model = "qwen2.5-coder:14b"          # any model you've pulled into Ollama

[writing]
style = "academic"                   # academic | clean
language = "auto"                    # auto | el | en

[stt]
mode = "auto"                        # auto | local | groq | openai | external
local_model = "auto"                 # auto | small | medium | large-v3-turbo

[listen]
utterance_pause = 0.9                # seconds of silence that end an utterance
decision_pause = 2.5                 # seconds of silence before a thought is written

[validate]
compile = "auto"                     # auto | always | off

Project status

voxtex is in beta (0.1). It's built and tested on a Greek thesis on WSL2 with an NVIDIA GPU; other setups are less tested, so issues are welcome. The original build plan is in docs/voxtext_plan.md and docs/PLAN-ADDENDUM.md.

To work on it:

git clone https://github.com/dhthz/voxtex.git && cd voxtex
uv sync --extra gpu
uv run pytest            # tests run without a microphone, a GPU or an API key
uv run ruff check .

License: MIT.