Iriscale
Platform
Chief Marketing AgentSEOGEO · AEO · AIOSocial Media ManagementPaid Ads Management
Industries
Healthcare & MedicalLegalHome Services & TradesProfessional & FinancialB2B & Technology
Iriscale ManagedPricingAbout
Resources
LearnBlogOpen source
  • Open source
  • MIT
  • v0.1.32
  • Claude Code
  • Codex CLI

Your coding agents tell you, by name, when they need you.

Iriscale Voice is a free, open-source plugin for Claude Code and Codex CLI. When a session finishes, gets blocked on a permission, or dies, it says so, by name, through the voice your OS already has. Zero dependencies. 30-second install. MIT.

Install in 30 secondsGitHub

Windows, macOS and Linux. One POSIX script, no runtime dependencies, no network calls, no telemetry. It speaks; it never listens.

Coding agents are at their best on long tasks: a refactor here, a test suite there, a migration in a third terminal. The bottleneck is you. You can't watch five terminals, so you either poll them and lose your focus, or forget one and it sits finished, or blocked on a yes/no, for twenty minutes.

Iriscale Voice removes the polling. You keep working in whichever session has your attention; the others speak up when, and only when, they need you. You hear which session and why, without looking, so you can finish the thought you're on and then switch. That's the whole product.

Install

Thirty seconds, no dependencies.

Pick your agent. The plugin is the best route for Claude Code. npx covers Codex CLI on any OS, and Claude Code without the plugin. Windows without Node gets a PowerShell one-liner.

Inside Claude Code, two commands:

/plugin marketplace add justbuild-it/iriscale_voice
/plugin install iriscale-voice@iriscale
Then hear it
/iriscale-voice:test

That's it: the standard preset is on. Silent on Windows? The same test command says why (Windows keeps a per-app volume for PowerShell in the Volume Mixer) and /iriscale-voice:test --fix puts it back to 100%.

Windows hooks run through Git Bash, which nearly every Claude Code install on Windows already has. Update later with /plugin marketplace update iriscale, then restart Claude Code.

Nothing is written until you ask

npm install runs no install script, and install <agent> without --apply only prints what it would write.

Every file is backed up beside itself

The installer rewrites only its own lines in your agent config and leaves your entries in place.

Uninstall reverses exactly those edits

Including restoring a notifier of your own that ours had to displace. Nothing asks for elevation.

What it says, and when

Which session, and why. Nothing else.

Each first line is spoken once. Underscores and hyphens are spoken as spaces, so name sessions like payments-api and you hear “payments api”.

finished its turn
You hear
“billing service done”, or “…done after 6 minutes” for long ones
What to do
Review it when you reach a stopping point.
finished a turn, but background agents or tasks are still running
You hear
nothing. The board shows working, waiting for 1 agent. Verbose: “…finished a step, 1 agent still running”
What to do
Nothing. It wakes itself and says “done” when the whole job is finished.
paused for a /loop or a scheduled wake-up
You hear
nothing. The board shows scheduled. Verbose: “…paused until its next wake-up”
What to do
Nothing.
is blocked on a permission prompt
You hear
“payments api is waiting for your answer to run git push origin main”, or “…to use Edit”. Anything that looks like a credential is spoken as “redacted”
What to do
It can’t continue until you answer. Switch now.
died (rate limit, billing, auth)
You hear
“data migration stopped: rate limit”
What to do
Don’t wait for it.
sat a minute with no key pressed there
You hear
“billing service is waiting for you”
What to do
The board marks it needs your review.
still needs you after a while
You hear
“payments still needs your answer, 10 minutes”. Merged when several: “still waiting: payments needs your answer, billing ready for review”
What to do
Reminders at 3 and 10 minutes for answers, 15 for review, 10 for errors, then silence. The board keeps the row.
you come back after 10 quiet minutes
You hear
“while you were away: payments needs your answer, billing ready for review”
What to do
One summary, before your prompt runs.
subagent or session end (verbose preset only)
You hear
“…sub agent done”, “…session ended”
What to do
Usually noise. Off by default.

What it will not say

  • The same line twice inside a minute: identical lines from one session are spoken once.
  • Anything on turns under 30 seconds in the standard preset, so it stays quiet while you are actively working in that session.
  • Reminders in the basic preset, or while you are typing in another session.
  • A word while your microphone is open, on Windows: it waits, and repeats itself afterwards.
