VoxStride

VoxStride is a screen-reader-first Windows desktop agent with spoken progress and equivalent text. The current Windows application is VoxStride Desktop, and its main window is the VoxStride Control Hub. It wraps a persistent Codex App Server conversation, supports live steering and interruption, sends foreground announcements through the screen reader and background announcements through Windows SAPI, and exposes the same information as text.

Why VoxStride is different

VoxStride is led by a blind Windows user through a fully text-based development workflow with JAWS and AI coding agents. Its accessibility behavior is treated as an engineering contract, not a visual layer added after the agent works. Every spoken event has equivalent transcript text, the native Request editor remains usable with JAWS, transcript updates preserve the reader's position, and synthetic agent input is isolated from physical and assistive input.

The project also treats truthful status as an accessibility feature. It does not announce success or interruption until the underlying system confirms it, and its automated release gate checks the live accessibility tree, assistive keyboard input, browser recovery, session persistence, and installed Windows application.

Open source

VoxStride is open source under the MIT License. Contributions from screen-reader users, Windows accessibility developers, agent-tooling authors, testers, and documentation writers are welcome. Start with CONTRIBUTING.md, which describes the accessibility contracts and verification required for changes.

Product naming

• Permanent brand: VoxStride
• Repository name: voxstride
• Current Windows application: VoxStride Desktop
• Current window: VoxStride Control Hub

Names such as VoxStride Voice, VoxStride Mobile, and VoxStride Runtime are reserved for possible future components. The project will use “voice-first” in its public description only after spoken request input is genuinely available.

Keyboard use with JAWS

1. Press Ctrl+Alt+Space anywhere. Focus moves to the standard multiline edit named Request. JAWS gives one concise Request announcement instead of repeating status and help text.
2. Type an outcome and press Enter to send it. The Hub hides and explicitly yields input while the task runs.
3. Press Shift+Enter to insert a new line instead of sending.
4. Press Ctrl+Alt+Space again to read the transcript or type a steering update. From Request, press Tab until JAWS announces the conversation transcript.
5. Press Ctrl+Alt+Escape anywhere to summon the Hub and request interruption. The transcript first records Interrupt requested, then records Interrupted only after App Server confirmation.
6. Press Ctrl+Alt+M to mute or unmute speech. Muting never removes transcript events.

Use New conversation at a major topic boundary. It clears the visible and persisted transcript, waits for an active turn to confirm interruption, starts a new Codex conversation, and returns focus to Request without a redundant spoken Ready announcement.

The global shortcuts are configurable in %LOCALAPPDATA%\VoxStride\settings.json. The persistent conversation and transcript are stored in session.json beside that file. On first launch after upgrading from the former name, VoxStride copies existing settings and session data without overwriting any VoxStride data already present.

Build, test, publish, and install

The supported entry points discover the .NET 10 SDK and bundled Node runtime; they do not depend on one Windows username or a version-hashed Codex path.

# Release build and self-tests
.\scripts\verify.ps1

# Full release gate against the installed package, with JAWS running
.\scripts\verify.ps1 -InstalledSmoke

# Or package and install separately
.\scripts\publish.ps1
.\scripts\install.ps1

publish.ps1 creates a self-contained Windows x64 package. install.ps1 installs it per user under %LOCALAPPDATA%\Programs\VoxStride, creates a VoxStride Desktop Start Menu shortcut, creates a start-at-login shortcut by default, and launches the Hub. Pass -NoStartAtLogin or -NoLaunch when desired.

Installation and verify.ps1 -InstalledSmoke refuse to replace VoxStride Desktop when their caller is a live VoxStride Desktop session. Finish and preserve source work there, then the agent automatically opens and manages a separate Codex desktop session to run the installation gate without asking the user to use engineering tools.

The solution entry point is VoxStride.slnx. Override discovery with VOXSTRIDE_CODEX_CLI_PATH, VOXSTRIDE_DOTNET_PATH, VOXSTRIDE_NODE_PATH, or VOXSTRIDE_AGENT_WORKSPACE. Stale or incomplete saved Codex bundle paths are repaired automatically on startup.

For future maintenance, start with:

• Architecture and invariants
• Maintenance, release, and troubleshooting
• Testing, JAWS, accessibility-tree, and visual passes
• Repository instructions for coding agents

Runtime behavior

• States are exactly: Ready, Running, Waiting for input, Interrupt requested, Interrupted, Completed, and Failed.
• The App Server thread ID and transcript persist, and the app uses thread/resume after relaunch.
• New text during a running turn uses turn/steer; the interrupt shortcut uses turn/interrupt.
• Server-streamed agent text, meaningful tool milestones, state changes, and queued speech are represented as compact plain text. Speech is marked on its related event instead of repeated on a separate narration row; routine reconnect history and raw diagnostic JSON are compacted.
• While the Hub is hidden and work is happening, the VoxStride voice has priority: it keeps spoken updates in order, asks JAWS to stop automatic window descriptions while each update is spoken, and finishes queued narration before the next Windows action. Summoning the Hub lets the current VoxStride sentence finish, then returns speech to JAWS. When the Hub has focus, Windows accessibility notifications are used instead of starting new VoxStride voice speech.
• Summoning normally relies on the native Request focus announcement. If a VoxStride sentence was already speaking, one short fallback—Request edit. Agent running, or the corresponding current state—is sent after that sentence finishes. Detailed status and keyboard help remain available in their own controls instead of being repeated on every summon.
• Completed agent message blocks are spoken as plain text beginning with Agent says. Earlier queued VoxStride voice updates remain in order, and each generic command, Windows-app, or connected-tool milestone is announced at most once per request.
• Incoming transcript output preserves the caret and scroll position while the transcript is focused, so new events do not pull JAWS away from the text the user is reviewing.
• A named input gate plus low-level keyboard and mouse hooks rejects only input carrying the agent controller's private marker while the user owns the Hub. Physical input and JAWS remain available, and release events always pass so Summon cannot leave Ctrl, Alt, or a mouse button stuck.
• Native Windows work uses UI Automation first, with guarded input only when semantic patterns are unavailable.
• If browser control finds no browser window or tab, the agent can start the default or requested installed browser, wait for a controllable window, and retry without asking the user to open it.
• The app runs asInvoker. Windows secure desktop and unelevated-to-elevated UI Automation are deliberate boundaries; the privileged-helper design is documented in STAGE0_RESULTS.md.

Known browser boundary

Chrome and Edge downloads passed. Browser-extension upload is unavailable until Allow access to file URLs is enabled for the ChatGPT extension. The agent cannot silently change that privileged extension setting. Bidirectional harmless test-file transfer passed through command-line HTTP tooling, and the limitation is surfaced truthfully in the transcript and Stage 0 report.