earheart: Instructions file for Codex

Earheart — Agent guide

Guidance for AI agents (and humans) contributing to Earheart.

Earheart is a hotkey-driven voice dictation app (Electron) that speaks a prompt into Claude Code, Codex, Cursor, or any focused window, fully local. A change is done when its code, tests, and docs land together in one reviewed PR with CI green on Linux, macOS, and Windows. This project follows GitHub flow: main is always releasable, all work happens on short-lived branches, and every change lands through a reviewed pull request.

Read README.md for setup, and CONTRIBUTING.md for the full architecture. This file is the operational checklist for how to work here.

Prerequisites

• Node.js ≥ 22.12 + npm — the locked Electron toolchain needs 22.12. .nvmrc is provided, so nvm use picks up the newest Node 22.
• The gh CLI — for opening PRs.
• A display for the smoke checks — on Linux, the make smoke targets already wrap Electron in xvfb-run -a (install Xvfb); on macOS and Windows run the underlying npx electron … commands directly, as CI does.
• GNU Make — for the make targets (on Windows, run the underlying commands instead).
• uv — only if you touch the optional Python server in stt-server/.
• No keys needed. Built-in models download to Electron's userData/models on first use; tests and smoke checks don't need them present.

Commands

The Makefile wraps most tasks; make help lists them all.

• Install / bootstrap: make install (npm ci, exactly as locked, then fetches the Electron binary, as CI does). To add or bump a dependency, use make deps-update (npm install) and commit the updated package-lock.json.
• Run locally: make run
• Lint / format / type-check: none — plain JavaScript, no linter configured.
• Test (all): make test (node --test with a 30 s per-test timeout, no framework)
• Test (single file): node --test --test-timeout=30000 test/pipeline.test.js
• Smoke checks (Linux): make smoke, make engine-smoke, make overlay-smoke, make settings-smoke (each wraps xvfb-run -a)
• Smoke checks (macOS / Windows): the same commands without xvfb-run: npx electron . --smoke-test --no-sandbox, then npx electron scripts/<engine|overlay|settings>-smoke.js --no-sandbox
• STT server tests: make test-stt (runs uv run --locked --extra test python -m pytest in stt-server/)
• Cleanup model benchmark (optional; needs a downloaded GGUF, not part of the gate): node scripts/bench-cleanup.mjs --out=<dir outside the repo> <model.gguf>; --probe <owner/repo> <file.gguf> checks a candidate on Hugging Face without downloading it, and --report <dir> rebuilds the comparison tables from saved runs. Method and recorded numbers: docs/cleanup-models.md
• Technical dictation eval (optional; needs a downloaded GGUF, not part of the gate): node scripts/eval-technical.mjs [--gpu] --out=<dir outside the repo> [--prompt=<base prompt file>] <model.gguf>, then `--report
• Long-recording STT measurement (optional; needs Electron and the scripts/eval-stt.js corpus/model cache, not part of the gate): xvfb-run -a npx electron scripts/eval-long-decode.js --no-sandbox --cache-dir <cache> --out <file outside the repo> --single; exits 1 when a long recording loses words. --before adds the old cut-at-every-pause splitter side by side, and --dictation [--seed N] runs dictation-shaped recordings (hesitations, clicks, breaths). Method and recorded numbers: docs/long-recordings.md
• Build: make dist (current platform)
• Release merged PRs: make release dispatches the catch-up release workflow on remote main using authenticated gh. It creates one version for all pending merged PRs; local changes are excluded. Track completion with gh run list --workflow auto-release.yml.