Introduction to Suzu

Suzu is a lightweight native macOS application designed to give AI terminal agents an audible voice and an expressive companion interface.

Quickstart

Launch the app

Suzu sits in your menu bar with instant local TTS readiness.

Install agent hooks

Run suzu hooks install --all to equip Claude, Pi, Codex and Cursor.

Listen & Reply

Your agent alerts you when tasks finish, and you can reply by voice with Suzu Ask.

Visual Companion Styles

Choose between three distinct companion aesthetics directly in the popover menu:

Pip (Mascot)

Animated Rive bubble with reactive facial expressions and status eyes.

3D Metal Orb

Subtle breathing metallic sphere with custom Metal vertex shaders.

Ambient Light

Minimalist click-through illumination in the screen corner.

Manual CLI Testing

Trigger test voice messages and query connected agents via command line:

bash

# Play the built-in quick test alert:
suzu demo

# Emit a custom spoken update:
suzu '["done", "en", "suzu", "claude"] Refactor finished, all tests green.'

# Check hook status across all detected agents:
suzu hooks status --json

Machine Protocol Specification

Suzu Agent Protocol (v1)

Interface specification for AI coding agents to stream real-time voice alerts, request human decisions, and interact with the macOS menu bar companion over Unix sockets.

1. CLI Payload Envelope

Agents prefix all spoken notifications with a 4-element metadata array:

bash

# Pattern: suzu '["state", "lang", "project", "agent"] message'

suzu '["code", "fr", "suzu", "claude"] Refactor du composant en cours.'
suzu '["done", "en", "web", "codex"] Build completed with 0 errors.'
suzu '["question", "en", "api", "pi"] Ready to deploy to production?'

Key	Type	Allowed Values	Description
state	string	code \| done \| question \| error \| search \| sleep	Controls mascot eye state and pre-speech sound chimes.
lang	string	fr \| en \| de \| es \| it \| pt \| zh \| ja \| ko \| ru	Language code routed to the local neural TTS model.
project	string	workspace name	Groups notifications by project workspace.
agent	string	claude \| pi \| codex \| cursor \| gemini	Identifies the calling AI agent in the notification log.

2. Interactive Decision Cards

To request human input synchronously from an AI workflow:

bash

# Option selection dialog:
REPLY=$(suzu --ask "Merge on main or open PR?" --options "Merge,PR,Diff" --timeout 120)

# Card with structured Markdown body:
REPLY=$(suzu card --json '{
  "title": "Tests completed with 1 failure",
  "body": "| Suite | Status |\n|---|---|\n| Auth | Failed |",
  "actions": [
    {"id": "fix", "label": "Fix test", "style": "primary"},
    {"id": "skip", "label": "Skip", "style": "neutral"}
  ],
  "timeout": 300
}')

Exit 0

Selected action ID on stdout

Exit 124

Timeout expired with no answer

Exit 125

Dismissed or refused by user

Exit 10

Suzu process not running

3. Sacred CLI Invariants

1. Non-blocking CLI

Voice jobs are pushed to the background queue instantly. CLI commands never freeze workflows.

2. No mass replay on reboot

Old unprocessed voice alerts are purged on startup so you are never inundated with stale audio.

3. Visual companion fallback

If audio fails or volume is muted, notification cards are guaranteed to render on screen.

4. Graceful shutdown

Always cleanly stops with SIGTERM. Dynamic socket files are cleaned up automatically.