tellme-gemini
Voice conversation with Gemini using TTS and STT
Open source Open in the app JSON README (API)
About
Voice conversation with Gemini using TTS and STT
Details
- Kind
- Plugins
- Topic
- AI, RAG & memory
- Publisher
- sandipchitale
- Origin
- gemini
- Category
- ferramentas
- Version
- 1.0.0
- Last push
- 2026-03-21T23:13:37Z
- Repository state
- ativo
- Language
- TypeScript
- Added
- 2026-08-30 14:13:39
- Updated
- 2026-08-30 14:13:39
- Origin id
sandipchitale/tellme-gemini
README
# TellMe for Gemini
A Gemini CLI extension that provides an interactive speech-based prompt mechanism and reads Gemini's responses aloud using macOS text-to-speech.
## Overview
TellMe Gemini enhances the Gemini CLI by hooking into the agent lifecycle:
1. **Interactive Prompt (BeforeAgent Hook)** — When you prefix your prompt with a dot (`.`), a Java Swing dialog box pops up for you to type your input. It then reads your prompt aloud ("You said: ...") and passes it to Gemini. If you prefix the prompts with `..` then it will not use the dialog box and will use the input from the prompt.
2. **Speech Response (AfterAgent Hook)** — After Gemini finishes responding to a spoken prompt (prefixed with `.` or `..` or suffixed with `..`), the extension reads Gemini's response aloud ("I say: ...") using the native macOS `say` command in the background.
## Requirements
- macOS (uses `/usr/bin/say` for text-to-speech)
- Node.js
- Java runtime (for the input dialog)
- Gemini CLI with extension support
## Installation
```sh
git clone https://github.com/sandipchitale/tellme-gemini
cd tellme-gemini
gemini extensions link .
```
## Disable the extension
```bash
gemini extensions disable tellme-gemini
```
## Enable the extension
```bash
gemini extensions enable tellme-gemini
```
## Uninstallation
```bash
gemini extensions uninstall tellme-gemini
```
## How It Works
### BeforeAgent Hook (i-say)
1. You provide a prompt to the Gemini CLI starting with a `.` or `..` (e.g., `.`).
2. The `BeforeAgent` hook executes `tellme.mjs`.
3. It detects the `.` prefix and launches a Java Swing input dialog ("Wassup? (try dictation)"). If you prefix the prompts with `..` then it will not use the dialog box and will use the input from the prompt.
4. You enter your actual prompt and click "OK" (if using `.`).
5. It uses the macOS `/usr/bin/say` command to speak your input aloud in the background: _"You said: {input}."_. On Linux it uses `/usr/bin/espeak`.
6. It sends the input to the Gemini CLI as `additionalContext` to be used for the agent. If you cancel the dialog, it gracefully denies the execution, halting the agent.
### AfterAgent Hook (tell-me)
1. After Gemini generates a response, the `AfterAgent` hook triggers.
2. It checks if the original prompt started with `.` or ended with `..`.
3. If it did, it retrieves the generated response from the hook payload (`prompt_response`).
4. It uses `/usr/bin/say` to speak the response aloud: _"I say: {response}"_. On Linux it uses `/usr/bin/espeak`.
5. The `say` process is spawned detached so the Gemini CLI can continue immediately without waiting for the speech to finish.
If the voice output is too long and you want to stop it do at the prompt:
```bash
!killall /usr/bin/say
ESCAPE
```
## Project Structure
```text
tellme-gemini/
├── hooks/
│ └── hooks.json # Hook configuration mapping BeforeAgent/AfterAgent to tellme.mjs
├── scripts/
│ └── tellme.java # Java Swing input dialog (single-file source program)
├── gemini-extension.json # Gemini Extension metadata
├── package.json # Project metadata (no dependencies)
├── tellme.mjs # Main hook handler logic (plain JavaScript, Node.js built-ins only)
└── README.md # This file
```
## Key Implementation Details
- **`tellme.mjs`** — The main script executed by the hooks. It reads the JSON event payload from `stdin` and checks `hook_event_name` to route logic to the `BeforeAgent` or `AfterAgent` handlers. Uses only Node.js built-in modules (`child_process`, `fs`).
- **`scripts/tellme.java`** — A single-file Java source program that displays a Swing dialog for user input. Runs directly via `java tellme.java` without needing compilation.
- **`hooks/hooks.json`** — Registers `i-say` for the `BeforeAgent` hook and `tell-me` for the `AfterAgent` hook. Both point to the `tellme.mjs` script.
## Author
Sandip Chitale
## License
MIT