TermSpeak

Voice-first web UI for terminal-based AI coding assistants such as Claude Code, Codex CLI, and Aider, while keeping the real CLI session running through a PTY.

TermSpeak is built for developers who already work in the terminal and want a faster way to talk to coding assistants without giving up a real CLI session.

Why TermSpeak

• Speak prompts instead of typing everything by hand
• Keep assistants running in a real interactive terminal session through PTY
• Switch between multiple providers such as Claude Code, Codex CLI, and Aider
• Choose the working directory before each session
• Use it alongside VS Code, Cursor, or any editor, as long as your assistant runs in the terminal
• Run everything locally on your own machine

Features

• Voice dictation with Web Speech API
• Text input with prompt history
• Built-in terminal view with xterm.js
• Multi-provider configuration
• Per-session working directory selection
• English and Portuguese (Brazil) UI support

The project now supports two interface languages out of the box:

• English
• Portuguese (Brazil)

Users can switch the UI language and the dictation language independently inside the app.

Architecture

• apps/server: Node.js server with node-pty, Express, WebSocket, and dynamic config loading
• apps/web: React + Vite frontend with xterm.js and Web Speech API dictation
• packages/shared: shared types and schemas used by server and web

Requirements

• Node.js 20+
• A Chromium-based browser with Web Speech API support, such as Chrome or Edge
• At least one assistant CLI available in your PATH, such as claude, codex, or aider

Install and run

From npm / npx

Package name on npm:

promptmic

Installed executable:

promptmic

The default user flow is:

npx promptmic

This starts TermSpeak locally and prints the URL in the terminal without opening the browser by default.

If you want the browser to open automatically:

npx promptmic --open

If you want to delete the saved local config and start fresh:

npx promptmic --reset-config

If you install it globally, the executable name is:

promptmic

That means:

• use npx promptmic when running directly from the npm package name
• use promptmic after a global install

Security note

TermSpeak is intended for local use on your own machine.

• by default it binds to 127.0.0.1
• do not expose it on 0.0.0.0 or another non-local host unless you explicitly understand the risk
• non-local binding can expose terminal session control, file-system access, and assistant configuration to other machines

Quick start

git clone [email protected]:lucasaclima03/term-speak.git
cd term-speak
npm install
npm run dev

Then open http://localhost:5173 in your browser.

The Vite dev server runs on 5173 and proxies API/WebSocket traffic to the local backend on 3001.

If no providers are configured yet, the app opens the Settings dialog automatically on first launch.

Run locally

Development mode

npm run dev

• Open the app at http://localhost:5173
• The local API server runs at http://localhost:3001
• In repository development mode, the server will use ./config.json if it exists
• On first launch, the Settings dialog opens automatically only if no providers are found in that config

Production-style local run

This matches the published CLI behavior more closely:

npm run build
npm run start

• The backend serves the built frontend directly on http://127.0.0.1:3001
• By default, this mode uses ~/.term-speak/config.json
• If that file does not exist yet, the first run starts with no providers and the onboarding flow begins in the UI

To run the production-style server while still using the repository config file:

npm run start:repo

Configuration

Published CLI / npx usage

When you run TermSpeak from npm, it stores configuration in:

~/.term-speak/config.json

You do not need to create that file manually. On first run, if no providers are configured yet, the UI opens the Settings dialog and saves the configuration there.

Repository / source usage

If you cloned the repository and want to use a repo-local config file, create:

cp config.example.json config.json

In repository development mode, the local server can read ./config.json and reloads it whenever the UI sends POST /api/config.

To actually start a session in any mode, you must have the configured assistant installed locally and available in your shell PATH.

If you want to use shell wrappers or functions such as personal or work, they must be available in your login shell.

Config locations

• npm run dev: prefers ./config.json in the repository
• if ./config.json does not exist in npm run dev, the app starts with an empty config for onboarding instead of falling back to ~/.term-speak/config.json
• npm run start: uses ~/.term-speak/config.json
• npm run start:repo: forces ./config.json
• npx promptmic: should behave like npm run start

