Tutorial: Add Spoken Build Status to an AI Coding Agent

A build finishes while you are deep in another file. A quiet "Build passed" can be useful. A narrated compiler log is not.

Vois makes the useful version local: an approved, short phrase becomes a voice clip on the same machine as the coding agent. The important work is deciding what the notification may say and making sure an audio hiccup never changes the build result.

Treat this as a small Vois workflow, not as a shortcut for giving an agent access to your logs. The agent can prepare the integration, but you should approve the exact phrases, the voice, the local file location, and the final trigger.

Keep the message small and fixed

A useful coding-agent notification answers one question: did the final build step pass? Keep details on screen, where they can be read in context.

Event	Spoken phrase	Keep out of the phrase
Final build succeeds	"Build passed."	Branch names, changed files, elapsed time
Final build fails	"Build failed. Check the terminal."	Error lines, source paths, test names
No running Vois app	Nothing	A second error about the missing app

Those boundaries reduce noise and protect the voice workflow from arbitrary build output. Error text can include a file path, generated secret, or untrusted fixture. A fixed status phrase does not need any of it.

Ask the agent for a notification plan

Open Vois first. Its bundled CLI is a remote control for the running local app, not an independent hosted speech service.

Prompt your agent: "Read the Vois CLI skill at https://vois.so/skills/vois-cli/SKILL.md. Design a local spoken build-status workflow with only two allowlisted phrases: 'Build passed.' and 'Build failed. Check the terminal.' It must ignore all build output, run only after the final build or test result, rate-limit repeated alerts, and never alter the build's exit status. Show me the plan and any proposed file changes before doing anything."

Expected deliverable: a short plan that identifies the local hook location, the two fixed phrases, the chosen voice ID, the cooldown behavior, and how the integration remains best-effort.

Review and approve:

1. Confirm that no branch name, command, source path, test name, or log output can become speech text.
2. Confirm that the notification is triggered only on final success or final failure, not on every tool call or retry.
3. Review any proposed local hook or agent configuration change before it is written.
4. Require the notification to return cleanly if Vois is closed, playback fails, or the status is unknown.

Preview the phrases before enabling a hook

The agent should verify the local Vois connection and inspect the voice IDs that the app reports. Choose a library voice or an authorized clone by its exact ID, not by a guessed display name. For these short English status lines, Fast is the natural starting point.

Prompt your agent: "With the Vois app open, verify the local CLI connection and list available voices. Propose one voice for two short build-status previews. Do not install a hook or change any coding-agent configuration. Create the two disposable previews only after I approve the exact voice and phrases."

Expected deliverable: a connection report, one exact voice ID, and two local preview files labelled for success and failure.

Review and approve:

1. Confirm the connection report shows the open local app, not a remote service.
2. Review the chosen voice and approve it before generation.
3. Listen to both short previews in your normal local player.
4. Change the phrase, not the build output, if the result sounds abrupt or unclear.

Make the notification an observer

When you approve the integration, have the agent create one local hook that receives only one of two status values: success or failure. It should map each value to the approved phrase, skip unknown values, prevent overlapping runs, and enforce a sensible cooldown such as 45 seconds.

The hook should check that Vois is available before it asks for audio. If that check, generation, or playback fails, the hook should quietly finish without replacing the build's original exit status. This is the central safety property. A notification is an observer, not a dependency.

Prompt your agent: "Implement the approved local build-status hook. It may accept only success or failure, must use the two approved fixed phrases, must prevent concurrent playback and repeated alerts during the cooldown, and must never change the original build result. Show the complete diff and explain how it handles an unavailable Vois app, failed audio generation, and unknown input before writing files."

Expected deliverable: a minimal local hook and the exact configuration change that calls it after the final build or test event.

Review and approve:

1. Inspect the diff for a strict two-value allowlist and no use of build output as text-to-speech input.
2. Confirm the hook is not configured for intermediate commands, retries, or file writes.
3. Approve the local file and configuration changes.
4. Run one passing build and one failing build, then confirm the original build status remains correct even if Vois is closed.

Keep the privacy boundary narrow

This pattern sends only one of two fixed sentences to Vois, where audio is generated locally. Do not expand it with a branch label, error summary, or a "helpful" log excerpt. A branch name can contain a ticket title; a test fixture can contain credential-shaped text. The terminal already has the details.

If you later change the workflow, repeat the review. Small integrations tend to grow one exception at a time. Keeping the voice line boring is how it stays safe.

Troubleshoot without adding more noise

Symptom	Ask the agent to check
No announcement	Confirm the Vois app is open and the local connection check succeeds.
Voice lookup fails	Inspect the available voice IDs again and copy the selected ID exactly.
Audio generation fails	Run an approved short preview outside the hook so normal diagnostics remain visible.
Repeated builds stay quiet	Review the cooldown and wait for it to expire before lowering it.
The agent reports a hook error	Verify that the notification is configured after the build result is recorded and cannot replace it.

Use one clear signal, then return to the work.

Sources

• Vois CLI skill: local connection, voice IDs, generation, output modes, and exit behavior
• GNU Bash Reference Manual: set and errexit
• GNU Bash Reference Manual: trap and exit cleanup

For agent-guided local voice workflows, read Vois CLI and AI-agent integration, then Get started.

The Vois Team