The session board

See them all at once.

Speech tells you the moment something changes. The board is where you look when you come back.

  • One row per session, Claude Code and Codex alike: needs your answer, needs your review, ready, working, scheduled, reviewed, with how long it has been there and what was last said.
  • Click a row, or press its number, to bring that session’s window to the front. Windows today, Linux with wmctrl, macOS not yet. When sessions are tabs in one IDE window it raises the window and names the tab.
  • It repaints only when something changes, so it is about 5 MB of idle shell. Give it a small terminal window off to the side, or set board_autostart and it opens itself on the next event.
iriscale-voice board
Built for real desks

The three objections, answered in the code.

Open offices, dictation, calls, and terminals full of tokens. Each of these is a default, not a setting you have to find.

It stays out of your dictation

Dictating with Wispr Flow or voice typing, or on a call? On Windows it waits while any app holds the microphone, and if the mic opens mid-sentence it stops and repeats itself once the mic closes. Its words never land in your transcript. The macOS and Linux equivalents are on the roadmap.

mic_aware=true · mic_wait=30

It never reads your secrets aloud

It tells you what it is waiting on, up to 60 characters of the command, because that is what lets you decide from across the room. Anything that looks like a credential (Bearer tokens, sk- and ghp_ keys, AKIA keys, password=, user:pass@host) is spoken and logged as “redacted”. Shared office? Speak the program name only.

command_detail=program

A voice you can stand

/iriscale-voice:speaker lists the voices worth using and sets one with a spoken sample. Lines are tuned for the ear: a short pause after the session name, CamelCase tool names split, the two-character hash Claude Code appends to auto-named sessions spelled out. Anything it still mangles, you fix once.

pronounce=iriscale=eye riss scale
A typical hour

Three sessions. Two interruptions. Both worth it.

  1. 1

    Start three sessions

    /rename billing-service, /rename payments-api, /rename docs. Give each a task that will take a while.

  2. 2

    Work in docs

    “billing service done after 4 minutes”

    Four minutes later, the voice. Finish your paragraph, then go review it.

  3. 3

    While reviewing

    “payments api is waiting for your answer to run pytest”

    Tab over, press yes, tab back. Ten seconds.

  4. 4

    Then nothing

    Nothing else speaks until something actually changes.

How it works

One shell script between the hook and the speaker.

The architecture is a feature. You can read the whole thing in ten minutes, and there is nothing else to install, update, or trust.

Agent hook event

  • Stop · PermissionRequest
  • StopFailure · Notification
  • PostToolUse · SessionEnd

Claude Code and Codex CLI run a shell command per lifecycle event.

JSON on stdin

  • session_id · cwd
  • hook_event_name
  • tool_name · tool_input

Field and event aliases map other agents onto the same five events.

bin/iriscale-voice

  • resolve the session name
  • preset and gates: quiet hours, mute, minimum turn, repeat guard, mic
  • scrub, queue, record state

One POSIX script. No jq, node or python.

Your OS voice

  • Windows: System.Speech
  • macOS: say
  • Linux: spd-say, espeak; then a notification, then a bell

Non-blocking: the hook returns before the sentence ends.

283 ms
per event on Windows, down from 1,479 ms after the builtins-only rewrite
1
external process at most on the hook path; a guard test fails the suite on a second
~97
tokens per session of always-on cost inside Claude Code
0
runtime dependencies, network calls, or telemetry

Read the whole thing: bin/iriscale-voice. The hook contract it consumes is in the Claude Code hooks reference.

Why we built it

We were the slow part.

We run a lot of agents. A refactor in one terminal, a migration in another, the website in a third. The agents were never the slow part; we were, because we kept checking on them. On 14 August one of us wrote a 30-line PowerShell hook that said “billing service done”. By the end of the day it had presets. By the end of the week it worked on macOS and Linux and we could not imagine working without it. So here it is.

Engineers at Iriscale run three to five sessions at a time, across the platform, this website and the agents themselves. The plugin is what makes that a normal working day instead of a tab-switching exercise: the sessions speak up, we finish the thought we are on, then we switch. The board is where we look when we come back from lunch.

