Getting Started

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

Installation

{
  "mcpServers": {
    "wtb": {
      "command": "npx",
      "args": ["wtb-mcp"]
    }
  }
}

Talkie is distributed as an npm package. A single command downloads the package, starts a server, and opens your browser:

npx walkietalkiebot

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

• Downloads and installs the walkietalkiebot package from npm
• Initializes an SQLite database at ~/.wtb/wtb.db
• Starts the server on port 5173 (configurable via WTB_PORT)
• Opens your default browser to the Talkie interface

If you prefer a global install:

npm install -g walkietalkiebot
walkietalkiebot

System Requirements

The Web Speech API is used for both speech-to-text and text-to-speech. Localhost is a secure context in all browsers, so no HTTPS setup is needed. Firefox and Safari have limited or no support for the Web Speech API recognition interface.

First Launch

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

1. Database creation — An SQLite database is initialized at ~/.wtb/wtb.db with WAL mode enabled for concurrent reads.
2. Server start — The HTTP server starts on port 5173 (or the port set by WTB_PORT).
3. Browser opens — Your default browser navigates to http://localhost:5173.
4. Onboarding wizard — On your first visit, a 7-step setup wizard walks you through configuration.

Onboarding

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

1. Welcome & theme selection — Meet Talkie and learn what it does. Choose from 6 retro themes: TalkBoy, Bubble, Dial-Up, Finder, Guestbook, or 1984. Each theme completely reskins the entire interface.
2. Choose your mode — Pick between Claude Code mode (recommended, full tool use, auto-detected) and Direct API mode (uses your Anthropic API key, no tools).
3. Text-to-speech — Toggle TTS on or off. Claude's responses will be read aloud when TTS is enabled. You can pick a specific voice in settings later.
4. Sound effects — Enable or disable cassette tape sounds when recording starts and stops.
5. Wake word — Say "Hey Talkie" to start recording without touching the keyboard. Customizable in settings.
6. Continuous listening — Always listening mode — say "over" when you're done talking to send your message. No spacebar needed.
7. Done — Review a summary of your configured settings and start using Talkie. All settings can be changed later from 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

Troubleshooting

Microphone permissions

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

• Check your browser's site settings and ensure microphone access is allowed for http://localhost:5173.
• On macOS, ensure your browser has microphone permission in System Settings > Privacy & Security > Microphone.

Port conflicts

If port 5173 is already in use, set a different port with the WTB_PORT environment variable:

WTB_PORT=4443 npx walkietalkiebot

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

export WTB_PORT=4443