To reset the default local config file used by the published CLI:

npx promptmic --reset-config

To reset a specific config file instead:

npx promptmic --config ./config.json --reset-config

Provider fields

| Field | Type | Required | Description | |---|---|---|---| | label | string | Yes | Label shown in the UI | | executionMode | "direct" \| "shell" | No | direct runs the executable directly. shell runs the command through the user's interactive shell. Defaults to shell for backward compatibility. | | command | string | Yes | In direct, the executable name available in PATH. In shell, any shell command, alias, or function available in the user's shell. | | args | string[] | No | Extra command arguments | | env | Record<string, string> | No | Extra environment variables, with ~/ expansion |

Execution modes

• direct is the recommended default for most providers because it runs the CLI directly and avoids shell startup noise
• on macOS and Linux, direct also probes the user's interactive shell to recover user PATH entries when the app was launched from a GUI or another stripped-down environment
• shell is useful when you rely on shell wrappers, aliases, or functions such as personal, work, or custom environment bootstrap commands
• direct still requires a real executable; aliases and shell functions remain a shell use case
• In shell mode, anything printed by your shell startup files can appear at the start of the session

Troubleshooting command resolution

• If a provider works in your terminal but fails inside TermSpeak, prefer direct with a real executable name or absolute path
• If the executable lives in a user-managed bin directory such as ~/.local/bin, ~/.nvm/.../bin, or a Homebrew prefix, TermSpeak will try to recover those PATH entries from your interactive shell on macOS and Linux
• For maximum portability across macOS, Linux, and Windows, use an absolute executable path when you can
• If you depend on aliases, shell functions, or wrapper commands, switch that provider to shell
• You can also set PATH explicitly in the provider env when you need a fully controlled runtime environment

Example: multiple Claude accounts with direct execution

{
  "providers": {
    "claude-personal": {
      "label": "Claude (Personal)",
      "executionMode": "direct",
      "command": "claude",
      "args": [],
      "env": { "CLAUDE_CONFIG_DIR": "~/.claude-personal" }
    },
    "claude-work": {
      "label": "Claude (Work)",
      "executionMode": "direct",
      "command": "claude",
      "args": [],
      "env": { "CLAUDE_CONFIG_DIR": "~/.claude-work" }
    }
  },
  "defaultProvider": "claude-personal"
}

Example: shell wrapper commands

{
  "providers": {
    "claude-personal": {
      "label": "Claude Personal",
      "executionMode": "shell",
      "command": "personal",
      "args": [],
      "env": {}
    },
    "claude-work": {
      "label": "Claude Work",
      "executionMode": "shell",
      "command": "work",
      "args": [],
      "env": {}
    }
  }
}

Example: Aider + Codex

{
  "providers": {
    "aider": {
      "label": "Aider",
      "executionMode": "direct",
      "command": "aider",
      "args": ["--no-auto-commits"],
      "env": {}
    },
    "codex": {
      "label": "Codex CLI",
      "executionMode": "direct",
      "command": "codex",
      "args": [],
      "env": {}
    }
  }
}

Usage

1. Configure one or more assistants.
2. Choose the assistant in the dropdown.
3. Choose a working folder.
4. Start a session.
5. Speak or type prompts.
6. Stop the session when finished.

Who this is for

TermSpeak is a good fit if you:

• use claude, codex, aider, or similar terminal-based assistants
• want voice input without leaving your local development workflow
• prefer editing in VS Code, Cursor, Neovim, or another editor while your assistant runs in the terminal

TermSpeak is not an IDE extension. It is a local voice interface for assistant CLIs.

Development notes

• config.json is intentionally ignored and should stay local
• Do not commit node_modules, dist, or other generated local assets
• If you change user-facing copy, update both supported UI languages: English and Portuguese (Brazil)

Contributing

Contribution guidelines live in CONTRIBUTING.md.