suzu
Try it free

Docs and FAQ

Suzu Docs

Everything about Suzu in one page: setup, the CLI your agents speak through, and answers to common questions.

or open /llms.txt

Getting started

What is Suzu?

Suzu gives your AI coding agents a voice. It is a macOS menu bar app: your agents (Claude Code, Codex, Pi, Gemini, Cursor...) tell you out loud when a task is done, when they have a question, or when they are stuck.

With Suzu Local, the local trial or an active Cloud plan, messages also appear in the capsule, a small black on-screen companion, with a message queue and a history. You reply by voice when the current agent session supports replies.

Getting started

Quickstart

  1. 1

    Launch Suzu

    Suzu lives in your menu bar. Choose a voice in Settings, then let your agents load Suzu with suzu hello.

  2. 2

    Connect your agents

    Install hooks for event sounds, then install the Suzu rule for your agent so it knows when to speak. The example below uses Codex.

  3. 3

    Hear it

    Run the test message below to hear Suzu and see the notification.

bash
suzu hooks status --json      # which agents are detected
suzu hooks install --all      # install event hooks
suzu rules install --tool codex # teach Codex to load Suzu
suzu '["done","en","my-app","codex"] Suzu is ready.' # test the voice

The suzu CLI

Make an agent speak

Every message starts with a metadata array, then the text to say. The metadata is never spoken.

bash
# suzu '["state","lang","project","agent"] message'
suzu '["done","en","my-app","claude"] Build finished, all tests pass.'
suzu '["question","en","my-app","codex"] Ready to deploy to production?'

# Optional 5th field: a voice id from `suzu voices`
suzu '["done","en","my-app","claude","<voice id>"] Task complete.'
FieldValuesRole
statecode, done, question, error, search, sleepSets the capsule state and its sound.
langen, fr, de, es, ...Language of the voice.
projectrepository nameGroups messages by project.
agentclaude, codex, pi, gemini, cursor...Shows the agent logo in the capsule.
voice (optional)id from suzu voicesPicks the voice. An unknown id falls back to the default voice.

The suzu CLI

Voices

bash
suzu voices --lang en         # list the voices, id first
suzu voice set <id>           # pin a voice for the current project

The suzu CLI

Ask a question

An agent can wait for your decision. Add + to the recommended option (green), ! to a destructive one (red), ~ to a risky one (orange). Always set --timeout.

bash
REPLY=$(suzu --ask '["question","en","my-app","codex"] Merge on main or open a PR?' --options "Open PR+,Merge~,Delete branch!" --timeout 7200)
Exit codeMeaning
0Answered: the answer is on stdout.
124No answer before the timeout.
125Dismissed: do not ask again.
10Suzu is not running: ask in your own channel.
11Suzu read the question aloud; the answer arrives in your own channel.
70Channel lost: ask again.

The suzu CLI

Cards and blips

A card shows a decision with visible context (a report, a diff, a list). A blip is a few silent words that float out of the capsule for a moment: a step done, tests green.

bash
REPLY=$(suzu card --json '{
  "agent": "codex",
  "project": "my-app",
  "lang": "en",
  "title": "Scan finished, 3 issues found",
  "body": "| Issue | Severity |\n|---|---|\n| CVE-2026-1 | high |",
  "actions": [
    {"id": "fix", "label": "Fix them", "style": "primary"},
    {"id": "skip", "label": "Ignore", "style": "danger"}
  ],
  "timeout": 7200
}')

suzu blip '["done","en","my-app","claude"] :tests: 142 tests' --eyes happy

Agent setup

Hooks, rules and souls

Hooks

suzu hooks install --all connects detected agents. suzu hooks uninstall --all restores their previous configs exactly.

Rules

suzu rules install --tool claude adds the line that makes an agent load Suzu. suzu rules status shows where it goes.

Hello

suzu hello --agent codex prints what an agent reads at the start of each session. suzu hello --status shows who loaded it.

Souls

suzu soul list shows the voice personalities. suzu soul set "speak like a pirate" sets one for this project.

bash
suzu quota --for claude       # remaining AI quota, as JSON

Agent setup

Guarantees

Never blocks

A voice message is queued instantly. The CLI never freezes your agent.

No replay storm

Old messages are not replayed after a restart.

Always visible

With capsule access enabled, the message remains visible even if sound is muted or fails.

Clean shutdown

Suzu stops cleanly and removes its socket files.

FAQ

Frequently asked questions

Which agents are supported?

suzu hooks detects Claude Code, Codex, Gemini, Pi and Cursor. Any agent that can run a shell command can speak through the suzu CLI.

Is my data private?

Local voices and local dictation run on your Mac. If you choose cloud dictation or voices, the audio or text needed for that request is sent to Soniox (dictation) or Fish Audio (voices). Cloud features require an account.

Which Mac do I need?

An Apple Silicon Mac running macOS 15 or later. Some speech features require a newer macOS version.

Do I need an account?

Not for Suzu Free. You need an account for the trial, purchases and Suzu Cloud. Sign in with Google, GitHub or a magic link: no password, ever.

How much does it cost?

Suzu Free costs nothing: the AI quota monitor, and your agents speak with Apple system voices. Suzu Local is a one-time purchase at $59, with a launch offer from $14.99 for the first 100 buyers. Suzu Cloud comes in two plans: Lite at $8 a month and Max at $20 a month, with 2 months free on yearly billing.