dictcode

Voice-to-code CLI tool. Speak and let your words flow into your clipboard, terminal, or directly into Claude Code.

Features

• Speech-to-text via OpenAI Whisper API or a local Whisper binary
• Multiple output targets: clipboard (Cmd+V), stdout, or Claude Code
• dictcode --claude: continuous voice conversation mode with Claude Code, with session persistence
• Silence detection: recording stops automatically when you stop speaking
• Push-to-talk mode
• Pipe mode (--pipe): non-interactive, composable with other CLI tools
• Interactive setup wizard on first run

Prerequisites

• Node.js >= 18
• sox (for microphone recording): brew install sox
• OpenAI API key (for the OpenAI Whisper provider) or a local Whisper binary
• Claude Code (optional, for --claude and --output claude)

Run dictcode --check to verify your setup.

Installation

npm install -g dictcode-cli

Quick start

# First run triggers the interactive setup wizard
dictcode

# Or set up manually
dictcode --setup

Usage

dictcode — single transcription

# Record and copy to clipboard (default)
dictcode

# Record and print to stdout
dictcode -o stdout

# Record and send to Claude Code
dictcode -o claude

# Use local Whisper instead of the API
dictcode -p local

# Push-to-talk: hold a key to record, release to stop
dictcode --push-to-talk

# Pipe mode: non-interactive, outputs plain text to stdout
dictcode --pipe

dictcode --claude — continuous voice mode with Claude Code

A voice-driven loop: speak, get a Claude Code response, speak again. Sessions are persisted automatically.

dictcode --claude

# Use local Whisper
dictcode --claude -p local

Say "new session" to start a fresh conversation.

Options

| Flag | Description | |---|---| | -p, --provider <name> | openai-api (default) or local | | -m, --model <model> | Whisper model (e.g. whisper-1, base, large-v3-turbo) | | -o, --output <target> | clipboard (default), stdout, or claude | | --claude | Start continuous voice conversation with Claude Code | | --push-to-talk | Hold any key to record, release to stop | | --pipe | Non-interactive mode for scripting | | --check | Verify prerequisites | | --setup | Run the setup wizard |

Configuration

Config is stored at ~/.config/dictcode/config.json. Example:

{
  "provider": "openai-api",
  "openai": {
    "apiKey": "sk-...",
    "model": "whisper-1"
  },
  "local": {
    "binaryPath": "/opt/homebrew/bin/whisper",
    "model": "base"
  },
  "recording": {
    "silenceThreshold": 0.5,
    "silenceDuration": "1.5"
  },
  "defaultOutput": "clipboard",
  "prompt": "TypeScript, React, Next.js, Claude Code"
}

The prompt field provides context to Whisper so it better recognizes domain-specific terms.

The OpenAI API key can also be set via the OPENAI_API_KEY environment variable.

Development

npm install
npm run build    # compile TypeScript
npm run dev      # compile in watch mode
npm start        # run the CLI

License

MIT