Iriscale's whole pitch is that agents do the work and people review and approve. This is that idea applied to our own engineering. The agents run; a person is interrupted only when there is something to review or approve; the tool just says when. If that sounds like how you would like to work, we are hiring.

The engineering team

Iriscale

Open roles at Iriscale

From a hook to a product

  1. Aug 14A 30-line PowerShell hook that said “billing service done”. Presets by the end of the day.
  2. Aug 15Rebuilt as a Claude Code plugin for Windows, macOS and Linux. v0.1.0 published.
  3. Aug 18Codex CLI support, one config for both agents.
  4. Aug 28The session board, with click-to-focus.
  5. Sep 10npx installer for macOS and Linux, a voice picker, microphone awareness.
  6. Nowv0.1.32: 33 releases since 15 August, CI on Ubuntu, macOS and Windows, a security page, and an outside-style audit with its fixes shipped.
Choose how chatty

Three presets, a mute switch, quiet hours.

basic

Just tell me when it’s done.

  • done
  • waiting for you

No errors, no command details, no reminders.

standardDefault

The default.

  • done
  • waiting for you
  • stopped: <reason>
  • waiting for your answer to run <command>

Quiet on turns under 30 seconds. Reminders while a session still needs you.

verbose

Tell me everything.

  • everything in standard
  • finished a step, N agents still running
  • paused until its next wake-up
  • sub agent done
  • session ended

Useful for a day, then most people go back to standard.

/iriscale-voice:preset basic
done + waiting for you. Nothing else.
/iriscale-voice:preset standard
+ errors + waiting for your answer. Quiet on turns under 30 s. (default)
/iriscale-voice:preset verbose
+ subagents, session end
/iriscale-voice:speaker
the voices worth using; :speaker "Samantha" sets one and speaks a sample
/iriscale-voice:mute
silence, stays installed. :unmute brings it back
/iriscale-voice:quiet 22-8
nothing between 10 pm and 8 am
/iriscale-voice:review-window 10
a key pressed within 10 minutes of finishing counts as reviewed
/iriscale-voice:status
what is configured
/iriscale-voice:config list
every setting: current value, default, meaning

Or edit ~/.claude/iriscale-voice.conf by hand: it is key=value lines. Every knob is documented in docs/CONFIG.md. Outside Claude Code the same thing is the iriscale-voice command.

Agents and platforms

Two verified live. Ten more mapped.

Most coding CLIs copied Claude Code's hook shape: a shell command per lifecycle event, JSON on stdin. One script plus a thin alias layer covers them, so each adapter is a small pull request.

Verified live

  • Claude Code
  • Codex CLI

Mapped, adapters welcome

  • Copilot CLI
  • Grok Build
  • Gemini CLI
  • Junie CLI
  • Cursor
  • Devin CLI
  • OpenCode / Kilo
  • Windsurf
  • Cline
  • Aider

The full matrix, with each vendor's events and what an adapter needs, is in docs/PLATFORMS.md. Zed, Warp and Roo Code have no shell hook yet, so they are out of reach until they add one.

Platform status, honestly

Windows is verified daily by the maintainers. macOS and Linux run the same script and pass CI on both, but their speech backends (say, spd-say) are tested by users rather than by us. Windows hooks need Git Bash. Reports welcome.

On the roadmap

  • A spoken one-line summary of what was done, read from the transcript.
  • Escalation when a permission prompt sits unanswered.
  • Earcons: a 200 ms tone per event type, for calls.
  • Menu-bar and tray versions of the board.
  • Microphone awareness on macOS (CoreAudio) and Linux (PulseAudio, PipeWire).
  • Adapters for the agents on the left, each a small PR.

Tracked in docs/ROADMAP.md. Numbers beyond the next release are intent, not promises; anything a user reports as broken jumps the queue.

Contribute

Small project, simple rules.

The point of every rule is that anyone can see what changed, why, and which version has it.

  • Every change is a pull request, in Conventional Commits form, with a line under Unreleased in the changelog. No direct pushes to main, maintainers included.
  • sh test/run.sh must pass, and a fix adds the check that would have caught the bug. Several guard tests exist only to stop a specific past bug from returning.
  • Patch per release: every release bumps the patch number and ships as soon as it is done. Small, frequent, visible.
  • Adding an agent is a small PR: field and event aliases, a synthetic payload test, and an install doc. A real payload captured from the agent is the one thing maintainers cannot produce for agents they do not run.
