Skip to content

an open-source alternative to the dots, bots and muses of the world, run an office of claude code/codex like agents on your laptop, sandboxes or anywhere, uses your existing subscriptions

feat(freeflow): voice dictation → message queue (Groq Whisper, flag-gated)

Chaitanya Giri7fb883bbdc89
diff --git a/build/entitlements.mac.plist b/build/entitlements.mac.plist
index 79a88e1e..4ee86b05 100644
--- a/build/entitlements.mac.plist
+++ b/build/entitlements.mac.plist
@@ -21,6 +21,11 @@
<!-- Persist user-granted file access (the "Documents folder" grant). -->
<key>com.apple.security.files.user-selected.read-write</key>
<true/>
+ <!-- Free Flow voice dictation records the mic via getUserMedia. Under the
+ hardened runtime this resource-access entitlement is required for mic
+ capture; it is inert unless the user enables Free Flow and records. -->
+ <key>com.apple.security.device.audio-input</key>
+ <true/>
<!-- Child processes inherit the parent's sandbox/TCC context (no-op outside
the sandbox, harmless to include for inherited child entitlements). -->
<key>com.apple.security.inherit</key>
diff --git a/electron-builder.yml b/electron-builder.yml
index 93b1e493..baee4201 100644
--- a/electron-builder.yml
+++ b/electron-builder.yml
@@ -46,6 +46,8 @@ mac:
NSDownloadsFolderUsageDescription: "Munder Difflin's agents may work on projects located in your Downloads."
NSRemovableVolumesUsageDescription: "Munder Difflin's agents may work on projects located on external volumes."
NSNetworkVolumesUsageDescription: "Munder Difflin's agents may work on projects located on network volumes."
+ # Free Flow voice dictation records the microphone (opt-in; off by default).
+ NSMicrophoneUsageDescription: "Munder Difflin records your voice only when you use Free Flow dictation, then sends it to Groq to transcribe into the message queue."
# Hardened runtime + entitlements so the spawned `claude` agents inherit this
# app's TCC responsibility (one grant covers them all) and node-pty can load.
hardenedRuntime: true
diff --git a/src/main/config.ts b/src/main/config.ts
index 8b11c83e..f2142958 100644
--- a/src/main/config.ts
+++ b/src/main/config.ts
@@ -153,6 +153,21 @@ export interface HarnessConfig {
/** Local HTTP port the webhook server binds to (default 3847). */
slackPort?: number;
+ // ─── Free Flow (voice dictation → message queue) ───────────────────────────
+ /** Master toggle for Free Flow push-to-talk dictation. Default OFF: with it off
+ * the composer shows no mic button, no getUserMedia runs, and no Groq call is
+ * ever made (zero behavior change). */
+ freeflowEnabled?: boolean;
+ /** User-pasted Groq API key (the user supplies their own free key). Used ONLY in
+ * the main process for the Groq STT call; NEVER logged, and never crosses IPC
+ * for the request. Treated like `slackBotToken`. */
+ groqApiKey?: string;
+ /** Groq Whisper model id. Default 'whisper-large-v3-turbo' (fast, multilingual). */
+ freeflowModel?: string;
+ /** Electron accelerator for the global push-to-talk TOGGLE hotkey (entry point
+ * B). Registered only while Free Flow is enabled. Default 'Control+Alt+D'. */
+ freeflowHotkey?: string;
+
// ─── Generic inbound webhook + status API ──────────────────────────────────
/** Master toggle for the generic webhook HTTP API (POST → work, GET → status). */
webhookEnabled?: boolean;
@@ -194,6 +209,10 @@ const DEFAULTS: HarnessConfig = {
slackBotToken: undefined,
slackChannelId: undefined,
slackPort: undefined,
+ freeflowEnabled: false,
+ groqApiKey: undefined,
+ freeflowModel: 'whisper-large-v3-turbo',
+ freeflowHotkey: 'Control+Alt+D',
webhookEnabled: false,
webhookSecret: undefined,
webhookPort: undefined,
diff --git a/src/main/freeflow.ts b/src/main/freeflow.ts
new file mode 100644
index 00000000..dd954170
--- /dev/null
+++ b/src/main/freeflow.ts
@@ -0,0 +1,132 @@
+/**
+ * Free Flow — Groq Whisper speech-to-text, run from the Electron MAIN process.
+ *
+ * The renderer captures mic audio (getUserMedia → MediaRecorder) and hands the
+ * raw bytes here over IPC; this module does the multipart upload to Groq's
+ * OpenAI-compatible transcription endpoint and returns the transcript. Doing the
+ * HTTP call in main (like `slack.ts` / `webhook.ts`) keeps the user's Groq key out
+ * of the renderer and dodges CORS.
+ *
+ * Electron 32 bundles Node 20, so the global `fetch` + `FormData` + `Blob`
+ * (undici) are available here — no extra dependency and no hand-rolled multipart.
+ *
+ * The API key is passed in by the caller (it lives in main's config), is used
+ * ONLY for the Authorization header, and is NEVER logged.
+ *
+ * Deliberately free of any `electron` import so it can be unit-/smoke-tested as a
+ * plain Node module.
+ */
+
+/** Groq's OpenAI-compatible transcription endpoint. */
+const GROQ_TRANSCRIBE_URL = 'https://api.groq.com/openai/v1/audio/transcriptions';
+/** Default model — fast, multilingual; ~216× real-time. The other option is the
+ * higher-accuracy `whisper-large-v3`. */
+export const DEFAULT_GROQ_MODEL = 'whisper-large-v3-turbo';
+/** Groq free-tier upload cap is 25 MB; reject larger payloads before we spend a
+ * network round-trip (our clips are seconds long / tens of KB in practice). */
+const MAX_AUDIO_BYTES = 25 * 1024 * 1024;
+/** Don't let a hung request wedge the feature — bound the call. */
+const REQUEST_TIMEOUT_MS = 60_000;
+
+export interface TranscribeOptions {
+ /** User's Groq API key. Used only for the Authorization header; never logged. */
+ apiKey: string;
+ /** Raw audio bytes captured in the renderer (e.g. webm/opus). */
+ audio: ArrayBuffer | Uint8Array | Buffer;
+ /** MIME type of `audio` (e.g. 'audio/webm'). Defaults to 'audio/webm'. */
+ mimeType?: string;
+ /** Upload filename (Groq infers format from the extension). Defaults to a webm name. */
+ filename?: string;
+ /** Groq model id. Defaults to DEFAULT_GROQ_MODEL. */
+ model?: string;
+ /** Optional ISO-639-1 language hint to improve accuracy/latency. */
+ language?: string;
+}
+
+export interface TranscribeResult {
+ ok: boolean;
+ text?: string;
+ error?: string;
+}
+
+/**
+ * Transcribe a single audio clip via Groq Whisper. Resolves `{ ok, text }` on
+ * success or `{ ok: false, error }` otherwise. Never throws; never logs the key.
+ */
+export async function transcribeWithGroq(opts: TranscribeOptions): Promise<TranscribeResult> {
+ if (!opts.apiKey) return { ok: false, error: 'missing Groq API key' };
+
+ const bytes = toUint8Array(opts.audio);
+ if (bytes.byteLength === 0) return { ok: false, error: 'empty audio' };
+ if (bytes.byteLength > MAX_AUDIO_BYTES) {
+ return { ok: false, error: 'audio too large (Groq free-tier cap is 25 MB)' };
+ }
+
+ const mimeType = opts.mimeType || 'audio/webm';
+ const filename = opts.filename || 'dictation.webm';
+ const model = opts.model || DEFAULT_GROQ_MODEL;
+
+ const form = new FormData();
+ form.append('model', model);
+ // `response_format=text` returns the bare transcript, but JSON is more robust to
+ // parse defensively; we ask for json and read `.text`.
+ form.append('response_format', 'json');
+ if (opts.language) form.append('language', opts.language);
+ form.append('file', new Blob([toArrayBuffer(bytes)], { type: mimeType }), filename);
+
+ const controller = new AbortController();
+ const timer = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+ try {
+ const res = await fetch(GROQ_TRANSCRIBE_URL, {
+ method: 'POST',
+ headers: { Authorization: `Bearer ${opts.apiKey}` },
+ body: form,
+ signal: controller.signal
+ });
+ const raw = await res.text();
+ if (!res.ok) {
+ // Surface Groq's error message (NOT the key) — e.g. 401 invalid_api_key,
+ // 413 too large, 429 rate limited. Keep it short.
+ return { ok: false, error: `Groq ${res.status}: ${extractError(raw) || res.statusText}` };
+ }
+ let text = '';
+ try {
+ const json = JSON.parse(raw) as { text?: unknown };
+ text = typeof json.text === 'string' ? json.text.trim() : '';
+ } catch {
+ // response_format fallback: a bare-text body.
+ text = raw.trim();
+ }
+ if (!text) return { ok: false, error: 'no speech detected' };
+ return { ok: true, text };
+ } catch (e) {
+ const aborted = e instanceof Error && e.name === 'AbortError';
+ return { ok: false, error: aborted ? 'transcription timed out' : errMsg(e) };
+ } finally {
+ clearTimeout(timer);
+ }
+}
+
+/** Pull a human-readable message out of Groq's JSON error envelope, if present. */
+function extractError(raw: string): string {
+ try {
+ const j = JSON.parse(raw) as { error?: { message?: string } | string };
+ if (typeof j.error === 'string') return j.error;
+ if (j.error && typeof j.error.message === 'string') return j.error.message;
+ } catch { /* not json */ }
+ return '';
+}
+
+function toUint8Array(audio: ArrayBuffer | Uint8Array | Buffer): Uint8Array {
+ if (audio instanceof Uint8Array) return audio; // Buffer is a Uint8Array subclass
+ return new Uint8Array(audio);
+}
+
+/** Blob wants an ArrayBuffer-backed view; copy out a clean ArrayBuffer slice. */
+function toArrayBuffer(bytes: Uint8Array): ArrayBuffer {
+ return bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength) as ArrayBuffer;
+}
+
+function errMsg(e: unknown): string {
+ return e instanceof Error ? e.message : String(e);
+}
diff --git a/src/main/index.ts b/src/main/index.ts
index 793ca570..06e675b7 100644
--- a/src/main/index.ts
+++ b/src/main/index.ts
@@ -1,4 +1,4 @@
-import { app, BrowserWindow, clipboard, dialog, ipcMain, powerSaveBlocker, screen, shell, Notification } from 'electron';
+import { app, BrowserWindow, clipboard, dialog, globalShortcut, ipcMain, powerSaveBlocker, screen, shell, Notification } from 'electron';
import { spawn } from 'node:child_process';
import { rmSync, existsSync, readFileSync, readdirSync, statSync, cpSync, writeFileSync, unlinkSync } from 'node:fs';
import { randomBytes, createHash, timingSafeEqual } from 'node:crypto';
@@ -24,6 +24,7 @@ import { readAgentUsage, readContextTokens } from './transcript';
import { listIssues, listCIRuns } from './github';
import { SlackWebhookServer, SlackReplyServer, postSlackReply } from './slack';
import { WebhookServer, type WebhookInbound, type WebhookTaskStatus } from './webhook';
+import { transcribeWithGroq, DEFAULT_GROQ_MODEL } from './freeflow';
import { TelemetryCollector } from './telemetry';
import { ControlRegistry } from './control';
import { ClosingTimeController } from './closingTime';
@@ -929,6 +930,26 @@ function createWindow(): void {
mainWindow = win;
+ // Permission gate for the renderer (our own trusted, local content). The only
+ // permission we constrain is microphone capture (Free Flow): it's allowed ONLY
+ // while Free Flow is enabled, so a disabled flag means zero mic access even at
+ // the Electron layer. Every other permission keeps the app's prior permissive
+ // behavior (e.g. clipboard for xterm/editor copy must keep working).
+ const ses = win.webContents.session;
+ ses.setPermissionRequestHandler((_wc, permission, callback, details) => {
+ if (permission === 'media') {
+ const mediaTypes = details && 'mediaTypes' in details ? details.mediaTypes : undefined;
+ const wantsAudio = !mediaTypes || mediaTypes.includes('audio');
+ callback(readConfig().freeflowEnabled === true && wantsAudio);
+ return;
+ }
+ callback(true);
+ });
+ ses.setPermissionCheckHandler((_wc, permission) => {
+ if (permission === 'media') return readConfig().freeflowEnabled === true;
+ return true;
+ });
+
// Persist geometry as the user drags/resizes (debounced) and on close. Skip
// while maximized/minimized so a restore doesn't save the fullscreen rect.
const saveBounds = debounce(() => {
@@ -1598,6 +1619,74 @@ ipcMain.handle('webhook:setConfig', (_evt, patch: unknown) => {
return { ok: true };
});
+// ─── IPC: Free Flow (voice dictation → message queue) ────────────────────────
+/** The global push-to-talk hotkey currently registered with the OS, or null when
+ * Free Flow is disabled / has no hotkey. Tracked so we unregister exactly ours. */
+let freeflowHotkey: string | null = null;
+
+/** Register (or re-register) the global push-to-talk TOGGLE hotkey from config.
+ * Only registers while Free Flow is enabled and a hotkey is set; on trigger it
+ * pushes `freeflow:hotkey` to the renderer, which toggles recording for the
+ * focused agent. NOTE: Electron globalShortcut can't capture the macOS Fn key
+ * (electron#16714) nor a bare modifier, so this is a real accelerator toggle —
+ * the documented v1 fallback for the native-Fn gesture. Best-effort: a failed or
+ * already-taken accelerator is logged, never fatal. */
+function reconcileFreeflowHotkey(): void {
+ // Tear down whatever we previously held.
+ if (freeflowHotkey) {
+ try { globalShortcut.unregister(freeflowHotkey); } catch { /* noop */ }
+ freeflowHotkey = null;
+ }
+ const cfg = readConfig();
+ if (!cfg.freeflowEnabled) return;
+ const accel = (cfg.freeflowHotkey ?? '').trim();
+ if (!accel) return;
+ try {
+ const ok = globalShortcut.register(accel, () => {
+ try { liveWebContents()?.send('freeflow:hotkey'); } catch { /* window gone */ }
+ });
+ if (ok) freeflowHotkey = accel;
+ else console.error('[freeflow] hotkey already in use or invalid:', accel);
+ } catch (e) {
+ console.error('[freeflow] could not register hotkey', accel, '-', e instanceof Error ? e.message : e);
+ }
+}
+
+ipcMain.handle('freeflow:setConfig', (_evt, patch: unknown) => {
+ const p = (patch ?? {}) as { enabled?: unknown; apiKey?: unknown; model?: unknown; hotkey?: unknown };
+ const next: Partial<HarnessConfig> = {};
+ if (typeof p.enabled === 'boolean') next.freeflowEnabled = p.enabled;
+ // Trim string fields; an emptied key/hotkey clears back to undefined.
+ if (typeof p.apiKey === 'string') next.groqApiKey = p.apiKey.trim() || undefined;
+ if (typeof p.model === 'string') next.freeflowModel = p.model.trim() || DEFAULT_GROQ_MODEL;
+ if (typeof p.hotkey === 'string') next.freeflowHotkey = p.hotkey.trim() || undefined;
+ writeConfig(next);
+ // Re-arm (or tear down) the global hotkey to match the new state.
+ reconcileFreeflowHotkey();
+ return { ok: true };
+});
+
+/** Transcribe one captured audio clip via Groq. Gated on the flag + a key being
+ * present, so a disabled feature can NEVER reach the network. The Groq key stays
+ * in main — only the audio bytes cross IPC inbound and the transcript outbound. */
+ipcMain.handle('freeflow:transcribe', async (_evt, arg: unknown) => {
+ const cfg = readConfig();
+ if (!cfg.freeflowEnabled) return { ok: false, error: 'Free Flow is disabled' };
+ if (!cfg.groqApiKey) return { ok: false, error: 'no Groq API key set' };
+ const a = (arg ?? {}) as { audio?: unknown; mimeType?: unknown; filename?: unknown; language?: unknown };
+ if (!(a.audio instanceof ArrayBuffer) && !(a.audio instanceof Uint8Array)) {
+ return { ok: false, error: 'no audio' };
+ }
+ return transcribeWithGroq({
+ apiKey: cfg.groqApiKey,
+ audio: a.audio,
+ mimeType: typeof a.mimeType === 'string' ? a.mimeType : undefined,
+ filename: typeof a.filename === 'string' ? a.filename : undefined,
+ model: cfg.freeflowModel || DEFAULT_GROQ_MODEL,
+ language: typeof a.language === 'string' && a.language ? a.language : undefined
+ });
+});
+
/** Start every hive-bound background service against the current harnessHome.
* Called on boot, and again to recover in place if a folder-change copy fails
* (config:changeHome tears these down before copying). No-op without a home. */
@@ -1660,6 +1749,8 @@ app.whenReady().then(() => {
else console.log('[webhook] listening', r.url ? `(tunnel: ${r.url})` : '(no tunnel)');
});
}
+ // Arm the Free Flow global push-to-talk hotkey when enabled (entry point B).
+ reconcileFreeflowHotkey();
app.on('activate', () => {
if (BrowserWindow.getAllWindows().length === 0) createWindow();
});
@@ -1684,3 +1775,9 @@ app.on('window-all-closed', () => {
app.quit();
}
});
+
+// Release the Free Flow global hotkey on quit so it never lingers past the app.
+app.on('will-quit', () => {
+ try { globalShortcut.unregisterAll(); } catch { /* noop */ }
+ freeflowHotkey = null;
+});
diff --git a/src/preload/index.ts b/src/preload/index.ts
index 4430eda1..16409e79 100644
--- a/src/preload/index.ts
+++ b/src/preload/index.ts
@@ -162,6 +162,12 @@ export interface HarnessConfig {
webhookEnabled?: boolean;
webhookSecret?: string;
webhookPort?: number;
+ /** Free Flow voice dictation — master flag (default off), user Groq key, model,
+ * and the global push-to-talk hotkey accelerator. */
+ freeflowEnabled?: boolean;
+ groqApiKey?: string;
+ freeflowModel?: string;
+ freeflowHotkey?: string;
costCapUsd?: number;
costCapTokens?: number;
agentTokenCaps?: Record<string, number>;
@@ -652,7 +658,28 @@ const api = {
webhookSetConfig: (patch: {
secret?: string; port?: number; enabled?: boolean;
}): Promise<{ ok: boolean }> =>
- ipcRenderer.invoke('webhook:setConfig', patch)
+ ipcRenderer.invoke('webhook:setConfig', patch),
+
+ // ─── Free Flow (voice dictation → message queue) ─────────────────────────────
+ /** Persist Free Flow settings (flag / Groq key / model / hotkey) and re-arm the
+ * global push-to-talk hotkey to match. The Groq key is stored in main config. */
+ freeflowSetConfig: (patch: {
+ enabled?: boolean; apiKey?: string; model?: string; hotkey?: string;
+ }): Promise<{ ok: boolean }> =>
+ ipcRenderer.invoke('freeflow:setConfig', patch),
+ /** Transcribe one captured audio clip via Groq (the key stays in main; only the
+ * audio bytes go in and the transcript comes back). Gated on the flag + a key. */
+ freeflowTranscribe: (arg: {
+ audio: ArrayBuffer | Uint8Array; mimeType?: string; filename?: string; language?: string;
+ }): Promise<{ ok: boolean; text?: string; error?: string }> =>
+ ipcRenderer.invoke('freeflow:transcribe', arg),
+ /** Subscribe to the global push-to-talk hotkey (entry point B); returns an
+ * unsubscribe fn. Fires each time the user presses the configured accelerator. */
+ onFreeflowHotkey: (cb: () => void): (() => void) => {
+ const listener = (): void => cb();
+ ipcRenderer.on('freeflow:hotkey', listener);
+ return () => ipcRenderer.removeListener('freeflow:hotkey', listener);
+ }
};
contextBridge.exposeInMainWorld('cth', api);
diff --git a/src/renderer/src/App.tsx b/src/renderer/src/App.tsx
index 29da7c3e..ad18e759 100644
--- a/src/renderer/src/App.tsx
+++ b/src/renderer/src/App.tsx
@@ -20,6 +20,7 @@ import { acquireTerminal } from '@/components/terminalPool';
import { FullscreenTerminal } from '@/components/FullscreenTerminal';
import { TaskDetailOverlay } from '@/components/TaskDetailOverlay';
import { FullscreenFileEditor } from '@/components/FullscreenFileEditor';
+import { freeflowRecorder } from '@/freeflow/recorder';
import brandLogo from '@brand/logo.png?url';
// Injected at build time from package.json (see electron.vite.config.ts).
@@ -46,10 +47,25 @@ export function App() {
// Initial config load
useEffect(() => {
let cancelled = false;
- window.cth.getConfig().then(c => { if (!cancelled) setConfig(c); });
+ window.cth.getConfig().then(c => {
+ if (cancelled) return;
+ setConfig(c);
+ // Mirror the Free Flow flag into the store so the composer mic button shows
+ // only when enabled (Settings keeps this in sync on save).
+ useStore.getState().setFreeflowEnabled(!!c.freeflowEnabled);
+ });
return () => { cancelled = true; };
}, []);
+ // Free Flow entry point B — the global push-to-talk hotkey. Main fires this
+ // (only while Free Flow is enabled); toggle dictation for whichever agent the
+ // user is currently viewing (fullscreen tab wins, else the selected agent).
+ useEffect(() => window.cth.onFreeflowHotkey(() => {
+ const s = useStore.getState();
+ const target = s.fullscreenAgentId ?? s.selectedId;
+ if (target) freeflowRecorder.toggle(target);
+ }), []);
+
// Quit warning subscription
useEffect(() => window.cth.onCloseRequested((info) => setQuitWarn(info)), []);
diff --git a/src/renderer/src/components/Icon.tsx b/src/renderer/src/components/Icon.tsx
index 1a98f083..61eaeaea 100644
--- a/src/renderer/src/components/Icon.tsx
+++ b/src/renderer/src/components/Icon.tsx
@@ -6,7 +6,7 @@ import { CSSProperties } from 'react';
export type IconName =
| 'gear' | 'plus' | 'x' | 'check' | 'arrow-right' | 'pause' | 'play'
| 'bell' | 'folder' | 'terminal' | 'code' | 'web' | 'mcp' | 'sparkle'
- | 'expand' | 'minimize' | 'clock';
+ | 'expand' | 'minimize' | 'clock' | 'mic';
interface IconDef {
ink: string; // primary color path d
@@ -87,6 +87,11 @@ const paths: Record<IconName, IconDef> = {
clock: {
accentColor: 'var(--cth-lemon)',
ink: 'M5 1h6v1h2v2h1v2h1v4h-1v2h-1v2h-2v1H5v-1H3v-2H2V8H1V6h1V4h1V2h2V1zm0 2H4v1H3v2H2v4h1v2h1v1h1v1h6v-1h1v-1h1v-2h1V6h-1V4h-1V3h-1V2H5v1zm2 1h2v4h2v1h1v1h-1v1h-1v-1H9v1H7V4z'
+ },
+ // Microphone: a solid capsule head, an open cradle, a stem, and a base.
+ mic: {
+ accentColor: 'var(--cth-coral)',
+ ink: 'M6 2h4v7H6V2z M4 9h1v2H4z M11 9h1v2h-1z M4 11h8v1H4z M7 12h2v2H7z M5 14h6v1H5z'
}
};
diff --git a/src/renderer/src/components/MessageQueueComposer.tsx b/src/renderer/src/components/MessageQueueComposer.tsx
index cfb118e1..f67b3b11 100644
--- a/src/renderer/src/components/MessageQueueComposer.tsx
+++ b/src/renderer/src/components/MessageQueueComposer.tsx
@@ -2,6 +2,7 @@ import { KeyboardEvent } from 'react';
import { PixelButton } from './PixelButton';
import { Icon } from './Icon';
import { useStore, type Agent, type QueuedMessage } from '@/store/store';
+import { freeflowRecorder, useFreeflow } from '@/freeflow/recorder';
const EMPTY_QUEUE: QueuedMessage[] = [];
@@ -26,6 +27,22 @@ export function MessageQueueComposer({ agent }: MessageQueueComposerProps) {
const setDraft = useStore((s) => s.setDraft);
const setText = (t: string) => setDraft(agent.id, t);
+ // Free Flow voice dictation (entry point A). The mic button shows only when the
+ // feature is enabled in Settings; a transcript is appended to this draft for
+ // review before sending (never auto-sent).
+ const freeflowEnabled = useStore((s) => s.freeflowEnabled);
+ const ff = useFreeflow();
+ const ffMine = ff.targetAgentId === agent.id;
+ const ffHint = !freeflowEnabled
+ ? null
+ : ffMine && ff.status === 'recording'
+ ? '● recording — click stop to transcribe'
+ : ffMine && ff.status === 'transcribing'
+ ? 'transcribing…'
+ : ff.error && (ffMine || ff.targetAgentId === null)
+ ? `voice: ${ff.error}`
+ : null;
+
const idle = agent.status === 'idle';
const queueIt = () => {
@@ -137,6 +154,15 @@ export function MessageQueueComposer({ agent }: MessageQueueComposerProps) {
</div>
)}
+ {/* Free Flow recording / transcription status (entry point A) */}
+ {ffHint && (
+ <span style={{
+ fontSize: 12, lineHeight: '16px',
+ color: ff.error && !(ffMine && ff.status !== 'idle') ? 'var(--cth-coral)' : 'var(--cth-ink-500)',
+ whiteSpace: 'nowrap', overflow: 'hidden', textOverflow: 'ellipsis'
+ }}>{ffHint}</span>
+ )}
+
{/* Composer */}
<div style={{ display: 'flex', gap: 6, alignItems: 'flex-end' }}>
<textarea
@@ -158,12 +184,51 @@ export function MessageQueueComposer({ agent }: MessageQueueComposerProps) {
outline: 'none'
}}
/>
- <PixelButton variant="primary" size="md" onClick={queueIt} disabled={!text.trim()}>
- <span style={{ display: 'inline-flex', gap: 6, alignItems: 'center' }}>
- send <Icon name="arrow-right" />
- </span>
- </PixelButton>
+ {/* Free Flow mic button sits directly ABOVE Send (only when enabled). */}
+ <div style={{ display: 'flex', flexDirection: 'column', gap: 6, alignItems: 'stretch' }}>
+ {freeflowEnabled && <FreeFlowButton agentId={agent.id} />}
+ <PixelButton variant="primary" size="md" onClick={queueIt} disabled={!text.trim()}>
+ <span style={{ display: 'inline-flex', gap: 6, alignItems: 'center' }}>
+ send <Icon name="arrow-right" />
+ </span>
+ </PixelButton>
+ </div>
</div>
</div>
);
}
+
+/**
+ * Push-to-talk button for the queue composer. Click to start recording, click
+ * again to stop → transcribe → the text is appended to this agent's draft. While
+ * another agent is mid-dictation it's disabled (one shared recorder). The actual
+ * capture + Groq call live in the freeflow recorder singleton.
+ */
+function FreeFlowButton({ agentId }: { agentId: string }) {
+ const ff = useFreeflow();
+ const mine = ff.targetAgentId === agentId;
+ const recording = ff.status === 'recording' && mine;
+ const transcribing = ff.status === 'transcribing' && mine;
+ // Block while another agent's clip is recording/uploading (single recorder).
+ const busyElsewhere = ff.status !== 'idle' && !mine;
+ return (
+ <PixelButton
+ variant={recording ? 'destructive' : 'secondary'}
+ size="md"
+ onClick={() => freeflowRecorder.toggle(agentId)}
+ disabled={transcribing || busyElsewhere}
+ >
+ <span
+ title={
+ recording ? 'Stop & transcribe'
+ : transcribing ? 'Transcribing…'
+ : 'Free Flow — dictate into the queue (push to talk)'
+ }
+ style={{ display: 'inline-flex', gap: 6, alignItems: 'center' }}
+ >
+ <Icon name="mic" />
+ {transcribing ? '…' : recording ? 'stop' : 'voice'}
+ </span>
+ </PixelButton>
+ );
+}
diff --git a/src/renderer/src/components/SettingsModal.tsx b/src/renderer/src/components/SettingsModal.tsx
index 8d5533bc..ce5e3f19 100644
--- a/src/renderer/src/components/SettingsModal.tsx
+++ b/src/renderer/src/components/SettingsModal.tsx
@@ -1,5 +1,6 @@
import { useState, useEffect, type CSSProperties } from 'react';
import type { HarnessConfig } from '@/store/config';
+import { useStore } from '@/store/store';
import { PixelPanel } from './PixelPanel';
import { PixelButton } from './PixelButton';
import { Icon } from './Icon';
@@ -193,6 +194,16 @@ export function SettingsModal({ config, onClose }: SettingsModalProps) {
const [showWebhookSecret, setShowWebhookSecret] = useState(false);
const [showWebhookHelp, setShowWebhookHelp] = useState(false);
+ // --- Free Flow (voice dictation → message queue) ---
+ const setFreeflowEnabledStore = useStore((s) => s.setFreeflowEnabled);
+ const [freeflowEnabled, setFreeflowEnabled] = useState(slackCfg.freeflowEnabled ?? false);
+ const [groqKey, setGroqKey] = useState(slackCfg.groqApiKey ?? '');
+ const [freeflowModel, setFreeflowModel] = useState(slackCfg.freeflowModel ?? 'whisper-large-v3-turbo');
+ const [freeflowHotkey, setFreeflowHotkey] = useState(slackCfg.freeflowHotkey ?? 'Control+Alt+D');
+ const [showGroqKey, setShowGroqKey] = useState(false);
+ const [freeflowBusy, setFreeflowBusy] = useState(false);
+ const [freeflowNote, setFreeflowNote] = useState('');
+
// Re-seed every editable field from the on-disk config when the modal opens.
// App's `config` prop is loaded once and never refreshed after a save, so
// without this the saved budget / velocity / slack values show blank on reopen.
@@ -212,6 +223,10 @@ export function SettingsModal({ config, onClose }: SettingsModalProps) {
setWebhookEnabled(cc.webhookEnabled ?? false);
setWebhookSecret(cc.webhookSecret ?? '');
setWebhookPort(String(cc.webhookPort ?? 3849));
+ setFreeflowEnabled(cc.freeflowEnabled ?? false);
+ setGroqKey(cc.groqApiKey ?? '');
+ setFreeflowModel(cc.freeflowModel ?? 'whisper-large-v3-turbo');
+ setFreeflowHotkey(cc.freeflowHotkey ?? 'Control+Alt+D');
}).catch(() => { /* keep prop-seeded values */ });
// Hydrate live connection state + the persisted Request URL: the
// tunnel URL lives in main, so reopening Settings while connected re-shows it.
@@ -333,6 +348,34 @@ export function SettingsModal({ config, onClose }: SettingsModalProps) {
const copyWebhookSecret = () => { void window.cth.copyToClipboard(webhookSecret); };
const copyTunnel = () => { void window.cth.copyToClipboard(tunnelUrl); };
+ // --- Free Flow handlers ---
+ /** Persist Free Flow settings; main re-arms the global hotkey. Also mirror the
+ * flag into the store so the composer mic button appears/disappears live. */
+ const saveFreeflow = async (enabledOverride?: boolean) => {
+ const enabled = enabledOverride ?? freeflowEnabled;
+ setFreeflowBusy(true); setFreeflowNote('');
+ try {
+ await window.cth.freeflowSetConfig({
+ enabled,
+ apiKey: groqKey,
+ model: freeflowModel.trim() || 'whisper-large-v3-turbo',
+ hotkey: freeflowHotkey
+ });
+ setFreeflowEnabledStore(enabled);
+ setFreeflowNote('saved');
+ } catch (e) {
+ setFreeflowNote(e instanceof Error ? e.message : String(e));
+ } finally { setFreeflowBusy(false); }
+ };
+
+ /** Toggle on/off and persist immediately so the change takes effect (and the
+ * global hotkey arms/disarms) without a separate Save click. */
+ const toggleFreeflow = () => {
+ const next = !freeflowEnabled;
+ setFreeflowEnabled(next);
+ void saveFreeflow(next);
+ };
+
const reset = async () => {
setBusy(true);
clearLocalState();
@@ -955,6 +998,99 @@ export function SettingsModal({ config, onClose }: SettingsModalProps) {
</div>
)}
</div>
+
+ <div style={{ height: 2, background: 'var(--cth-ink-300)' }} />
+
+ {/* Free Flow (voice dictation) */}
+ <div style={{ display: 'flex', flexDirection: 'column', gap: 10 }}>
+ <div style={{
+ fontFamily: 'var(--cth-font-display)', fontSize: 8, lineHeight: '12px',
+ color: 'var(--cth-ink-500)', textTransform: 'uppercase', marginBottom: 2
+ }}>
+ Free Flow
+ </div>
+ <div style={{ display: 'flex', alignItems: 'center', justifyContent: 'space-between', gap: 12 }}>
+ <div style={{ display: 'flex', flexDirection: 'column', gap: 2 }}>
+ <span style={{ fontSize: 14, lineHeight: '20px', color: 'var(--cth-ink-900)' }}>
+ Free Flow (voice dictation)
+ </span>
+ <span style={{ fontSize: 12, lineHeight: '16px', color: 'var(--cth-ink-500)' }}>
+ Push-to-talk dictation: speak, and Groq Whisper drops the text into the queue composer.
+ </span>
+ </div>
+ <PixelButton
+ variant={freeflowEnabled ? 'primary' : 'secondary'}
+ size="sm"
+ onClick={toggleFreeflow}
+ disabled={freeflowBusy}
+ >
+ {freeflowEnabled ? 'on' : 'off'}
+ </PixelButton>
+ </div>
+
+ {freeflowEnabled && (
+ <div style={{ display: 'flex', flexDirection: 'column', gap: 10 }}>
+ {/* Groq API key — stored in main config, used only there. */}
+ <label style={{ display: 'flex', flexDirection: 'column', gap: 4 }}>
+ <span style={slackLabelStyle}>Groq API key</span>
+ <div style={{ display: 'flex', gap: 6 }}>
+ <input
+ type={showGroqKey ? 'text' : 'password'}
+ value={groqKey}
+ onChange={(e) => setGroqKey(e.target.value)}
+ placeholder="gsk_... (get a free key at console.groq.com)"
+ style={{ ...slackInputStyle, fontFamily: 'var(--cth-font-mono)' }}
+ />
+ <PixelButton variant="secondary" size="sm" onClick={() => setShowGroqKey((v) => !v)} disabled={!groqKey}>
+ {showGroqKey ? 'hide' : 'show'}
+ </PixelButton>
+ </div>
+ </label>
+
+ <div style={{ display: 'flex', gap: 16 }}>
+ {/* Model picker */}
+ <label style={{ display: 'flex', flexDirection: 'column', gap: 4, flex: 1 }}>
+ <span style={slackLabelStyle}>Model</span>
+ <select
+ value={freeflowModel}
+ onChange={(e) => setFreeflowModel(e.target.value)}
+ style={{ ...slackInputStyle, fontFamily: 'var(--cth-font-mono)' }}
+ >
+ <option value="whisper-large-v3-turbo">whisper-large-v3-turbo (fast)</option>
+ <option value="whisper-large-v3">whisper-large-v3 (accurate)</option>
+ </select>
+ </label>
+ {/* Global push-to-talk hotkey (entry point B). */}
+ <label style={{ display: 'flex', flexDirection: 'column', gap: 4, flex: 1 }}>
+ <span style={slackLabelStyle}>Global hotkey (toggle)</span>
+ <input
+ value={freeflowHotkey}
+ onChange={(e) => setFreeflowHotkey(e.target.value)}
+ placeholder="Control+Alt+D"
+ style={{ ...slackInputStyle, fontFamily: 'var(--cth-font-mono)' }}
+ />
+ </label>
+ </div>
+
+ <div style={{ display: 'flex', gap: 8, alignItems: 'center' }}>
+ <PixelButton variant="ghost" size="sm" onClick={() => saveFreeflow()} disabled={freeflowBusy}>
+ save
+ </PixelButton>
+ {freeflowNote && (
+ <span style={{ fontSize: 12, color: 'var(--cth-ink-500)' }}>{freeflowNote}</span>
+ )}
+ </div>
+
+ <span style={{ fontSize: 12, lineHeight: '16px', color: 'var(--cth-ink-500)' }}>
+ A mic button appears above Send in the queue composer — click to record, click again to
+ transcribe into the draft (review before sending). The global hotkey toggles dictation for
+ the agent you're viewing from anywhere. macOS doesn't expose the <code>Fn</code> key to the
+ app, so the global gesture is a key-combo toggle rather than Fn hold-to-talk. macOS will ask
+ for microphone permission the first time you record.
+ </span>
+ </div>
+ )}
+ </div>
</>
)}
diff --git a/src/renderer/src/freeflow/recorder.ts b/src/renderer/src/freeflow/recorder.ts
new file mode 100644
index 00000000..aad7e5c9
--- /dev/null
+++ b/src/renderer/src/freeflow/recorder.ts
@@ -0,0 +1,162 @@
+/**
+ * Free Flow recorder — a single shared push-to-talk capture engine for the whole
+ * renderer. Both entry points use it, so only ONE recording can run at a time:
+ * (A) the "Free Flow" button in MessageQueueComposer, and
+ * (B) the global push-to-talk hotkey (main pushes `freeflow:hotkey`).
+ *
+ * Flow: getUserMedia(audio) → MediaRecorder (webm/opus) → on stop, the blob's
+ * bytes go to main over IPC (`freeflowTranscribe`), which calls Groq Whisper and
+ * returns the transcript. The transcript is APPENDED to the target agent's
+ * composer draft (store.drafts) — never auto-sent — faithful to freeflow: the
+ * user reviews, then presses Send/Enter.
+ *
+ * Exposed as a module singleton + a `useFreeflow()` hook (useSyncExternalStore)
+ * so the button can reflect recording/transcribing state without prop-drilling.
+ */
+import { useSyncExternalStore } from 'react';
+import { useStore } from '@/store/store';
+
+export type FreeflowStatus = 'idle' | 'recording' | 'transcribing';
+
+export interface FreeflowState {
+ status: FreeflowStatus;
+ /** The agent whose draft a finished transcript will land in. */
+ targetAgentId: string | null;
+ /** Last error (mic denied, Groq failure…). Cleared when a new capture starts. */
+ error: string | null;
+}
+
+let state: FreeflowState = { status: 'idle', targetAgentId: null, error: null };
+const listeners = new Set<() => void>();
+
+function setState(patch: Partial<FreeflowState>): void {
+ state = { ...state, ...patch };
+ for (const l of listeners) l();
+}
+
+function subscribe(cb: () => void): () => void {
+ listeners.add(cb);
+ return () => listeners.delete(cb);
+}
+
+function getSnapshot(): FreeflowState {
+ return state;
+}
+
+// ─── Recording internals ─────────────────────────────────────────────────────
+let recorder: MediaRecorder | null = null;
+let stream: MediaStream | null = null;
+let chunks: Blob[] = [];
+
+/** Prefer webm/opus (Groq-supported, Chromium default); fall back to whatever the
+ * platform offers. Returns '' to let MediaRecorder pick its default. */
+function pickMimeType(): string {
+ const candidates = ['audio/webm;codecs=opus', 'audio/webm', 'audio/ogg;codecs=opus'];
+ const supported = typeof MediaRecorder !== 'undefined' && typeof MediaRecorder.isTypeSupported === 'function';
+ if (supported) {
+ for (const c of candidates) {
+ if (MediaRecorder.isTypeSupported(c)) return c;
+ }
+ }
+ return '';
+}
+
+/** Release the mic stream so the OS recording indicator clears. */
+function teardownStream(): void {
+ try { stream?.getTracks().forEach((t) => t.stop()); } catch { /* noop */ }
+ stream = null;
+}
+
+/** Append `text` to the target agent's composer draft (with a separating space). */
+function deliverTranscript(agentId: string, text: string): void {
+ const st = useStore.getState();
+ const cur = st.drafts[agentId] ?? '';
+ const sep = cur && !/\s$/.test(cur) ? ' ' : '';
+ st.setDraft(agentId, cur + sep + text);
+}
+
+/** Begin capturing for `agentId`. No-op (besides surfacing an error) if the mic
+ * can't be opened. Safe to call only from the idle state. */
+async function start(agentId: string): Promise<void> {
+ if (state.status !== 'idle') return;
+ if (!agentId) { setState({ error: 'no agent selected' }); return; }
+ if (typeof navigator === 'undefined' || !navigator.mediaDevices?.getUserMedia) {
+ setState({ error: 'microphone not available' });
+ return;
+ }
+ try {
+ stream = await navigator.mediaDevices.getUserMedia({ audio: true });
+ } catch (e) {
+ // Permission denied / no device — surface a short, friendly message.
+ const name = e instanceof DOMException ? e.name : '';
+ setState({
+ status: 'idle',
+ error: name === 'NotAllowedError' ? 'microphone permission denied' : 'could not open microphone'
+ });
+ return;
+ }
+ chunks = [];
+ const mimeType = pickMimeType();
+ try {
+ recorder = mimeType ? new MediaRecorder(stream, { mimeType }) : new MediaRecorder(stream);
+ } catch {
+ teardownStream();
+ setState({ status: 'idle', error: 'recording not supported' });
+ return;
+ }
+ recorder.ondataavailable = (ev: BlobEvent) => { if (ev.data && ev.data.size > 0) chunks.push(ev.data); };
+ recorder.onstop = () => { void finish(agentId); };
+ recorder.start();
+ setState({ status: 'recording', targetAgentId: agentId, error: null });
+}
+
+/** Stop the active recording (triggers transcription via `onstop`). */
+function stop(): void {
+ if (state.status !== 'recording' || !recorder) return;
+ try { recorder.stop(); } catch { /* already stopped */ }
+}
+
+/** Called when MediaRecorder finishes: assemble the clip, transcribe, deliver. */
+async function finish(agentId: string): Promise<void> {
+ const type = recorder?.mimeType || 'audio/webm';
+ teardownStream();
+ recorder = null;
+ const blob = new Blob(chunks, { type });
+ chunks = [];
+ if (blob.size === 0) {
+ setState({ status: 'idle', error: 'nothing recorded' });
+ return;
+ }
+ setState({ status: 'transcribing', error: null });
+ try {
+ const buf = await blob.arrayBuffer();
+ const ext = type.includes('ogg') ? 'ogg' : 'webm';
+ const res = await window.cth.freeflowTranscribe({
+ audio: buf,
+ mimeType: type.split(';')[0],
+ filename: `dictation.${ext}`
+ });
+ if (res.ok && res.text) {
+ deliverTranscript(agentId, res.text);
+ setState({ status: 'idle', error: null });
+ } else {
+ setState({ status: 'idle', error: res.error || 'transcription failed' });
+ }
+ } catch (e) {
+ setState({ status: 'idle', error: e instanceof Error ? e.message : 'transcription failed' });
+ }
+}
+
+/** Toggle capture for `agentId`: start if idle, stop if recording. During
+ * transcription it's a no-op (the upload is in flight). */
+function toggle(agentId: string): void {
+ if (state.status === 'recording') stop();
+ else if (state.status === 'idle') void start(agentId);
+}
+
+export const freeflowRecorder = { start, stop, toggle, subscribe, getSnapshot };
+
+/** React hook: subscribe to the shared recorder state. */
+export function useFreeflow(): FreeflowState {
+ return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+}
diff --git a/src/renderer/src/store/config.ts b/src/renderer/src/store/config.ts
index bac031f1..f8923c46 100644
--- a/src/renderer/src/store/config.ts
+++ b/src/renderer/src/store/config.ts
@@ -58,6 +58,11 @@ export interface HarnessConfig {
slackBotToken?: string;
slackChannelId?: string;
slackPort?: number;
+ /** Free Flow voice dictation (mirrors src/main/config.ts). */
+ freeflowEnabled?: boolean;
+ groqApiKey?: string;
+ freeflowModel?: string;
+ freeflowHotkey?: string;
costCapUsd?: number;
/** Hard total-token ceiling across active agents (the user-facing budget). */
costCapTokens?: number;
diff --git a/src/renderer/src/store/store.ts b/src/renderer/src/store/store.ts
index f2ecd047..44936905 100644
--- a/src/renderer/src/store/store.ts
+++ b/src/renderer/src/store/store.ts
@@ -169,6 +169,10 @@ interface State {
* composer) doesn't eat what the user was typing. */
drafts: Record<string, string>;
setDraft: (agentId: string, text: string) => void;
+ /** Mirror of config.freeflowEnabled so the composer can show/hide the Free Flow
+ * mic button reactively (set by App on config load and by Settings on save). */
+ freeflowEnabled: boolean;
+ setFreeflowEnabled: (on: boolean) => void;
/** Park a message for an agent. Returns nothing; the flush loop delivers it. */
enqueueMessage: (agentId: string, text: string, meta?: { slack?: { channel: string; thread_ts: string } }) => void;
/** Drop a single queued message (user removed it, or it was just delivered). */
@@ -458,6 +462,8 @@ export const useStore = create<State>((set) => ({
drafts: {},
setDraft: (agentId, text) =>
set((s) => ({ drafts: { ...s.drafts, [agentId]: text } })),
+ freeflowEnabled: false,
+ setFreeflowEnabled: (on) => set({ freeflowEnabled: on }),
enqueueMessage: (agentId, text, meta) =>
set((s) => {
const trimmed = text.trim();