Integrations

Connect Talkie to Claude Code, the Anthropic API, MCP tools, Telegram, and manage your server.

Claude Code Mode

Claude Code mode is the default integration. Each message you send spawns a fresh claude -p CLI process, giving Claude full access to tools like file editing, bash commands, web search, and more.

The CLI is invoked with the following flags:

• --output-format stream-json — Streams structured JSON events for real-time display
• --verbose — Includes detailed tool usage information in the event stream
• --permission-mode bypassPermissions — Skips interactive permission prompts so the CLI can run non-interactively
• --no-session-persistence — Each request is a fresh one-shot process with no session state carried over

Real-time activity feed

As Claude works, Talkie displays a live activity feed showing each tool call in real-time. You can see when Claude reads a file, edits code, runs a bash command, searches the web, or uses any other tool. The activity feed shows:

• Tool icon and label — Each of 40+ tools has a unique emoji icon and human-readable label (e.g. "Reading file", "Running command")
• Category color coding — Tools are grouped into 6 categories, each with a distinct accent color
• Clean display names — MCP tools like mcp__talkie__list_conversations display as "Conversations"
• Input parameters — The arguments passed to each tool
• Status — Whether the tool call is in progress, succeeded, or failed
• Duration — How long each tool call took to complete

Tool categories

Every tool in the activity feed is color-coded by category. Each category has a subtle left-border accent and tinted background that adapts to the active theme:

Category colors are defined per-theme, so they match each theme's design language (e.g. neon accents in Guestbook, muted tones in Finder).

Image attachments

You can attach images to your messages by dragging and dropping them onto the chat area or using the image button in the input bar. Images are sent to Claude via the vision API, allowing Claude to analyze screenshots, diagrams, error messages, and other visual content.

Voice-optimized system prompt

When using voice input, Talkie includes a system prompt optimized for spoken interactions. This encourages Claude to give concise, conversational responses that work well when read aloud by the text-to-speech engine.

Direct API Mode

Direct API mode is an alternative to the Claude Code CLI. Instead of spawning a CLI process, it calls the Anthropic API directly. This mode requires an API key but offers faster response times and streaming TTS integration.

Setup

1. Set the ANTHROPIC_API_KEY environment variable, or enter your API key in the settings drawer.
2. Open the settings drawer and enable Direct API mode.

Configuration options

• Model selection — Choose between Sonnet 4, Opus, and Haiku models depending on your speed and quality needs.
• Max tokens — Configure the maximum number of tokens in Claude's response.
• Custom system prompts — Override the default system prompt with your own instructions.
• Streaming TTS — In Direct API mode, text-to-speech starts reading the response as it streams in, rather than waiting for the complete response.

MCP Server

Talkie includes an MCP (Model Context Protocol) server with 30 tools that allow Claude Code to interact with the Talkie interface. The MCP server uses stdio transport and is launched via the talkie-mcp command.

Setup

Add the following to your Claude Code MCP configuration (typically in ~/.claude/claude_desktop_config.json or your project's .mcp.json):

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

Once configured, Claude Code will have access to all 30 Talkie tools.

Available tools

IPC workflow

The MCP tools enable a bidirectional communication flow between Talkie and Claude Code:

1. User speaks or types in the Talkie UI
2. Message posted to /api/send on the server
3. MCP tool polls /api/pending to pick up the waiting message
4. Claude Code processes the message using its full tool suite
5. Response sent back via /api/respond
6. Talkie speaks the response aloud using text-to-speech

This workflow lets you use Talkie as a voice interface for Claude Code while Claude Code retains full access to file editing, bash commands, and all other tools.

Telegram Bot

Talkie includes a Telegram bot that lets you talk to Claude from any Telegram client. The bot auto-starts with the Talkie server when a bot token is configured.

Setup

1. Create a new bot via @BotFather on Telegram and copy the bot token.
2. Save the token as the TELEGRAM_BOT_TOKEN environment variable, or write it to ~/.talkie/telegram.token.
3. Start (or restart) the Talkie server. The bot will connect automatically.

# Option 1: Environment variable
export TELEGRAM_BOT_TOKEN="123456:ABC-DEF..."

# Option 2: Token file
echo "123456:ABC-DEF..." > ~/.talkie/telegram.token

Bot commands

• /start — Welcome message and introduction
• /help — Show available commands
• /conversations — List recent conversations with inline selection buttons
• /new <name> — Create a new conversation with the given name
• /current — Show the currently active conversation
• /status — Check Talkie server status

Message handling

• Text messages — Sent to Claude Code for processing. Responses are returned as Telegram messages.
• Photos — Analyzed using Claude vision. Claude describes and responds to the image content.
• Voice messages — The bot suggests using the Talkie web UI for voice input, as Telegram voice messages require server-side transcription.

Server Management

The talkie-server CLI manages the Talkie server lifecycle. It can run the server as a background process or install it as a macOS launchd daemon for automatic startup.

CLI commands

• talkie-server start [-f] — Start the server. Use -f to run in the foreground (useful for debugging). Without -f, starts as a background process.
• talkie-server stop — Stop the running server.
• talkie-server restart — Stop and restart the server.
• talkie-server status — Show server status including whether it is running, the port, launchd status, and database path.
• talkie-server logs [-f] — View server logs. Use -f to follow (tail) the log output in real-time.
• talkie-server install — Install Talkie as a macOS launchd daemon. The server will start automatically on login.
• talkie-server uninstall — Remove the launchd daemon.

Environment variables

SSL certificates

Self-signed TLS certificates are automatically generated on first launch and stored at ~/.talkie/. The files are:

• ~/.talkie/cert.pem — The self-signed certificate
• ~/.talkie/key.pem — The private key

Your browser will show a security warning on first visit because the certificate is self-signed. Accept the warning to continue. This is required because the Web Speech API needs a secure (HTTPS) context to function.