# Suzu Docs

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

Source: https://suzuvoice.app/docs

## 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.

## Quickstart

1. **Launch Suzu**: Suzu lives in your menu bar. Choose a voice in Settings, then let your agents load Suzu with `suzu hello`.
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. **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
```

## 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.'
```

| Field | Values | Role |
| --- | --- | --- |
| state | code, done, question, error, search, sleep | Sets the capsule state and its sound. |
| lang | en, fr, de, es, ... | Language of the voice. |
| project | repository name | Groups messages by project. |
| agent | claude, codex, pi, gemini, cursor... | Shows the agent logo in the capsule. |
| voice (optional) | id from `suzu voices` | Picks the voice. An unknown id falls back to the default voice. |

## Voices

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

## 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 code | Meaning |
| --- | --- |
| 0 | Answered: the answer is on stdout. |
| 124 | No answer before the timeout. |
| 125 | Dismissed: do not ask again. |
| 10 | Suzu is not running: ask in your own channel. |
| 11 | Suzu read the question aloud; the answer arrives in your own channel. |
| 70 | Channel lost: ask again. |

## 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
```

## 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
```

## 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.

## 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.