@p8n.ai/pi-listens 0.1.2 → 0.2.0

package/CHANGELOG.md

@@ -6,6 +6,21 @@ This project follows [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-05-09
+
+### Added
+
+- `/init` command to create a global settings file (`~/.pi/pi-listens.json`) with sensible defaults.
+- `/voice-check` command (replaces `/voice-status`) with improved diagnostic output.
+
+### Changed
+
+- `/voice-on` now enables auto-speak by default for a full hands-free experience. Use `--no-speak` to opt out.
+- Rename `/voice-status` to `/voice-check` to better communicate its diagnostic purpose.
+
+### Removed
+
+- `/listen` slash command. Use `/voice-on` for the hands-free voice loop, or the `voice_input` agent tool for programmatic speech input.
 ## [0.1.2] - 2026-05-09
 
 ### Changed
@@ -39,7 +54,8 @@ This project follows [Semantic Versioning](https://semver.org/).
 - Stop active audio capture/playback subprocesses when voice mode is closed or the Pi session shuts down.
 - Clean up generated audio files when spoken playback is interrupted.
 
-[Unreleased]: https://github.com/p8n-ai/pi-listens/compare/v0.1.2...HEAD
+[Unreleased]: https://github.com/p8n-ai/pi-listens/compare/v0.2.0...HEAD
 [0.1.0]: https://github.com/p8n-ai/pi-listens/releases/tag/v0.1.0
 [0.1.1]: https://github.com/p8n-ai/pi-listens/releases/tag/v0.1.1
 [0.1.2]: https://github.com/p8n-ai/pi-listens/releases/tag/v0.1.2
+[0.2.0]: https://github.com/p8n-ai/pi-listens/releases/tag/v0.2.0

package/README.md

@@ -7,14 +7,27 @@ Speech-first Pi package powered by [Sarvam AI](https://www.sarvam.ai/). It gives
 - voice-first clarification loops where the agent speaks a question, listens, transcribes, and continues
 - interactive TUI and headless/RPC usage through Pi extension tools and UI fallback
 
-## Install
+## Quick start
 
 ```bash
 pi install npm:@p8n.ai/pi-listens
-export SARVAM_API_KEY="your-sarvam-api-key"
 pi
 ```
 
+Inside Pi, run `/init` to create a global settings file with sensible defaults:
+
+```
+/init
+```
+
+Then open `~/.pi/pi-listens.json` and replace the `apiKey` placeholder with your [Sarvam AI API key](https://dashboard.sarvam.ai).
+
+Alternatively, set the key via environment variable:
+
+```bash
+export SARVAM_API_KEY="your-sarvam-api-key"
+```
+
 For local development from this checkout:
 
 ```bash
@@ -88,16 +101,15 @@ The extension also injects voice guidance into the system prompt:
 
 | Command | Purpose |
 | --- | --- |
-| `/listen [seconds]` | Stream one utterance over Sarvam WebSocket STT, wait for a sustained silence boundary, transcribe, and send it to Pi as a user message. |
+| `/init` | Create a global settings file at `~/.pi/pi-listens.json` with sensible defaults. Use `--overwrite` to replace an existing file. |
 | `/speak <text>` | Speak text with Sarvam TTS. |
-| `/voice-on [--speak] [--manual] [--no-listen] [seconds]` | Open the hands-free TUI panel. By default it listens now and auto-listens again after each agent response. `--speak` reads short assistant replies aloud. `--manual` leaves the panel active but only listens when you press R. |
-| `/voice-on --no-speak` | Open the panel without auto-reading assistant replies. |
-| `/voice-status` | Show setup and voice-mode status. |
+| `/voice-on [--no-speak] [--manual] [--no-listen] [seconds]` | Start the hands-free voice loop. Auto-speaks assistant replies and auto-listens by default. `--no-speak` disables reading replies aloud. `--manual` disables auto-listen (press Space to listen). |
+| `/voice-check` | Show setup diagnostics and voice-mode status. |
 
 Voice panel controls in interactive mode:
-- Space: listen now; press again while listening to stop listening; if Pi is speaking, Space stops playback before listening
-- A: auto-listen on/off (listen again after each assistant reply)
-- S: read aloud on/off (speak assistant replies)
+- Space: listen now; press again while listening to stop; if Pi is speaking, stops playback first
+- A: toggle auto-listen (listen again after each assistant reply)
+- S: toggle read-aloud (speak assistant replies)
 - Q: close the panel and stop any active listening or speaking
 - Click the orb: visual ripple feedback (terminals with mouse reporting)
 
@@ -143,7 +155,7 @@ Example config file:
   "ttsSampleRate": 24000,
   "ttsOutputCodec": "wav",
   "textFallback": true,
-  "autoSpeakAssistant": false,
+  "autoSpeakAssistant": true,
   "maxAutoSpeakChars": 320
 }
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@p8n.ai/pi-listens",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "Pi package for speech-first interaction using Sarvam AI speech-to-text and text-to-speech.",
   "author": "Ravindra Barthwal",
   "license": "MIT",

package/skills/pi-listens/SKILL.md

@@ -15,6 +15,13 @@ This Pi package provides voice tools backed by Sarvam AI.
 - `voice_transcribe_file`: transcribe an existing audio file.
 - `voice_setup_check`: diagnose API key, recorder, player, and voice settings.
 
+## Commands
+
+- `/init`: create a global settings file with defaults. User only needs to set their Sarvam API key.
+- `/speak <text>`: speak text with Sarvam TTS.
+- `/voice-on`: start hands-free voice loop (auto-speaks replies and auto-listens by default).
+- `/voice-check`: show setup diagnostics and voice-mode status.
+
 ## Usage rules
 
 1. When you need user input, clarification, or confirmation, use `voice_ask` instead of asking only in text.

package/src/commands.ts

@@ -1,9 +1,11 @@
-import { mkdir } from "node:fs/promises";
+import { existsSync, readFileSync } from "node:fs";
+import { mkdir, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
 import { join } from "node:path";
 import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { VoiceToolServices } from "./tools.js";
 import { conciseTranscript, prepareSpokenText } from "./text.js";
-import { audioExtensionForCodec } from "./config.js";
+import { audioExtensionForCodec, maskSecret } from "./config.js";
 import { applyVoiceChrome, installVoiceUi, uninstallVoiceUi } from "./voice-ui.js";
 
 export type VoiceLoopStatus = "idle" | "listening" | "transcribing" | "agent" | "speaking" | "error";
@@ -26,10 +28,10 @@ export interface VoiceModeState {
 }
 
 export function registerVoiceCommands(pi: ExtensionAPI, services: VoiceToolServices, state: VoiceModeState) {
-	pi.registerCommand("listen", {
-		description: "Record speech, transcribe with Sarvam AI, and send it to pi as a user message",
+	pi.registerCommand("init", {
+		description: "Create a global pi-listens settings file at ~/.pi/pi-listens.json with sensible defaults",
 		handler: async (args, ctx) => {
-			await listenAndSend(pi, services, ctx, parseSeconds(args));
+			await initSettings(services, ctx, args.includes("--overwrite"));
 		},
 	});
 
@@ -46,11 +48,10 @@ export function registerVoiceCommands(pi: ExtensionAPI, services: VoiceToolServi
 	});
 
 	pi.registerCommand("voice-on", {
-		description: "Enable hands-free voice loop. Use --speak to read short assistant replies aloud.",
+		description: "Enable hands-free voice loop with auto-speak and auto-listen. Use --no-speak to disable reading replies aloud, --manual to only listen on demand.",
 		handler: async (args, ctx) => {
 			state.enabled = true;
-			if (args.includes("--speak")) state.autoSpeakAssistant = true;
-			if (args.includes("--no-speak")) state.autoSpeakAssistant = false;
+			state.autoSpeakAssistant = !args.includes("--no-speak");
 			state.autoListen = !args.includes("--manual");
 			installVoiceUi(ctx, state, createVoiceUiCallbacks(pi, services, state, ctx));
 			applyVoiceChrome(ctx, state);
@@ -60,30 +61,97 @@ export function registerVoiceCommands(pi: ExtensionAPI, services: VoiceToolServi
 	});
 
 
-	pi.registerCommand("voice-status", {
-		description: "Show pi-listens Sarvam AI, recorder, player, and voice-mode status",
+	pi.registerCommand("voice-check", {
+		description: "Check pi-listens setup: Sarvam AI key, recorder, player, and voice-mode status",
 		handler: async (_args, ctx) => {
 			const config = services.getConfig();
 			const audio = services.getAudio().describe();
+			const ready = Boolean(config.apiKey) && audio.recorder !== "missing" && audio.player !== "missing";
 			ctx.ui.notify(
 				[
-					`Voice mode: ${state.enabled ? "on" : "off"}`,
-					`Auto-speak assistant: ${state.autoSpeakAssistant ? "on" : "off"}`,
-					`Auto-listen: ${state.autoListen ? "on" : "off"}`,
-					`Status: ${state.status}`,
-					`Sarvam API key: ${config.apiKey ? "set" : "missing"}`,
+					ready ? "✓ pi-listens is ready." : "⚠ pi-listens needs attention.",
+					"",
+					`Sarvam API key: ${maskSecret(config.apiKey)}`,
 					`Recorder: ${audio.recorder}`,
 					`Player: ${audio.player}`,
 					`Streaming player: ${audio.streamingPlayer}`,
 					`STT: ${config.sttModel} (${config.translateInputToEnglish ? "translate→English" : config.sttMode}, ${config.sttLanguageCode})`,
 					`TTS: ${config.ttsModel} (${config.ttsLanguageCode}, speaker ${config.ttsSpeaker})`,
+					"",
+					`Voice mode: ${state.enabled ? "on" : "off"}`,
+					`Auto-speak: ${state.autoSpeakAssistant ? "on" : "off"}`,
+					`Auto-listen: ${state.autoListen ? "on" : "off"}`,
 				].join("\n"),
-				config.apiKey && audio.recorder !== "missing" && audio.player !== "missing" ? "info" : "warning",
+				ready ? "info" : "warning",
 			);
 		},
 	});
 }
 
+const INIT_SETTINGS_TEMPLATE = {
+	apiKey: "paste-your-sarvam-api-key-here",
+	sttModel: "saaras:v3",
+	sttMode: "transcribe",
+	sttLanguageCode: "unknown",
+	translateInputToEnglish: true,
+	ttsModel: "bulbul:v3",
+	ttsLanguageCode: "en-IN",
+	ttsSpeaker: "shubh",
+	recordSeconds: 300,
+	recordSampleRate: 16000,
+	streamChunkMs: 250,
+	streamMaxSeconds: 300,
+	silenceStartSeconds: 0.2,
+	silenceStopSeconds: 3.5,
+	silenceThreshold: "1%",
+	ttsSampleRate: 24000,
+	ttsOutputCodec: "wav",
+	textFallback: true,
+	autoSpeakAssistant: true,
+	maxAutoSpeakChars: 320,
+};
+
+async function initSettings(services: VoiceToolServices, ctx: ExtensionCommandContext, overwrite: boolean) {
+	const dir = join(homedir(), ".pi");
+	const filePath = join(dir, "pi-listens.json");
+
+	if (existsSync(filePath) && !overwrite) {
+		const existing = readFileSync(filePath, "utf8");
+		let parsed: Record<string, unknown> = {};
+		try { parsed = JSON.parse(existing) as Record<string, unknown>; } catch { /* ignore */ }
+		const hasKey = typeof parsed.apiKey === "string" && parsed.apiKey !== "paste-your-sarvam-api-key-here" && parsed.apiKey.length > 0;
+		ctx.ui.notify(
+			[
+				`Settings file already exists: ${filePath}`,
+				hasKey ? "Sarvam API key: set" : "Sarvam API key: not yet configured",
+				"",
+				"Use /init --overwrite to replace it with fresh defaults.",
+			].join("\n"),
+			"info",
+		);
+		return;
+	}
+
+	await mkdir(dir, { recursive: true });
+	await writeFile(filePath, `${JSON.stringify(INIT_SETTINGS_TEMPLATE, null, 2)}\n`, "utf8");
+
+	const audio = services.getAudio().describe();
+	ctx.ui.notify(
+		[
+			`✓ Created settings file: ${filePath}`,
+			"",
+			"Next step: open the file and replace the apiKey value with your Sarvam AI API key.",
+			"Get a key at: https://dashboard.sarvam.ai",
+			"",
+			`Recorder: ${audio.recorder}`,
+			`Player: ${audio.player}`,
+			audio.recorder === "missing" || audio.player === "missing"
+				? "⚠ Install SoX (rec/play) or ffmpeg for microphone and audio playback."
+				: "✓ Audio recorder and player detected.",
+		].join("\n"),
+		"info",
+	);
+}
 export async function maybeContinueVoiceLoop(pi: ExtensionAPI, services: VoiceToolServices, state: VoiceModeState, ctx: ExtensionContext) {
 	if (!state.enabled || state.isListening) return;
 	if (state.autoSpeakAssistant && state.lastAssistantText) {

package/src/index.ts

@@ -52,7 +52,7 @@ export default function piListensExtension(pi: ExtensionAPI) {
 					`Sarvam API key: ${maskSecret(config.apiKey)}`,
 					`Recorder: ${audioInfo.recorder}`,
 					`Player: ${audioInfo.player}`,
-					"Run /voice-status or call voice_setup_check for details.",
+					"Run /init to create a settings file, or /voice-check for details.",
 				].join("\n"),
 				"warning",
 			);