ᓚᘏᗢ Whisker: A Pipecat Debugger

May 29, 2026 · View on GitHub

whisker

PyPI Discord

ᓚᘏᗢ Whisker: A Pipecat Debugger

Whisker is a low-level debugger for the Pipecat voice and multimodal conversational AI framework.

Pipecat is a multi-agent systems: workers spawn sub-workers, send jobs to each other, and exchange messages on a shared bus. Whisker gives you a single view over the whole system so you can see exactly what every part is doing.

With Whisker you can:

  • 🧑‍🤝‍🧑 Browse every worker and sub-worker running in your Pipecat process
  • 🗺️ Inspect the selected worker's pipeline
  • 🧰 See every job flowing between workers
  • 🚌 Follow messages on the Pipecat bus
  • 📌 Select a processor to inspect its frames
  • 🔍 Filter frames by name and direction
  • 🧵 Trace a frame's path through the pipeline
  • 💾 Save and load previous sessions

Think of Whisker as trace logging with batteries for Pipecat applications.

Whisker

🧭 Getting started

Requirements

  • Python 3.11+
  • Pipecat installed
  • Node.js 20+ (for the UI)
  • ngrok (for connecting to the hosted UI)

Install Whisker for Python

uv pip install pipecat-ai-whisker

Add Whisker to your Pipecat pipeline

Whisker is split into two pieces: a WhiskerServer that owns the WebSocket connection to the UI (and listens on the Pipecat bus for cross-worker events), and per-worker WhiskerObservers that forward frame events to the server. Add one server to your runner and an observer to every pipeline worker you want to debug.

pipeline = Pipeline(...)
worker = PipelineWorker(pipeline, ...)

whisker = WhiskerServer()
worker.add_observer(whisker.create_observer(worker))

runner = WorkerRunner()
await runner.add_workers(whisker, worker)
await runner.run()

You can also add Whisker without touching your application code by listing a setup file in the PIPECAT_SETUP_FILES environment variable. The runner picks up setup_worker_runner (called once for the runner) and each worker picks up setup_pipeline_worker (called once per pipeline worker) — both reading from the same file, so a module-level WhiskerServer is shared between them:

whisker = WhiskerServer()

async def setup_worker_runner(runner: WorkerRunner):
    await runner.add_workers(whisker)


async def setup_pipeline_worker(worker: PipelineWorker):
    worker.add_observer(whisker.create_observer(worker))

In both cases, this starts the Whisker server that the graphical UI will connect to. By default, the Whisker server runs at:

ws://localhost:9090

  1. Expose your local server with ngrok:

    ngrok http 9090

  2. Copy the ngrok URL (e.g., your-ngrok-url.ngrok.io)

  3. Open the hosted Whisker UI: https://whisker.pipecat.ai/

  4. Connect to your bot:

    • In the WebSocket URL field, enter: wss://your-ngrok-url.ngrok.io
    • Click connect

🏠 Option B: Run the UI locally

If you prefer to run the UI locally:

  1. Clone the repository:

    git clone https://github.com/pipecat-ai/whisker.git

  2. Start the UI:

    cd whisker/ui
npm install
npm run dev

  3. Connect to http://localhost:5173

The UI will automatically connect to ws://localhost:9090 by default.

💾 Saving sessions

You can save a Whisker session to a file for later replay or sharing. The on-disk format matches the live wire protocol, so any saved session loads back into the Whisker UI via Load session.

Record alongside the live server by passing file_name= to WhiskerServer:

whisker = WhiskerServer(file_name="whisker.whisk")

For a headless capture without the WebSocket server (CI jobs, scripted recordings), drop in WhiskerFile — same wiring as WhiskerServer, no port reserved:

whisker = WhiskerFile("whisker.whisk")

Custom sinks

WhiskerServer and WhiskerFile are both concrete WhiskerSinks. To stream events to a different backend (HTTP webhook, message queue, custom log format, …), subclass WhiskerSink and implement emit:

class MyCustomSink(WhiskerSink):
    async def emit(self, event: dict) -> None:
        # event is a plain dict — encode and ship it however you like.
        ...

📚 Next steps