Welcome to hns Documentation

Speech-to-text CLI. 100% local. Built for developers.

---

This documentation provides a comprehensive guide to installing, configuring, and using hns—a CLI tool to record and transcribe speech to text, designed for developers.

Overview

hns is a local speech-to-text CLI that uses Whisper for offline speech recognition. It records audio from your microphone and transcribes it directly to your clipboard. Integrate hns with Claude Code, Ollama, LLM, and more CLI tools for powerful voice input workflows.

With hns, you can:

• Drive AI coding agents like Claude Code, Codex CLI, and Cursor CLI with your voice
• Dictate and get polished text for emails, Slack messages, and documents
• Speak freely in a stream-of-consciousness style for voice journaling and note-taking

...and much more! Just integrate hns with your favorite CLI tools.

Quick Start

Install hns using uv or pipx, and then run hns in your terminal.

uv (Recommended)

uv tool install hns

pipx

pipx install hns

pip

pip install --user hns

When you see 🎤 Recording..., speak the following sentence clearly into your microphone: "In the beginning the Universe was created. This has made a lot of people very angry and been widely regarded as a bad move".

Press Enter when you're done. The transcribed text will be printed to your terminal and copied directly to your clipboard, ready to be pasted anywhere with Ctrl+V or Cmd+V.

Highlights

• Speech to Clipboard: Transcribed text is automatically copied to your clipboard for immediate pasting
• Composability (The Unix Way): Transcription is written to stdout and progress/status messages to stderr. Easy to integrate with other CLI tools
• 100% Local Speech Recognition: Audio is processed entirely on your local machine using local Whisper. No data leaves your device
• Offline Voice to Text: After the initial model download, no internet connection is required. Works on Linux, macOS, and Windows
• Multi-Language Support: Transcribe in any language supported by Whisper
• Configurable: Choose models and languages via environment variables
• Open Source Speech to Text: MIT licensed, fully transparent

Navigating the Documentation

This documentation is organized into the following sections:

Get Started

• Quick Start: Step-by-step instructions to get hns up and running in 30 seconds.
• Installation: Detailed installation guide along with instructions to upgrade to the latest version.
• Configuration: Guide to configuring hns via environment variables to match your hardware and transcription needs.
• CLI Reference: Comprehensive reference for all hns command-line options.

Use Cases

• Overview: Explore various use cases and workflows enabled by hns.
• Voice to Polished Text: Detailed guide on transforming raw dictation into polished text using hns and LLMs.
• Drive Coding Agents: Provide detailed, context-rich instructions to AI coding agents like Claude Code using your voice.
• Effortless Voice Journaling: Sustainable voice journaling workflow using hns and LLMs.