pi-voice: Skill for Claude Code

Pi-voice Package Development

Patterns and best practices for building the pi-voice extension.

Architecture Overview

pi-voice has two independent layers:

1. Server (extensions/server.ts) — Pure Node.js HTTP server, no pi dependencies. Manages Kokoro ONNX model lifecycle. Talks to kokoro-js only.
2. Extension (extensions/index.ts) — pi SDK integration: tools, commands, events, TUI. Talks to the server via HTTP.

The extension never touches the TTS model directly — it sends HTTP requests to the server.

Pi SDK Docs

For the complete API reference, read pi's installed docs:

npm root -g  # → <dir>/@earendil-works/pi-coding-agent/docs/

Doc	When to read
extensions.md	Adding tools, commands, events, providers
tui.md	Building custom UI components
skills.md	Authoring skills
themes.md	Creating themes
packages.md	Package distribution
session-format.md	SessionManager API, entry types

Extension Patterns

Tool Registration

The tts tool pattern — a tool that calls the TTS server and returns output:

ctx.tools.register("tts", {
  description: "Convert text to speech audio",
  parameters: Type.Object({
    text: Type.String({ description: "Text to speak" }),
  }),
  render: "text",
  execute: async (args) => {
    const response = await fetch(`http://${host}:${port}/tts`, { ... });
    // process and play audio
    return { output: "Speaking: ..." };
  },
});

Slash Command with Custom TUI

The /voice command uses ctx.ui.custom() for a full-screen settings UI:

ctx.commands.register("/voice", {
  description: "Voice settings",
  execute: async () => {
    ctx.ui.custom(renderVoiceUI, handleVoiceKey);
  },
});

The render function returns ink-compatible elements. The key handler receives key events and returns true to trigger re-render.

Event Handlers

Auto-TTS listens to agent_end and synthesizes speech:

ctx.events.on("agent_end", async (event) => {
  const text = extractLastMessage(event);
  const summary = await summarizeWithModel(ctx, text);
  await speak(summary, config);
});