Getting Started

What is TUI Writer?

TUI Writer is a terminal-based application that combines real-time speech transcription with AI-powered editing. Unlike traditional transcription tools that simply convert speech to text, TUI Writer acts as an intelligent companion that understands natural language editing commands.

Core Workflow:
1. Speak into your microphone
2. See your words transcribed in real-time
3. Make edits by speaking naturally: “change that to…” or “delete the last sentence”
4. The AI automatically detects and applies your edits
5. Copy the final transcript to your clipboard

For developers new to nbdev, the following sections explain the development workflow.

Install TUI Writer in Development Mode

For development and contributions, install the package in editable mode:

# Clone the repository
git clone https://github.com/Swiftner/tui_writer.git
cd tui_writer

# Install in development mode
pip install -e .

# Make changes under nbs/ directory
# The notebooks in nbs/ are the source of truth

# After making changes, regenerate the Python modules
nbdev_prepare

The nbdev_prepare command: - Exports code from notebooks to Python modules - Runs tests - Updates documentation - Cleans notebook outputs

Usage

Installation

Installation Options

Install TUI Writer using pip:

pip install tui_writer

Or using uv:

uv tool install tui_writer

Prerequisites

TUI Writer requires:
- Python 3.9 or higher
- A working microphone
- API key for at least one LLM provider (OpenAI, Anthropic, or Google)

First Run Setup

After installation, launch the application:

tui_writer

On first run, you will need to:
1. Press a to open AI settings
2. Select your preferred provider (OpenAI, Anthropic, or Google)
3. Choose a model
4. Enter your API key
5. Press Apply

The configuration is saved to ~/.config/tui_writer/tui_writer.conf and persists across sessions.

Basic Usage

Once configured:
- Press SPACE to start recording
- Speak naturally - your words appear in real-time
- Say edit commands like “change that to…” and they are applied automatically
- Press SPACE to stop recording
- Press C to copy the transcript to clipboard
- Press Q to quit

For detailed documentation on all features, press ? in the application to view the help screen.

Using Omarchy Keybindings

Some users may want to use Omarchy to play back previously recorded terminal sessions using tools such as script or asciinema.

These tools record the text output of your terminal session. Useful for quick debugging, demos, and sharing reproducible steps.

Example: Record and replay a terminal session

Record using script:

script session.log
# ...run any terminal commands you want recorded...
exit

Replay using scriptreplay:

scriptreplay session.log

Binding playback to a key in Omarchy

Add a keybinding in your Omarchy config:

[keybindings]
p = "scriptreplay ~/session.log"

Press P to replay the session.

Example using asciinema

Record:

asciinema rec demo.cast

Play back:

asciinema play demo.cast

These examples can be adapted to your workflow if you use Omarchy alongside TUI Writer.