Contributing guideOpen issues@iriscale/voice on npm

The repo is its own Claude Code marketplace: /plugin marketplace add justbuild-it/iriscale_voice. Run the tests with sh test/run.sh; they use a throwaway config directory and never touch your real settings.

Latest releases

All releases
  1. v0.1.32Sep 13, 2026

    Fix false Codex permission alerts during automatic approval review (#46). Voice now announces a permission wait only when the current turn records a human re...

  2. v0.1.31Sep 12, 2026

    Fix Windows Codex hooks timing out after 10 or 30 seconds even though their foreground work completed. Background notification watchers now run without keepi...

  3. v0.1.30Sep 12, 2026

    Codex fixes from #42: Fix Windows prompt-submit "Hook failed / hook exited with code 1" errors caused by invoking cmd-style commands through PowerShell. Use...

Every entry links the PR that shipped it: CHANGELOG.md.

About Iriscale

Built by a company that runs agents for a living.

Iriscale builds AI agents that run marketing: AI search visibility, SEO, content, Google and ChatGPT ads and social, with people reviewing and approving. Iriscale Voice is what our engineers built so the agents could work while they did.

See the platform
FAQ

The questions developers ask first.

No. Everything runs on your machine. The script makes no network calls, collects no telemetry and needs no account. The only time anything is fetched is when you run an installer, which downloads the script from GitHub or npm because you asked it to. What it writes locally: a config file, an activity log rolled at 1 MB, one small state file per session and scratch files in a private directory. SECURITY.md lists every path.

SECURITY.md

No. Iriscale Voice only speaks; it never listens. Claude Code's built-in /voice command is dictation, which is a different thing, and that name collision is why every plugin command is namespaced as /iriscale-voice:something.

On Windows, no. It waits while any app has the microphone open (Wispr Flow, voice typing, a call) and, if the mic opens mid-sentence, cancels the line and repeats it once the mic closes. That is mic_aware, on by default, with mic_wait set to 30 seconds. The macOS (CoreAudio) and Linux (PulseAudio, PipeWire) equivalents are on the roadmap; until then, mute or quiet hours cover a call.

Yes. One config file covers both, and the session board lists sessions from both agents in one place. The one thing to avoid is installing the Claude Code plugin and running the npx install for Claude on the same machine, because every event would be spoken twice; the installer checks for the plugin and refuses.

The config at ~/.claude/iriscale-voice.conf, an activity log beside it, one state file per session under ~/.claude/iriscale-voice-sessions, and scratch files under a runtime directory created with mode 700. The installers add a copy of the script in a fixed directory, put it on your PATH and edit only the config of the agent you named, backing every file up beside itself first. Nothing runs with elevated rights, and nothing is written until you pass --apply.

What this software does on your machine

Whatever your operating system already has: System.Speech on Windows, say on macOS, spd-say or espeak on Linux, falling back to a desktop notification and then a bell. /iriscale-voice:speaker lists the voices worth using and sets one with a spoken sample. If it mangles a name, pronounce=word=spoken fixes it; underscores and hyphens in session names are already spoken as spaces.

The hooks run wherever the agent runs, and speech goes through that machine's speech engine. On a headless box with no engine it falls back to a desktop notification and then a terminal bell, which most terminals forward over SSH. Full speech from a remote session to your local speakers is not something it does today.

The presets decide what is said and when; quiet hours, mute lists and the minimum turn length decide when it stays silent; pronounce fixes individual words. The lines themselves live in one readable POSIX shell script, bin/iriscale-voice, so changing a phrase is a one-line edit in a fork.

bin/iriscale-voice

No. The hook path takes about 283 ms per event on Windows, spawns at most one external process, and hands speech off without blocking: a guard test fails the suite if a slow speaker holds the hook for more than two seconds. The always-on cost inside Claude Code is about 97 tokens per session.

Plugin: /plugin uninstall iriscale-voice@iriscale. npx install: npx @iriscale/voice@latest uninstall codex (or claude), which reverses exactly the edits it made and restores any notifier of your own it had to displace. Windows PowerShell install: iriscale-voice uninstall codex. Your own settings stay in place in every case.