Superwhisper for Grok

Superwhisper voice integration for Grok.

When the Grok agent finishes a turn, Superwhisper opens with the final assistant message. Answer by voice and the transcript goes back to Grok, giving you the same hands-free loop as the Claude Code, Codex, Cursor, OpenCode, and Pi integrations. Tool calls that need permission are gated the same way — approve or deny by speaking.

Installation

curl -fsSL https://superwhisper.com/install-grok.sh | bash

Or from a checkout:

./install.sh

Restart Grok after installing.

Requires Superwhisper for macOS and Grok CLI 0.2.112 or newer.

To verify:

cat ~/.grok/hooks/superwhisper.json

Events

Grok event	Superwhisper behavior
UserPromptSubmit	Dismisses any open Superwhisper prompt
PreToolUse	Opens Superwhisper with the pending tool call; your spoken answer allows or denies it. Dismissing falls through to Grok's own prompt
Stop (reason: end_turn)	Opens Superwhisper with the final message; your spoken reply continues the turn
Stop (any other reason)	Ignored — the session is closing, not finishing a turn
SessionEnd	Dismisses and cleans up session state

PreToolUse and Stop block on a spoken reply, so both use a 30-minute timeout. Grok's default is 5 seconds. Grok caps a turn at 8 stop-hook continuations, then forces the stop.

How it works

1. You start Grok on a task
2. When the agent finishes or needs permission, Superwhisper opens over your other windows
3. You reply by voice
4. The agent picks up your reply and keeps working

Why this isn't a Grok plugin

Grok discovers a plugin's hooks/hooks.json and reports it — grok inspect shows has_hooks=true and grok plugin details lists hooks under components — but the session loader never reads from it. Verified on grok 0.2.112 both as a directory install under ~/.grok/plugins/ and as a registry install via grok plugin install --trust; in both cases sessions executed zero plugin hooks. Anthropic's superpowers plugin behaves identically, so it isn't specific to this one.

~/.grok/hooks/ is always trusted and needs no folder-trust grant, so the hooks live there instead. If a later Grok build starts running plugin hooks, this collapses to the two-line installer the Codex and Claude Code integrations use.

Workspace toggle

Ask the agent to turn the integration off ("turn off superwhisper") — it uses the superwhisper skill, which flips a per-workspace flag.

Repository layout

superwhisper-grok/
├── install.sh           # Registers hooks in ~/.grok/hooks/ and the skill in ~/.grok/skills/
├── install-grok.sh      # Entry point for the curl one-liner
├── skills/superwhisper/ # Toggle skill
└── tests/e2e.sh         # Hermetic test suite (fake Grok + fake Superwhisper)

The hook logic itself ships inside the Superwhisper app (agent-hook grok). This repo carries the registration, installer, skill, and tests.

Troubleshooting

Hooks not firing after install — restart Grok, then confirm ~/.grok/hooks/superwhisper.json exists and that the wrapper it points at is executable.

Superwhisper not opening — make sure Superwhisper is running, then check the hook log:

tail -f /tmp/superwhisper-agent/debug.log

See which hooks a session actually ran — read the hook_execution records in ~/.grok/sessions/<encoded-cwd>/<session-id>/updates.jsonl, or run grok --debug-file <path>.

License

MIT