Feat: Add whisper speech-to-text input command with post-transcription actions for insert, editable send-to-session, and clipboard copy (#268)

* Add Whisper speech-to-text input and tests

* Rename menu entry v to Git/GitHub action

* update HISTORY

* Rename menu label to GitHub PR AI Action

* Refactor speech-to-text and lazy-load prompt mode

* fix test suites

* Add comparison table and clarify differences

* Enable AI session links by default

Author: tninja

HISTORY.org

@@ -2,6 +2,8 @@
 * Release history
 
 ** Main branch change
+- Feat: Add whisper speech-to-text input command with post-transcription actions for insert, editable send-to-session, and clipboard copy
+- Fix: Slowness of ai coding session given clickable session link feature
 
 ** 1.65
 - Feat: Add agent-shell integration for ai-code-behaviors, by davidwuchn

README.org

@@ -27,7 +27,24 @@ An Emacs interface for AI-assisted software development. *The purpose is to prov
 
 - I switch between different CLI-based AI tools in Emacs: Claude Code / OpenAI Codex / Gemini CLI / etc. If you also use different AI tools inside Emacs, but want to keep the same user interface and experience, this package is for you.
 
-- Lots of features and tools are ported from [[https://github.com/tninja/aider.el][aider.el]]. If you like the features in aider.el, but wish to switch to modern AI coding CLI, this package is also for you.
+- If you are deciding between the main AI coding packages inside Emacs, the most important question is this: do you want one consistent coding workflow across many AI tools, or do you want the deepest integration for one specific agent runtime? The table below focuses on the user-visible differences that matter day to day.
+
+| Feature     | ai-code-interface.el                                                                                                          | claude-code-ide.el                                                                                  | agent-shell                                                                      | eca-emacs                                                                   |
+|-------------+-----------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------+------------------------------------------------------------------------------|
+| Switching   | Best when you move between Codex, Claude Code, Gemini CLI, Copilot CLI, and other supported backends without relearning commands | Claude Code only                                                                                   | Many ACP agents, but through one ACP shell model                                 | ECA agents and models inside one ECA workspace                                |
+| Context    | Current file, visible buffers, function or region, saved repo context, prompt files, and @ file completion                                | Active file, selection, project data, diagnostics, and editor-aware mentions                                 | Shell session context, project files, transcripts, screenshots, and clipboard image support | File and range references, repomap, cursor auto-context, and workspace-aware chats |
+| Editor tools | Built-in Emacs MCP tools for project info, imenu, xref, and tree-sitter, plus MCP debug and config helpers                              | Deepest Claude-specific Emacs MCP bridge, including diagnostics and custom Emacs tools exposed to Claude | MCP server configuration is available, but the main focus is the ACP shell session        | MCP-aware chat settings and tool-call handling, but centered on the ECA server      |
+| Actions     | Task-first actions such as change code, implement TODO, explain, ask, refactor, and prompt workflows                                | Claude-first IDE prompting, mentions, and editor-aware operations                                       | Shell-first agent interaction; coding style depends on the ACP agent you connect       | Chat-first coding, context injection, and rewrite flows                             |
+| Dev loop    | Built-in TDD cycle, diff review, Magit helpers, and refactoring actions                                                              | Strong Claude-specific ediff flow with diagnostics-aware review                                          | Strong queue, transcript, model-switching, and container-friendly shell workflow       | Strong approvals, rewrite diff, timelines, and saved chats                          |
+| Sessions    | One consistent workflow even when the backend changes underneath                                                            | Multiple Claude sessions per project                                                                  | Multiple ACP shells with queueing and transcripts                                   | Multiple chats per workspace with agent and model switching                     |
+| Visibility    | Review-oriented commands, prompt files, and backend-aware session buffers                                                      | Session list, debug buffer, resume flow, and IDE diff controls                                            | Queue view, transcripts, screenshots, and shell-level visibility                         | Tool-call approvals, expandable blocks, timeline view, and chat state indicators       |
+| Best fit     | You want one Emacs UX across many AI coding tools                                                                             | You want the deepest Claude Code integration in Emacs                                                | You want ACP-native shells and transcript-heavy workflows                           | You want a polished server-backed chat workspace                               |
+
+- All four packages share the same broad goal: keep AI-assisted coding inside Emacs, preserve project context, and make long-running AI sessions practical. The difference is where they place the center of gravity. =claude-code-ide.el= goes deepest on Claude Code plus MCP-powered editor awareness. =agent-shell= goes deepest on ACP and shell-native agent operations. =eca-emacs= goes deepest on a dedicated server-backed chat UX.
+
+- =ai-code-interface.el= is different because its biggest advantage is *one stable coding workflow across many AI backends*. Unlike =claude-code-ide.el=, which is centered on Claude Code, =agent-shell=, which is centered on ACP shells, or =eca-emacs=, which is centered on the ECA server, =ai-code-interface.el= keeps the same menu, context gathering, prompt construction, refactoring actions, TDD helpers, git-oriented review flow, and Emacs MCP tools while the backend changes underneath. In practice, that means switching from Claude Code to Codex, Gemini CLI, Copilot CLI, or another backend does not force you to relearn how you work inside Emacs.
+
+- That also means this package is a good fit when you do not want to pick a single winner forever. You can keep using specialized backends when they are the right tool for a task, but still drive them from one Emacs-centered interface focused on code changes, review, and iterative development instead of one vendor-specific chat surface.
 
 - Screenshot
 
@@ -109,6 +126,7 @@ Enable installation of packages from MELPA by adding an entry to package-archive
 
 *** Optional Dependencies
 - `helm`: For an enhanced auto-completion experience (`ai-code-input.el`).
+- `whisper`: For speech-to-text input via `ai-code-speech-to-text-input`. Record audio, press `RET` to stop, then choose whether to insert the transcription into the current buffer, send it to the active AI coding session with editable initial input, or copy it to the clipboard.
 - `gptel`: For intelligent, AI-generated content headlines in the prompt file.
   - ai-code-task-use-gptel-filename: When non-nil, file name created by `ai-code-create-or-open-task-file` or `ai-code-create-file-or-dir` will have auto-generated filenames created by GPTel
   - ai-code-notes-use-gptel-headline: When non-nil, notes created by `ai-code-take-notes` will have auto-generated headlines created by GPTel
@@ -131,7 +149,7 @@ Enable installation of packages from MELPA by adding an entry to package-archive
 [[./clickable_link_ai_session.png]]
 - *Context-Aware Code Actions*: The menu exposes dedicated entries for changing code (`c`), implementing TODOs (`i`), asking questions (`q`), explaining code (`x`), sending free-form commands (`<SPC>`), and refreshing AI context (`@`). Each command automatically captures the surrounding function, region, or clipboard contents (via `C-u`) to keep prompts precise.
 - *Agile Development Workflows*: Use the refactoring navigator (`r`), the guided TDD cycle (`t`), and the pull/review diff helper (`v`) to keep AI-assisted work aligned with agile best practices. Prompt authoring is first-class through quick access to the prompt file (`p`), build/test helper (`b`), and AI-assisted shell/file execution (`!`). In prompt files, send the current block with `C-c C-c`.
-- *Productivity & Debugging Utilities*: Initialize project navigation assets (`.`), investigate exceptions (`e`), auto-fix Flycheck issues in scope (`f`), copy or open file paths formatted for prompts (`k`, `o`), generate MCP inspector commands (`m`), capture session notes straight into Org (`n`), and toggle desktop notifications (`N`) to get alerted when AI responses are ready in background sessions.
+- *Productivity & Debugging Utilities*: Initialize project navigation assets (`.`), investigate exceptions (`e`), auto-fix Flycheck issues in scope (`f`), copy or open file paths formatted for prompts (`k`, `o`), generate MCP inspector commands (`m`), capture session notes straight into Org (`n`), dictate prompts with speech-to-text (`:`), and toggle desktop notifications (`N`) to get alerted when AI responses are ready in background sessions.
 - *Seamless Prompt Management*: Open the prompt file via `ai-code-open-prompt-file` (stored under `.ai.code.files/.ai.code.prompt.org` by default), send regions with `ai-code-prompt-send-block`, and reuse prompt snippets via `yasnippet` to keep conversations organized.
 - *Interactive Chat & Context Tools*: Dedicated buffers hold long-running chats, automatically enriched with file paths, diffs, and history from Magit or Git commands for richer AI responses.
 - *AI-Assisted Bash Commands*: From Dired, shell, eshell, or vterm, run `C-c a !` and type natural-language commands prefixed with `:` (e.g., `:count lines of python code recursively`); the tool generates the shell command for review and executes it in a compile buffer.
@@ -147,6 +165,7 @@ Enable installation of packages from MELPA by adding an entry to package-archive
 - *One-prompt TDD with refactoring*: Press `C-c a`, then `t` (`ai-code-tdd-cycle`) and choose `5. Red + Green + Blue (One prompt)` to generate tests, implement code, run tests, and then refactor the changed code in one flow.
 - *Reviewing a Pull Request*: Press `C-c a`, then `v` (`ai-code-pull-or-review-diff-file`). Choose to generate a diff between two branches. The diff will be created in a new buffer, and you'll be prompted to start a review.
 - *Multiple Sessions Support*: Start more AI coding session with C-c a a after launching one. Select active session with C-c a z. Prompt with above command will be sent to the selected session.
+- *Speech to Text Input*: Press `C-c a`, then `:` (`ai-code-speech-to-text-input`). Speak your prompt, press `RET` to stop recording, then choose whether to insert the transcription into the current buffer, send it to the active AI coding session after editing it in `ai-code-read-string`, or copy it to the clipboard.
 
 *** Context Engineering
 

ai-code-input.el

@@ -29,6 +29,20 @@
 (declare-function ai-code-backends-infra--terminal-send-backspace "ai-code-backends-infra" ())
 (declare-function ai-code--prompt-filepath-candidates "ai-code-prompt-mode" ())
 (declare-function ai-code--git-root "ai-code-file" (&optional dir))
+(declare-function ai-code--insert-prompt "ai-code-prompt-mode" (prompt))
+(declare-function whisper-run "whisper" ())
+
+(defvar whisper-after-transcription-hook nil
+  "Hook run by whisper.el after transcription finishes.")
+
+(defconst ai-code--speech-to-text-buffer-name "*whisper-stdout*"
+  "Buffer name used by whisper.el transcription output.")
+
+(defconst ai-code--speech-to-text-actions
+  '("Insert to current buffer"
+    "Send to AI coding session"
+    "Copy to clipboard")
+  "Completion choices for speech-to-text transcription handling.")
 
 ;;;###autoload
 (defun ai-code-plain-read-string (prompt &optional initial-input candidate-list)
@@ -118,6 +132,66 @@ INITIAL-INPUT is optional initial input string.
 CANDIDATE-LIST is an optional list of candidate strings to show before history."
   (ai-code-helm-read-string-with-history prompt "ai-code-helm-read-string-history.el" initial-input candidate-list))
 
+(defun ai-code--speech-to-text-apply-transcription (origin-buffer)
+  "Read transcription from current buffer and apply a chosen speech action.
+The transcription is obtained from the current buffer, then if
+ORIGIN-BUFFER is still live and the transcription is non-empty,
+prompt the user to choose an action (insert into ORIGIN-BUFFER,
+send to an AI coding session, or copy to the clipboard) and
+perform that action."
+  (let ((transcription
+         (string-trim
+          (buffer-substring-no-properties (point-min) (point-max)))))
+    (when (and (buffer-live-p origin-buffer)
+               (not (string-empty-p transcription)))
+      (ai-code--speech-to-text-handle-action
+       origin-buffer
+       transcription
+       (completing-read "Choose speech action: "
+                        ai-code--speech-to-text-actions
+                        nil t)))))
+
+(defun ai-code--speech-to-text-handle-action (origin-buffer transcription action)
+  "Handle speech ACTION for TRANSCRIPTION from ORIGIN-BUFFER."
+  (pcase action
+    ("Insert to current buffer"
+     (with-current-buffer origin-buffer
+       (insert transcription)))
+    ("Send to AI coding session"
+     (ai-code--speech-to-text-send-prompt origin-buffer transcription))
+    ("Copy to clipboard"
+     (kill-new transcription))))
+
+(defun ai-code--speech-to-text-send-prompt (origin-buffer transcription)
+  "Edit TRANSCRIPTION from ORIGIN-BUFFER and send the result to the AI session."
+  (when-let ((prompt (with-current-buffer origin-buffer
+                       (ai-code-read-string "Send to AI: " transcription))))
+    (require 'ai-code-prompt-mode)
+    (ai-code--insert-prompt prompt)))
+
+;;;###autoload
+(defun ai-code-speech-to-text-input ()
+  "Record audio with whisper.el, then choose how to use the transcription.
+
+After recording and transcription, you can insert the text at point in the
+original buffer, send it to an AI coding session, or copy it to the clipboard."
+  (interactive)
+  (unless (require 'whisper nil t)
+    (user-error "Whisper.el is not available, please install it first"))
+  (let ((origin-buffer (current-buffer)))
+    (with-current-buffer (get-buffer-create ai-code--speech-to-text-buffer-name)
+      (erase-buffer)
+      (setq-local whisper-after-transcription-hook nil)
+      (add-hook 'whisper-after-transcription-hook
+                (lambda ()
+                  (ai-code--speech-to-text-apply-transcription origin-buffer))
+                nil t)
+      (whisper-run)
+      (message "Recording audio. Press RET when you are done.")
+      (while (not (equal ?\r (read-char)))
+        (sit-for 0.5))
+      (whisper-run))))
+
 ;;;###autoload
 (when (featurep 'helm)
   (setq ai-code--read-string-fn #'ai-code-helm-read-string))

ai-code-session-link.el

@@ -20,7 +20,7 @@
 (defvar ai-code-backends-infra--session-directory nil
   "Session working directory set by ai-code-backends-infra buffers.")
 
-(defcustom ai-code-session-link-enabled nil
+(defcustom ai-code-session-link-enabled t
   "When non-nil, make supported links clickable in AI session buffers.
 
 Disable this if you prefer to avoid the extra linkification work on

ai-code.el

@@ -465,7 +465,7 @@ Shows the current backend label to the right."
   (ai-code--infix-select-code-change-auto-test)
   ("r" "Refactor Code" ai-code-refactor-book-method)
   ("t" "Test Driven Development" ai-code-tdd-cycle)
-  ("v" "Pull or Review Code Change" ai-code-pull-or-review-diff-file)
+  ("v" "GitHub PR AI Action" ai-code-pull-or-review-diff-file)
   ("!" "Run Current File or Command" ai-code-run-current-file-or-shell-cmd)
   ("b" "Build / Test (AI follow-up)" ai-code-build-or-test-project)
   ("K" "Create or open task file" ai-code-create-or-open-task-file)
@@ -479,6 +479,7 @@ Shows the current backend label to the right."
   ("o" "Open recent file (C-u: insert)" ai-code-git-repo-recent-modified-files)
   ("p" "Open prompt history file" ai-code-open-prompt-file)
   ("m" "Debug python MCP server" ai-code-debug-mcp)
+  (":" "Speech to text input" ai-code-speech-to-text-input)
   ("N" "Toggle notifications" ai-code-notifications-toggle))
 
 (transient-define-prefix ai-code-menu-default ()

test/stubs/eca-chat.el

@@ -0,0 +1,37 @@
+;;; eca-chat.el --- Minimal ECA chat test stub -*- lexical-binding: t; -*-
+
+;; SPDX-License-Identifier: Apache-2.0
+
+;;; Commentary:
+;; Lightweight ECA chat stub for batch tests.
+
+;;; Code:
+
+(defun eca-chat-open (&optional _session)
+  "Return nil in the lightweight test stub."
+  nil)
+
+(defun eca-chat-send-prompt (_message)
+  "Return nil in the lightweight test stub."
+  nil)
+
+(defun eca-chat--get-last-buffer (_session)
+  "Return the current buffer in the lightweight test stub."
+  (current-buffer))
+
+(defun eca-chat-add-workspace-root ()
+  "Return nil in the lightweight test stub."
+  (interactive)
+  nil)
+
+(defun eca-chat-add-file-context (&rest _args)
+  "Return nil in the lightweight test stub."
+  nil)
+
+(defun eca-chat-add-repo-map-context (&rest _args)
+  "Return nil in the lightweight test stub."
+  nil)
+
+(provide 'eca-chat)
+
+;;; eca-chat.el ends here

test/stubs/eca-process.el

@@ -0,0 +1,16 @@
+;;; eca-process.el --- Minimal ECA process test stub -*- lexical-binding: t; -*-
+
+;; SPDX-License-Identifier: Apache-2.0
+
+;;; Commentary:
+;; Lightweight ECA process stub for batch tests.
+
+;;; Code:
+
+(defun eca-process--download-url (_version)
+  "Return an empty download URL in the lightweight test stub."
+  "")
+
+(provide 'eca-process)
+
+;;; eca-process.el ends here

test/stubs/eca-util.el

@@ -0,0 +1,77 @@
+;;; eca-util.el --- Minimal ECA util test stub -*- lexical-binding: t; -*-
+
+;; SPDX-License-Identifier: Apache-2.0
+
+;;; Commentary:
+;; Lightweight ECA utility stub for unit tests that do not need the real runtime.
+
+;;; Code:
+
+(require 'cl-lib)
+
+(defvar eca--sessions nil
+  "Minimal session store for the test stub.")
+
+(defvar eca--stub-session nil
+  "Current session object used by the test stub.")
+
+(defun eca-session ()
+  "Return the current stub session."
+  eca--stub-session)
+
+(defun eca-vals (map)
+  "Return MAP values for alists and hash tables."
+  (cond
+   ((hash-table-p map)
+    (let (values)
+      (maphash (lambda (_key value) (push value values)) map)
+      (nreverse values)))
+   ((listp map)
+    (mapcar #'cdr map))
+   (t nil)))
+
+(defun eca-info (format-string &rest args)
+  "Format FORMAT-STRING with ARGS for the test stub."
+  (apply #'format format-string args))
+
+(defun eca--session-id (session)
+  "Return SESSION id or a default stub value."
+  (or (plist-get session :id) 1))
+
+(defun eca--session-status (session)
+  "Return SESSION status or a default stub value."
+  (or (plist-get session :status) 'running))
+
+(defun eca--session-workspace-folders (session)
+  "Return SESSION workspace folders."
+  (plist-get session :workspace-folders))
+
+(defun eca-create-session (workspace-folders)
+  "Create a new stub session for WORKSPACE-FOLDERS."
+  (setq eca--stub-session (list :id 1 :status 'running :workspace-folders workspace-folders)))
+
+(defun eca-delete-session (_session)
+  "Delete the current stub session."
+  (setq eca--stub-session nil)
+  t)
+
+(defun eca-assert-session-running (_session)
+  "Pretend the current stub session is running."
+  t)
+
+(defun eca--session-add-workspace-folder (session folder)
+  "Return SESSION with FOLDER adjoined to its workspace list."
+  (plist-put session
+             :workspace-folders
+             (cl-adjoin folder (plist-get session :workspace-folders) :test #'string=)))
+
+(defun eca-get (map key)
+  "Get KEY from MAP for hash tables and plists."
+  (cond
+   ((hash-table-p map) (gethash key map))
+   ((listp map) (plist-get map key))
+   (t nil)))
+
+(provide 'eca-util)
+
+;;; eca-util.el ends here