Docs / Getting Started

Getting Started

Install, configure, and start talking to Claude in minutes.

Installation

Talkie is distributed as an npm package. A single command downloads the package, starts an HTTPS server, generates self-signed certificates, and opens your browser:

npx talkiebot

That is all you need. The npx talkiebot command handles everything:

  • Downloads and installs the talkiebot package from npm
  • Generates self-signed TLS certificates at ~/.talkie/
  • Starts an HTTPS server on port 3443 (configurable)
  • Opens your default browser to the Talkie interface
Node.js 18+ required Talkie requires Node.js version 18 or later. Check your version with node --version. Download the latest LTS release from nodejs.org if needed.

If you prefer a global install:

npm install -g talkiebot
talkiebot

System Requirements

Requirement Details
Browser Chrome or Edge (required for Web Speech API support)
HTTPS Auto-handled. Self-signed certs generated on first launch.
Node.js Version 18 or later
OS macOS, Linux, or Windows

The Web Speech API is used for both speech-to-text and text-to-speech. It requires a secure context (HTTPS), which Talkie provides automatically with self-signed certificates. Firefox and Safari have limited or no support for the Web Speech API recognition interface.

First Launch

When you run npx talkiebot for the first time, several things happen in sequence:

  1. Certificate generation — A self-signed TLS certificate and private key are created at ~/.talkie/cert.pem and ~/.talkie/key.pem. These are reused on subsequent launches.
  2. Database creation — An SQLite database is initialized at ~/.talkie/talkie.db with WAL mode enabled for concurrent reads.
  3. Server start — The HTTPS server starts on port 3443 (or the port set by TALKIE_PORT).
  4. Browser opens — Your default browser navigates to https://localhost:3443.
  5. Certificate warning — Your browser will show a security warning because the certificate is self-signed. Accept it to continue (see Troubleshooting below).
  6. Onboarding wizard — On your first visit, a 6-step setup wizard walks you through configuration.

Onboarding

The onboarding wizard runs automatically on your first visit. It consists of six steps that configure your Talkie experience:

  1. Theme selection — Choose from 6 retro themes: TalkBoy, Bubble, Dial-Up, Finder, Guestbook, or 1984. Each theme completely reskins the entire interface. You can change this later from the settings drawer.
  2. Text-to-speech — Toggle TTS on or off and pick a voice from the voices available in your browser. Claude's responses will be read aloud when TTS is enabled.
  3. Sound effects — Enable or disable UI sound effects for actions like sending messages, receiving responses, and navigation.
  4. Wake word — Configure a wake word that activates voice input hands-free. When enabled, Talkie continuously listens for the trigger phrase in the background.
  5. Continuous listening — Set up continuous listening mode and a trigger word. In this mode, Talkie keeps the microphone open and sends transcriptions when the trigger word is detected.
  6. Done — Review your settings and start using Talkie. All settings can be changed later from the settings drawer.
Tip You do not need to configure everything during onboarding. The defaults work well for most users. You can always adjust settings later by opening the settings drawer.

Basic Usage

Voice input

There are two ways to use voice input:

  • Push-to-talk — Hold the Space key or tap the microphone button. Release to send your message.
  • Continuous listening — When enabled in settings, Talkie keeps the microphone open and listens for your trigger word.

Text input

Type your message in the input bar at the bottom of the screen and press Enter to send. Use Shift + Enter for a new line.

Theme switching

Open the settings drawer from the floating action button (bottom-right corner) to switch between the 6 available themes. Your selection is saved and persists across sessions.

Keyboard shortcuts

Shortcut Action
Space (hold) Push-to-talk
Cmd + K Open search
Enter Send message
Shift + Enter New line in input

Troubleshooting

Certificate warnings

Because Talkie uses a self-signed certificate, your browser will show a security warning on first visit. This is expected and safe for local development:

  • Chrome — Click "Advanced" then "Proceed to localhost (unsafe)".
  • Edge — Click "Advanced" then "Continue to localhost (unsafe)".

The certificate is stored at ~/.talkie/cert.pem. If you need to regenerate it, delete the file and restart Talkie.

Microphone permissions

Voice input requires microphone access over HTTPS. If the browser does not prompt for permission:

  • Verify you are accessing Talkie over https:// (not http://).
  • Check your browser's site settings and ensure microphone access is allowed for https://localhost:3443.
  • On macOS, ensure your browser has microphone permission in System Settings > Privacy & Security > Microphone.

Port conflicts

If port 3443 is already in use, set a different port with the TALKIE_PORT environment variable:

TALKIE_PORT=4443 npx talkiebot

You can also export it in your shell profile to make it permanent:

export TALKIE_PORT=4443
Still stuck? Open an issue on GitHub with your Node.js version, browser, and OS details.
Previous Documentation Next Features