From 3e70b2e7742af54a28a5f4fe43fc1a3d7c34f03d Mon Sep 17 00:00:00 2001 From: Brand Date: Sun, 10 May 2026 17:20:42 -0600 Subject: [PATCH] =?UTF-8?q?feat(integrations):=20SP-4=20multi-platform=20M?= =?UTF-8?q?CP=20=E2=80=94=20alias=20+=20per-agent=20docs?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds the multi-platform reach for codetalker per SP-4 of the commercial launch master plan. CodeTalker already ships an MCP server (claude-code-talker-mcp-stdio) that any MCP-compatible AI agent can connect to — the work this PR adds is packaging + discoverability: 1. **Shorter console_script alias** in core/pyproject.toml: - codetalker-mcp = claude_code_talker.mcp_stdio:main - Existing claude-code-talker-mcp-stdio kept for backwards compat. 2. **Per-agent integration docs** in docs/integrations/ covering: - Claude Code (canonical), Cursor, Cline (VS Code), Continue.dev, Windsurf, Zed, Codex CLI, Goose, Roo Code, Replit Agent, AWS Kiro, Google Antigravity - Plus v1.x stubs for Aider (bespoke CLI wrapper) and JetBrains AI Assistant (bespoke plugin) — these are Pro Plus targets per the master plan, scheduled post-launch. 3. **MCP registry submission metadata** in docs/integrations/mcp-registries.md — canonical YAML + submission status for the 8 MCP registries: - registry.modelcontextprotocol.io (official, Sept 2025) - PulseMCP, MCP.so, mcpservers.org - GitHub MCP Registry, modelcontextprotocol/servers awesome-list - Anthropic Claude Marketplace, Continue Hub 4. **README update** with a 'Use with other AI-coding agents' section linking to the new integration guides. No daemon-side code changes — the existing 9 agent-facing MCP tools (tts_speak, tts_set_mode, tts_status, tts_mute, tts_unmute, tts_list_voices, tts_set_voice, tts_set_cadence, tts_shutdown) already work with any MCP client. Session-scoped tool variants (narrate with voice/mode args, session_set_mode, session_set_mute, session_list) ship in a follow-up PR per the master plan's split-PR strategy. Refs: docs/superpowers/specs/2026-05-09-cct-30-open-core-strategy.md Refs: C:/Users/brand/.claude/plans/i-want-to-start-merry-treasure.md Co-Authored-By: Claude Opus 4.7 (1M context) --- README.md | 23 +++++++- core/pyproject.toml | 1 + docs/integrations/README.md | 79 +++++++++++++++++++++++++++ docs/integrations/aider.md | 45 +++++++++++++++ docs/integrations/antigravity.md | 49 +++++++++++++++++ docs/integrations/claude-code.md | 43 +++++++++++++++ docs/integrations/cline.md | 71 ++++++++++++++++++++++++ docs/integrations/codex-cli.md | 51 +++++++++++++++++ docs/integrations/continue.md | 53 ++++++++++++++++++ docs/integrations/cursor.md | 75 +++++++++++++++++++++++++ docs/integrations/goose.md | 49 +++++++++++++++++ docs/integrations/jetbrains.md | 39 +++++++++++++ docs/integrations/kiro.md | 45 +++++++++++++++ docs/integrations/mcp-registries.md | 85 +++++++++++++++++++++++++++++ docs/integrations/replit.md | 57 +++++++++++++++++++ docs/integrations/roo-code.md | 45 +++++++++++++++ docs/integrations/windsurf.md | 53 ++++++++++++++++++ docs/integrations/zed.md | 63 +++++++++++++++++++++ 18 files changed, 925 insertions(+), 1 deletion(-) create mode 100644 docs/integrations/README.md create mode 100644 docs/integrations/aider.md create mode 100644 docs/integrations/antigravity.md create mode 100644 docs/integrations/claude-code.md create mode 100644 docs/integrations/cline.md create mode 100644 docs/integrations/codex-cli.md create mode 100644 docs/integrations/continue.md create mode 100644 docs/integrations/cursor.md create mode 100644 docs/integrations/goose.md create mode 100644 docs/integrations/jetbrains.md create mode 100644 docs/integrations/kiro.md create mode 100644 docs/integrations/mcp-registries.md create mode 100644 docs/integrations/replit.md create mode 100644 docs/integrations/roo-code.md create mode 100644 docs/integrations/windsurf.md create mode 100644 docs/integrations/zed.md diff --git a/README.md b/README.md index f020207..a330199 100644 --- a/README.md +++ b/README.md @@ -25,8 +25,29 @@ Prerequisite (one time): `pip install --user claude-code-talker`. Then run `/cod - `claude-code-plugin/` — Claude Code plugin: one-shot install via `/plugin install`, slash commands, MCP-spawned daemon (Phase 18) - `voice-cloner/` — XTTS character voice generation (Phase 5) +## Use with other AI-coding agents + +CodeTalker ships an MCP server (`codetalker-mcp`) that any MCP-compatible AI coding agent can connect to. Per-agent setup snippets: + +- **[Cursor](docs/integrations/cursor.md)** — `~/.cursor/mcp.json` +- **[Cline](docs/integrations/cline.md)** (VS Code) — `cline_mcp_settings.json` +- **[Continue.dev](docs/integrations/continue.md)** — `~/.continue/config.yaml` +- **[Windsurf](docs/integrations/windsurf.md)** (Codeium) — `mcp_config.json` +- **[Zed](docs/integrations/zed.md)** — `settings.json` `context_servers` +- **[Codex CLI](docs/integrations/codex-cli.md)** (OpenAI) — `~/.codex/config.toml` +- **[Goose](docs/integrations/goose.md)** (Block) — `~/.config/goose/config.yaml` +- **[Roo Code](docs/integrations/roo-code.md)** — VS Code MCP settings +- **[Replit Agent](docs/integrations/replit.md)** — remote MCP (cloud caveat applies) +- **[AWS Kiro](docs/integrations/kiro.md)** — Kiro's MCP config +- **[Google Antigravity](docs/integrations/antigravity.md)** — Antigravity's MCP config +- **[Aider](docs/integrations/aider.md)** (Pro Plus, coming in v1.x) — bespoke CLI wrapper +- **[JetBrains AI Assistant](docs/integrations/jetbrains.md)** (Pro Plus, coming in v1.x) — bespoke plugin + +See [`docs/integrations/README.md`](docs/integrations/README.md) for an overview, troubleshooting, and the MCP tools catalog. + ## Choosing your install path - **Using VS Code?** Install `extension/`. Daemon spawn, status bar, command palette, secrets-to-keychain. - **Using bare Claude Code (terminal, JetBrains, etc.)?** Install `claude-code-plugin/` via `/plugin install`. Slash commands `/codetalker:*`, daemon-aware skill, `tts_set_*` MCP tools Claude can call to self-modulate. -- **Both?** They coexist — same daemon, same hooks; the daemon dedupes any duplicate hook firings. +- **Using a different AI-coding agent?** See the [per-agent integration guides](docs/integrations/README.md) above. One `pip install --user claude-code-talker` covers the daemon for all of them. +- **Multiple at once?** They coexist — same daemon, same hooks; the daemon dedupes any duplicate hook firings. diff --git a/core/pyproject.toml b/core/pyproject.toml index 6de21f6..00dfb19 100644 --- a/core/pyproject.toml +++ b/core/pyproject.toml @@ -35,6 +35,7 @@ claude-code-talker = "claude_code_talker.server:main" claude-code-talker-hook = "claude_code_talker.hook_cli:main" claude-code-talker-setup = "claude_code_talker.setup:main" claude-code-talker-mcp-stdio = "claude_code_talker.mcp_stdio:main" +codetalker-mcp = "claude_code_talker.mcp_stdio:main" [tool.setuptools.packages.find] where = ["."] diff --git a/docs/integrations/README.md b/docs/integrations/README.md new file mode 100644 index 0000000..4097d8a --- /dev/null +++ b/docs/integrations/README.md @@ -0,0 +1,79 @@ +# CodeTalker — Multi-Platform AI-Coding Agent Integrations + +CodeTalker ships an MCP (Model Context Protocol) server that any MCP-compatible AI coding agent can connect to. Once connected, the agent can narrate its work aloud, switch narration modes, mute itself for long agentic loops, and (with Pro) use cloned voices and animated character avatars. + +This directory contains per-agent installation snippets so users can wire codetalker into their preferred AI-coding setup without hunting through docs. + +## Prerequisites (one time) + +```bash +pip install --user claude-code-talker +``` + +That installs both the daemon (`claude-code-talker`) and the MCP stdio shim (`codetalker-mcp`). The daemon runs locally on port 17832 by default; the shim auto-spawns the daemon when an agent first connects, so users don't need to start it manually. + +For voice models, run `claude-code-talker-setup` once to download Piper voices (~100 MB). + +## Per-agent integration guides + +| Agent | Integration mechanism | Guide | +|---|---|---| +| **Claude Code** (Anthropic) | Native hooks + MCP via plugin | [`claude-code.md`](claude-code.md) | +| **Cursor** | MCP via `.cursor/mcp.json` | [`cursor.md`](cursor.md) | +| **Cline** (VS Code) | MCP via `cline_mcp_settings.json` | [`cline.md`](cline.md) | +| **Continue.dev** | MCP via `config.yaml` | [`continue.md`](continue.md) | +| **Windsurf** (Codeium) | MCP via `mcp_config.json` | [`windsurf.md`](windsurf.md) | +| **Zed** | MCP via `settings.json` `context_servers` | [`zed.md`](zed.md) | +| **Codex CLI** (OpenAI) | MCP via `~/.codex/config.toml` | [`codex-cli.md`](codex-cli.md) | +| **Goose** (Block) | Extension via `~/.config/goose/` | [`goose.md`](goose.md) | +| **Roo Code** | MCP via VS Code settings | [`roo-code.md`](roo-code.md) | +| **Replit Agent** | MCP via Replit's MCP settings | [`replit.md`](replit.md) | +| **AWS Kiro** | MCP via Kiro's MCP config | [`kiro.md`](kiro.md) | +| **Google Antigravity** | MCP via Antigravity's MCP config | [`antigravity.md`](antigravity.md) | +| **Aider** | Bespoke CLI wrapper (not MCP) | [`aider.md`](aider.md) — coming in v1.x | +| **JetBrains AI Assistant** | Bespoke plugin (not MCP) | [`jetbrains.md`](jetbrains.md) — coming in v1.x | + +## What you get + +Once connected, the agent can call these MCP tools (free tier — no subscription required): + +- `tts_speak(text)` — speak arbitrary text +- `tts_set_mode(mode)` — switch between `direct` / `brief` / `live` / `trigger` +- `tts_status()` — get current state +- `tts_mute()` / `tts_unmute()` — silence without changing config +- `tts_list_voices(engine?)` — list available voices +- `tts_set_voice(voice, engine?)` — change active voice +- `tts_set_cadence(cadence)` — for `live` mode: `periodic` / `per_tool_call` / `per_cluster` / `significant_only` / `hybrid` +- `tts_shutdown()` — gracefully stop the daemon + +With a **Pro subscription** ($10/mo at [CodeTalker.opencircuit.studio](https://codetalker.opencircuit.studio)), additional tools unlock: + +- `attach_character(session_id, character_name)` — attach a character with cloned voice + animated 3D avatar +- `list_characters()` — show the character library +- (and platform-specific Pro features depending on the agent) + +## How the connection works + +``` +┌──────────────────┐ stdio MCP ┌─────────────────┐ HTTP+SSE ┌─────────────────┐ +│ Your AI agent │ ───────────────▶ │ codetalker-mcp │ ─────────────▶ │ codetalker │ +│ (Cursor / Cline /│ │ (stdio shim, │ │ daemon │ +│ Continue / ...) │ │ auto-spawns │ │ (Python, local) │ +└──────────────────┘ │ daemon) │ │ port 17832 │ + └─────────────────┘ └─────────────────┘ +``` + +The shim is short-lived per-session; the daemon is a singleton that survives across agent sessions. Multiple agents can connect to the same daemon simultaneously (e.g., Claude Code in one terminal + Cursor in another) and share state. + +## Troubleshooting + +- **"daemon failed to start"** — ensure `claude-code-talker` is on your PATH. Try `which claude-code-talker` (macOS/Linux) or `where.exe claude-code-talker` (Windows). If missing, run `pip install --user claude-code-talker` and ensure your Python user-scripts dir is on PATH. +- **"unknown tool"** — make sure your agent is using the latest version of codetalker. The tool list expanded in v0.2.0+. +- **No audio** — run `claude-code-talker-setup` to download voice models, or check that your system's default audio device is selected. +- **Daemon won't shut down** — `claude-code-talker stop` or kill the PID in `~/.claude-code-talker/daemon.pid`. + +For deeper issues, file at https://github.com/OpenCircuitDev/codetalker/issues. + +## Submitting to MCP registries + +CodeTalker is listed on several MCP discovery sites. See [`mcp-registries.md`](mcp-registries.md) for the submission metadata used for each registry. diff --git a/docs/integrations/aider.md b/docs/integrations/aider.md new file mode 100644 index 0000000..bf38282 --- /dev/null +++ b/docs/integrations/aider.md @@ -0,0 +1,45 @@ +# CodeTalker for Aider + +**Status:** Coming in v1.x (SP-10 of the launch master plan). + +Aider is a CLI-first AI pair-programming tool. It does not natively support MCP, so codetalker-for-Aider requires a bespoke adapter rather than the universal `codetalker-mcp` server. + +## Planned mechanism + +A new `codetalker-aider` CLI wrapper (Python console_script) that: + +1. Spawns Aider as a subprocess +2. Monitors Aider's stdout for the standard event markers (commit, /run, /shell, file diffs) +3. Pipes those events to the codetalker daemon's narration engine +4. Passes everything else through to the user's terminal transparently + +Usage will look like: + +```bash +codetalker-aider --model claude-sonnet-4-6 myrepo/ +``` + +Identical to running Aider directly, plus narration. + +## Why this approach + +Aider doesn't have an event/hook system that exposes "the agent just edited a file" or "the agent just ran a command" as discrete signals. The simplest universal approach is to wrap the CLI and pattern-match on output. + +Alternative: monitor Aider's git commits + `.aider.*.log` files. But that gives us less-granular events. + +## Timeline + +The Aider adapter is part of SP-10 in the launch master plan, scheduled after v1 launch. It's one of the two **Pro Plus** ($3/mo addon) platform integrations along with JetBrains AI Assistant. + +If you want to be notified when this lands: watch the [GitHub repo](https://github.com/OpenCircuitDev/codetalker) or subscribe to the launch newsletter at https://codetalker.opencircuit.studio. + +## Community workarounds (interim) + +A few community-built MCP wrappers for Aider exist (`disler/aider-mcp`, `danielscholl/aider-mcp`). These let MCP-speaking clients drive Aider through MCP tool calls. However, they don't solve the narration problem in the other direction — they let an agent USE Aider, not let Aider's events trigger narration. + +If you want narration for Aider TODAY, the manual workaround is: +1. Run `claude-code-talker serve` to start the daemon +2. In a separate terminal: `aider` (or whatever invocation you use) +3. Periodically run `claude-code-talker speak "Aider made an edit"` (or similar) when you want narration + +It's not seamless, but it works until v1.x ships the proper adapter. diff --git a/docs/integrations/antigravity.md b/docs/integrations/antigravity.md new file mode 100644 index 0000000..c0cd8c3 --- /dev/null +++ b/docs/integrations/antigravity.md @@ -0,0 +1,49 @@ +# CodeTalker for Google Antigravity + +Google Antigravity (public preview Nov 2025) is Gemini 3's agent platform — a VS Code OSS fork with a manager view for orchestrating multi-agent workflows. + +## Install + +### 1. Install the daemon + +```bash +pip install --user claude-code-talker +``` + +### 2. Add to Antigravity's MCP config + +Antigravity uses a standard MCP server config. Find the config file path in Antigravity's Settings → AI → MCP Servers (typically `~/.antigravity/mcp.json` or similar). + +```json +{ + "mcpServers": { + "codetalker": { + "command": "codetalker-mcp", + "args": [], + "env": {} + } + } +} +``` + +Or use the Settings UI directly: Add Server → Type: stdio → Command: `codetalker-mcp`. + +### 3. Restart Antigravity + +The agent + manager view pick up the new MCP server on launch. + +## Verify + +In Antigravity's manager view, look at the MCP servers panel — `codetalker` should appear with a green status indicator. + +In an agent chat: + +> Call codetalker.tts_status to report the current state. + +You should see the daemon's status text. + +## Notes specific to Antigravity + +- Antigravity's **manager view** orchestrates multiple Gemini 3 agents in parallel. Match this with codetalker's per-session settings (configure via the webui dashboard at http://localhost:17832): for each agent's session, set a different mode/cadence so the audio stream stays meaningful. +- Antigravity is free for individuals — codetalker's free tier complements that well. The Pro features ($10/mo) light up when you want character voices for differentiating agents audibly (e.g., "agent #1 sounds like Dr. Crow, agent #2 sounds like the Captain"). +- Antigravity supports multi-model (Claude Sonnet 4.6, GPT-OSS-120B, Gemini 3). codetalker is model-agnostic; narration triggers off hooks/MCP not model output. diff --git a/docs/integrations/claude-code.md b/docs/integrations/claude-code.md new file mode 100644 index 0000000..418286a --- /dev/null +++ b/docs/integrations/claude-code.md @@ -0,0 +1,43 @@ +# CodeTalker for Claude Code + +Claude Code is codetalker's original integration target — the experience is the most polished here. + +## Install + +Inside any Claude Code session: + +``` +/plugin marketplace add OpenCircuitDev/codetalker +/plugin install codetalker@codetalker +``` + +That's it. The plugin installs: +- The MCP server config (`claude-code-talker-mcp-stdio` invoked over stdio) +- Hook handlers for `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `Stop`, `Notification` +- Slash commands (`/codetalker:status`, `/codetalker:mute`, `/codetalker:mode`, etc.) +- A Claude self-modulation guide (see `claude-code-plugin/CLAUDE.md`) + +**Prerequisite (one time):** `pip install --user claude-code-talker`. + +## What you get (Claude Code-specific) + +Beyond the universal MCP toolset documented in the main [README](README.md), Claude Code gets: + +- **Automatic narration via hooks** — Claude Code fires hook events at every turn (`UserPromptSubmit` when you type, `PreToolUse` before each tool call, etc.). codetalker subscribes to these and narrates accordingly, with no model-side cooperation needed. +- **The `codetalker-narration` skill** — Claude is told when and how to write `## Audible ` blocks for codetalker to TTS. The skill content is fetched live from the daemon at session start, so the active tag list reflects user preferences from the webui dashboard. +- **Self-modulation** — the Claude self-modulation guide (`CLAUDE.md` in the plugin) tells Claude when to call `tts_set_mode(brief)` to spare you a long agentic loop, when to `tts_mute` if you ask it to be quiet, etc. +- **`/codetalker:status`, `/codetalker:mode`, `/codetalker:mute` slash commands** — quick controls without leaving the conversation. + +## Verify + +``` +/codetalker:status +``` + +This calls `mcp__codetalker__tts_status` and prints the current state. You should hear (and see) the response. + +## Notes specific to Claude Code + +- The plugin's hook handlers and the MCP server share state via the daemon — there's no race condition between "Claude hook fires" and "Claude calls MCP tool." +- The daemon survives across Claude Code sessions and across IDE restarts. To stop it: `/codetalker:stop` or `claude-code-talker stop`. +- For VS Code users who run Claude Code inside VS Code's terminal, **install the `extension/` package** instead of (or in addition to) the plugin. The extension adds a status bar widget, command palette entries, and secrets-to-keychain integration. Both can coexist — they share the same daemon. diff --git a/docs/integrations/cline.md b/docs/integrations/cline.md new file mode 100644 index 0000000..adfb2ce --- /dev/null +++ b/docs/integrations/cline.md @@ -0,0 +1,71 @@ +# CodeTalker for Cline + +Cline (the VS Code agent) supports MCP natively. Add codetalker to its MCP settings and Cline can narrate its work. + +## Install + +### 1. Install the daemon + +```bash +pip install --user claude-code-talker +``` + +### 2. Add to Cline's MCP config + +Open VS Code → Cline panel → MCP Servers icon (top-right) → "Configure MCP Servers" → opens `cline_mcp_settings.json`. + +Add the `codetalker` entry to `mcpServers`: + +```json +{ + "mcpServers": { + "codetalker": { + "command": "codetalker-mcp", + "args": [], + "env": {}, + "alwaysAllow": [], + "disabled": false + } + } +} +``` + +If you want Cline to call codetalker tools without per-call confirmation, add them to `alwaysAllow`: + +```json +"alwaysAllow": ["tts_set_mode", "tts_mute", "tts_unmute", "tts_status"] +``` + +(Don't auto-allow `tts_speak` — keeping it in the confirm-each-call list prevents surprise narration.) + +### 3. Reload Cline + +VS Code → Command Palette → "Cline: Restart" — or just restart VS Code. + +### 4. (Optional) Cline rules + +In Cline's Settings → Custom Instructions, add: + +``` +You have access to mcp__codetalker__* tools. Default to letting hooks narrate +automatically. Switch to brief mode (tts_set_mode brief) when starting a long +agentic loop, and back to direct/live afterwards. +``` + +## Verify + +In a Cline chat: + +> Call mcp__codetalker__tts_status and tell me what you find. + +Cline should call the tool and return the status text. + +## Troubleshooting + +- **"command not found"** — VS Code's MCP runs in a non-login shell that often misses user-scripts paths. Use the absolute path: `which codetalker-mcp` → paste into `command` field. +- **Tools missing after restart** — check Cline's "Output" panel (View → Output → "Cline") for MCP errors. + +## Notes specific to Cline + +- Cline's checkpoint feature interacts cleanly with codetalker — when you rewind to a checkpoint, codetalker's session state stays (it's stored in the daemon, not in Cline). +- If you use Cline's autonomous mode (long-running agent), set codetalker to `live` mode + `significant_only` cadence so you only hear about meaningful steps. diff --git a/docs/integrations/codex-cli.md b/docs/integrations/codex-cli.md new file mode 100644 index 0000000..1bcb3b7 --- /dev/null +++ b/docs/integrations/codex-cli.md @@ -0,0 +1,51 @@ +# CodeTalker for Codex CLI + +OpenAI Codex CLI (`@openai/codex`) added MCP support in late 2025. CodeTalker hooks in as an MCP server. + +## Install + +### 1. Install the daemon + +```bash +pip install --user claude-code-talker +``` + +### 2. Add to Codex's config + +Edit `~/.codex/config.toml`: + +```toml +[mcp_servers.codetalker] +command = "codetalker-mcp" +args = [] +``` + +If `codetalker-mcp` isn't on Codex's PATH (Codex CLI sometimes sandboxes its env), use absolute: + +```toml +[mcp_servers.codetalker] +command = "/Users/you/.local/bin/codetalker-mcp" +args = [] +``` + +### 3. Restart Codex + +```bash +codex --version # verify Codex picks up the new MCP server +``` + +In an interactive session, run `/mcp list` (if Codex's CLI supports it) to confirm codetalker is loaded. + +## Verify + +In a Codex CLI session: + +> Call codetalker tts_status. + +Codex should invoke the MCP tool and return its output. + +## Notes specific to Codex CLI + +- Codex CLI ships with Windows PowerShell + WSL2 sandbox support as of Q1 2026 — codetalker's daemon runs on the host, so the MCP shim crosses the sandbox boundary via stdio. This works in WSL2 if Python is installed on the WSL side. +- Codex CLI's container-caching speedup (90% faster cold-starts as of 2026) doesn't affect codetalker — the shim is fast either way; the daemon is a long-running singleton. +- If you primarily use Codex Cloud (the cloud-hosted variant), codetalker won't work there — codetalker is local-first by design (audio plays on your machine). Run Codex locally or via Codex CLI for codetalker integration. diff --git a/docs/integrations/continue.md b/docs/integrations/continue.md new file mode 100644 index 0000000..50bf96a --- /dev/null +++ b/docs/integrations/continue.md @@ -0,0 +1,53 @@ +# CodeTalker for Continue.dev + +Continue (the open-source VS Code / JetBrains assistant) speaks MCP natively (via the YAML config). + +## Install + +### 1. Install the daemon + +```bash +pip install --user claude-code-talker +``` + +### 2. Add to Continue's config + +Edit `~/.continue/config.yaml` (or your assistant's specific config file): + +```yaml +mcpServers: + - name: codetalker + command: codetalker-mcp + args: [] + env: {} +``` + +If you maintain an assistant via [Continue Hub](https://hub.continue.dev), add codetalker as a tool block on the hub. The codetalker assistant page is at https://hub.continue.dev/assistants/codetalker (TBD — submission planned in SP-7 of the launch master plan). + +### 3. Reload Continue + +VS Code → Command Palette → "Continue: Reload" — or restart your IDE. + +### 4. (Optional) Continue rules block + +In your `config.yaml`, you can add a system message guiding Continue's use of codetalker: + +```yaml +systemMessage: | + You have access to codetalker tools (mcp tools from the codetalker MCP server). + Use tts_set_mode to switch between direct/brief/live based on workload. + Don't call tts_speak directly — narration happens via hooks. +``` + +## Verify + +In a Continue chat: + +> List the MCP tools available to you. + +You should see `codetalker.tts_speak`, `codetalker.tts_set_mode`, and the rest. + +## Notes specific to Continue + +- Continue's "Quick Edit" command (cmd-I) doesn't typically need narration — it's fast. Save codetalker for "Chat" interactions and the autonomous "Agent" mode. +- Continue supports MCP `resources` and `prompts` in addition to `tools`. CodeTalker currently exposes tools only; resources/prompts may come in v1.x. diff --git a/docs/integrations/cursor.md b/docs/integrations/cursor.md new file mode 100644 index 0000000..704c171 --- /dev/null +++ b/docs/integrations/cursor.md @@ -0,0 +1,75 @@ +# CodeTalker for Cursor + +Cursor speaks MCP natively. Add codetalker to your Cursor MCP config and the agent can narrate its work aloud. + +## Install + +### 1. Install the daemon + +```bash +pip install --user claude-code-talker +``` + +Verify `codetalker-mcp` is on your PATH: + +```bash +which codetalker-mcp # macOS/Linux +where.exe codetalker-mcp # Windows +``` + +### 2. Add to Cursor's MCP config + +**Global config** (recommended) — applies across all Cursor projects: + +Edit `~/.cursor/mcp.json` (create if missing): + +```json +{ + "mcpServers": { + "codetalker": { + "command": "codetalker-mcp", + "args": [], + "env": {} + } + } +} +``` + +**Per-project config** — `.cursor/mcp.json` in your project root, same shape. + +### 3. Restart Cursor + +Cursor loads MCP servers at startup. After restart, the agent has access to codetalker tools (`mcp__codetalker__tts_*`). + +### 4. (Optional) Tell Cursor when to use codetalker + +In Cursor's Settings → AI → Rules, add: + +``` +You have access to mcp__codetalker__* tools. When you're about to chain many tool +calls without user input, call mcp__codetalker__tts_set_mode with mode="brief" +so the user gets a summary instead of every step. Switch back when you're done. +``` + +This is optional — without it, Cursor's narration just uses whatever mode the user set in codetalker's webui dashboard. + +## Verify + +After restart, in a Cursor chat: + +> Use the codetalker tts_status tool to report current state. + +You should hear (or see in chat) the daemon's status. + +## Troubleshooting + +- **Cursor doesn't see the tools after restart** — open Cursor's MCP status panel (Settings → MCP) and check for errors. The most common cause is `codetalker-mcp` not being on the PATH that Cursor uses (Cursor sometimes uses a different shell env than your terminal). +- **Workaround for PATH issues** — use the absolute path in the config: + ```json + "command": "/Users/you/.local/bin/codetalker-mcp" + ``` +- **Daemon spawn fails** — check that you can run `claude-code-talker serve` manually from a terminal. If that works but the shim's auto-spawn doesn't, file an issue with the shim's stderr output (visible in Cursor's MCP logs). + +## What's next + +If you want Pro features (character voices, animated avatars), subscribe at [CodeTalker.opencircuit.studio](https://codetalker.opencircuit.studio) — your existing codetalker installation will pick up the entitlement after sign-in. diff --git a/docs/integrations/goose.md b/docs/integrations/goose.md new file mode 100644 index 0000000..23b03b1 --- /dev/null +++ b/docs/integrations/goose.md @@ -0,0 +1,49 @@ +# CodeTalker for Goose + +Goose (Block / AAIF) is an open-source AI agent CLI with a robust extension system. It supports MCP via its extension mechanism. + +## Install + +### 1. Install the daemon + +```bash +pip install --user claude-code-talker +``` + +### 2. Add codetalker as a Goose extension + +Edit `~/.config/goose/config.yaml`: + +```yaml +extensions: + codetalker: + type: stdio + enabled: true + cmd: codetalker-mcp + args: [] + envs: {} +``` + +Alternative: use `goose configure` from the CLI — it has an interactive add-extension flow. + +### 3. Verify + +```bash +goose session --resume # or start a new session +``` + +Inside the session, ask: + +> What MCP tools do you have access to? + +Goose should list the codetalker tools. + +## Notes specific to Goose + +- Goose's "developer mode" and "automated mode" both work with codetalker. In automated mode, codetalker's `brief` setting is recommended — Goose can run long chains, and narrating each step gets noisy. +- Goose's `multi-provider` support (OpenAI, Anthropic, Gemini, local LLMs via Ollama) is orthogonal to codetalker — narration works regardless of which LLM Goose is using. +- If you're on Goose Desktop (the GUI app), MCP servers are configured the same way; the GUI just edits the same YAML. + +## What about Goose's own TTS? + +Goose has a community-built voice extension. If you use both, you'll get double-narration. Pick one — codetalker has more configurability (modes, cadence, character voices) but the Goose-native extension has tighter Goose-specific event integration. Run `goose extensions list` to see what's enabled. diff --git a/docs/integrations/jetbrains.md b/docs/integrations/jetbrains.md new file mode 100644 index 0000000..f03e498 --- /dev/null +++ b/docs/integrations/jetbrains.md @@ -0,0 +1,39 @@ +# CodeTalker for JetBrains AI Assistant + +**Status:** Coming in v1.x (SP-10 of the launch master plan). + +JetBrains AI Assistant ships with the JetBrains IDE family (IntelliJ IDEA, PyCharm, WebStorm, GoLand, Rider, etc.). It is not MCP-native as of mid-2026, so codetalker-for-JetBrains requires a bespoke plugin. + +## Planned mechanism + +A JetBrains IDE plugin (Kotlin, built against the IntelliJ Platform SDK) that: + +1. Listens for JetBrains AI Assistant events (chat message, code action invoked, agent step completed) +2. Invokes the local codetalker daemon's HTTP narration endpoint +3. Lives in plugins.jetbrains.com under the OpenCircuit publisher + +Distribution will be via the JetBrains Plugin Marketplace — search "CodeTalker" inside any JetBrains IDE's Settings → Plugins → Marketplace. + +## Why this approach + +JetBrains AI Assistant uses the JetBrains plugin extension points, not an open protocol. To integrate, codetalker needs to be a JetBrains plugin. The plugin will be thin — most logic lives in the codetalker daemon; the plugin is just an event listener + REST caller. + +## Timeline + +The JetBrains plugin is part of SP-10 in the launch master plan, scheduled after v1 launch. It's one of the two **Pro Plus** ($3/mo addon) platform integrations along with Aider. + +## What about Junie? + +JetBrains shipped **Junie** (April 2025) — an autonomous coding agent that runs longer-form tasks. Junie uses the same plugin extension points as JetBrains AI Assistant, so the codetalker plugin will support both. + +Junie's autonomous-mode narration is a perfect fit for codetalker's `live` mode + `cadence=significant_only` — let Junie run for an hour and only hear about the milestones. + +## Notes for the JetBrains AI Assistant free tier + +JetBrains AI Assistant moved to a free tier in 2025.1+ (with limited cloud quota). codetalker has no quota interaction — narration is local and unmetered. The Pro Plus subscription needed to unlock the JetBrains adapter is separate from any JetBrains AI subscription. + +## What about other JetBrains AI products? + +- **JetBrains Junie** — same plugin (see above) +- **Sourcegraph Cody** for JetBrains — separate plugin; codetalker dropped Cody support after Sourcegraph moved Cody to enterprise-only ($59/user/mo min) in July 2025 +- **GitHub Copilot for JetBrains** — uses JetBrains' Copilot plugin; narration via that path is being scoped as part of SP-10's Copilot Chat adapter (covered separately) diff --git a/docs/integrations/kiro.md b/docs/integrations/kiro.md new file mode 100644 index 0000000..2a5a690 --- /dev/null +++ b/docs/integrations/kiro.md @@ -0,0 +1,45 @@ +# CodeTalker for AWS Kiro + +AWS Kiro (public preview July 2025) is a VS Code OSS fork with spec-driven development. It supports MCP for multimodal context. + +## Install + +### 1. Install the daemon + +```bash +pip install --user claude-code-talker +``` + +### 2. Add to Kiro's MCP config + +Kiro stores MCP config alongside its other settings. Edit `~/.aws/kiro/mcp.json` (or use Kiro's Settings → MCP Servers UI): + +```json +{ + "mcpServers": { + "codetalker": { + "command": "codetalker-mcp", + "args": [], + "env": {} + } + } +} +``` + +### 3. Restart Kiro + +Kiro's agent panel will pick up the new MCP server. + +## Verify + +In Kiro chat: + +> List the MCP context sources available. + +You should see `codetalker` with its tools. + +## Notes specific to Kiro + +- Kiro's spec-driven workflow generates a design + tasks file before coding. If you narrate during the spec-generation step, codetalker's `brief` mode keeps the narration scoped to milestone events (spec saved, tasks generated, etc.) instead of every micro-step. +- Kiro currently supports Python + JavaScript only (as of mid-2026). codetalker's MCP integration works regardless of the target language. +- Kiro is powered by Claude Sonnet/Opus. codetalker has no special handling for any specific model — narration works via hooks/MCP, not via the model's output channel. diff --git a/docs/integrations/mcp-registries.md b/docs/integrations/mcp-registries.md new file mode 100644 index 0000000..74e0b35 --- /dev/null +++ b/docs/integrations/mcp-registries.md @@ -0,0 +1,85 @@ +# MCP Registry Submissions + +CodeTalker is listed (or planned for listing) on the following MCP registries. This file is the **source of truth** for the listing metadata so submissions stay consistent across registries. + +## Canonical metadata + +```yaml +name: codetalker +display_name: CodeTalker +version: 0.2.0 # bumps with each PyPI release of claude-code-talker +description: | + Multi-mode voice / TTS narration companion for AI coding agents. Connects to + Claude Code, Cursor, Cline, Continue, Windsurf, Zed, Codex CLI, Goose, AWS + Kiro, Google Antigravity, Roo Code, and Replit Agent via MCP. Free tier + includes 4 narration modes (direct/brief/live/trigger), 5 cadence patterns + for live mode, voice picker with Piper TTS, hook-driven narration, and a + webui dashboard. Pro tier ($10/mo) adds character system with local voice + cloning and animated 3D avatars. +license: MIT +homepage: https://codetalker.opencircuit.studio +repository: https://github.com/OpenCircuitDev/codetalker +maintainer: Open Circuit Studio +contact: hello@opencircuit.studio +keywords: + - tts + - voice + - narration + - ai-coding + - accessibility + - claude-code + - cursor + - cline + - mcp +transport: + - stdio + - sse # via daemon's http endpoint +install: + pip: claude-code-talker + entry_point: codetalker-mcp +runtime: + language: python + python_min: "3.11" +categories: + - productivity + - accessibility + - developer-tools +``` + +## Per-registry submission status + +| Registry | URL | Status | Notes | +|---|---|---|---| +| **registry.modelcontextprotocol.io** (official) | https://registry.modelcontextprotocol.io | TODO — submit at v1 launch | Anthropic's official registry, Sept 2025 launch. Best SEO. Submit via their GitHub PR flow against `modelcontextprotocol/registry`. | +| **PulseMCP** | https://www.pulsemcp.com | TODO — submit at v1 launch | Hand-reviewed, 14K+ servers. Form-based submission at pulsemcp.com/add. | +| **MCP.so** | https://mcp.so | TODO — submit at v1 launch | Largest catalog by volume. Self-serve listing via mcp.so/add. | +| **mcpservers.org** | https://mcpservers.org | TODO — submit at v1 launch | Curated 450+. PR to their GitHub repo. | +| **GitHub MCP Registry** | https://github.com/mcp | TODO — submit at v1 launch | GitHub's curated registry, Sept 2025. PR flow. | +| **modelcontextprotocol/servers** | https://github.com/modelcontextprotocol/servers | TODO — submit at v1 launch | Official awesome-list. PR adding codetalker to the third-party section. | +| **Anthropic Claude Marketplace** | https://claude.com/plugins | TODO — submit at v1 launch | Already have the `claude-code-plugin/` set up. Submit at v1. | +| **Continue Hub** | https://hub.continue.dev | TODO — submit at v1 launch | Continue's first-party assistant + MCP hub. Submit at hub.continue.dev/submit. | + +## Submission checklist (do at v1 launch) + +For each registry, file the listing with the canonical metadata above plus registry-specific niceties: + +- [ ] Banner / logo PNG (1200x630 for social previews) +- [ ] Square logo PNG (256x256) +- [ ] 30-second demo GIF or MP4 showing codetalker narrating a Claude Code session +- [ ] Screenshots: webui dashboard, Pro Android session detail, character library +- [ ] Pricing page link +- [ ] GitHub issues link for support +- [ ] Discord / community link (TBD pending SP-9 launch sequence) + +## Per-platform integration docs (linked from registry listings) + +Each registry submission should link to the relevant per-agent integration guide so users can install codetalker with one click on their target platform. Use the live URLs at https://codetalker.opencircuit.studio/integrations/ (planned in SP-6 of the launch master plan). + +## When metadata changes + +When bumping the version, releasing a new feature, or rebranding: +1. Update this file first. +2. Submit updates to each registry that supports it (most do via GitHub PR or admin form). +3. PulseMCP and mcpservers.org may re-review; the others auto-update from your manifest. + +The weekly-landscape-scan routine (see `.claude/routines/weekly-landscape-scan.md`) watches for NEW MCP registries that emerge. If a new high-traffic registry appears, it'll generate an integration spec for adding codetalker there. diff --git a/docs/integrations/replit.md b/docs/integrations/replit.md new file mode 100644 index 0000000..9e103ba --- /dev/null +++ b/docs/integrations/replit.md @@ -0,0 +1,57 @@ +# CodeTalker for Replit Agent + +Replit Agent 3 (Jan 2026) supports MCP for both custom and remote servers, with a 200-minute autonomous runtime per session. + +## Important caveat: Replit is cloud-hosted + +CodeTalker is **local-first** — the daemon runs on your machine and plays audio through your speakers. Replit Agent runs in Replit's cloud. So a stdio MCP connection between them isn't viable. + +**Workaround:** Run the codetalker daemon locally with its HTTP+SSE endpoint exposed, then configure Replit Agent to connect to that remote MCP server. + +## Install + +### 1. Install the daemon locally + +```bash +pip install --user claude-code-talker +``` + +### 2. Run the daemon with a public endpoint + +Use a tunneling tool like `ngrok` to expose your local daemon's port: + +```bash +claude-code-talker serve +ngrok http 17832 +# note the https://abc123.ngrok.app URL ngrok prints +``` + +### 3. Add the remote MCP server to Replit Agent + +In Replit Agent's MCP settings (Settings → MCP Connectors), add: + +- **Type:** Remote (SSE) +- **URL:** `https://abc123.ngrok.app/sse` +- **Name:** `codetalker` + +### 4. (Optional) Add authentication + +The codetalker daemon doesn't ship with auth out of the box (it assumes local-only). For a public tunnel, you'll want either: +- A pairing token (codetalker's companion pairing system — see `docs/companion-pairing.md`) +- An ngrok password (set via `ngrok http 17832 --basic-auth user:pass`) + matching auth header in Replit's MCP config + +**Security warning:** If you expose codetalker via ngrok without auth, anyone with the URL can make your machine narrate things. Treat the URL as a secret. + +## Verify + +In Replit Agent: + +> Call codetalker's tts_status tool. + +You should hear the narration locally (via your machine's speakers) and see the status text in Replit's chat. + +## Notes specific to Replit + +- Replit Agent's 200-minute autonomous runtime is long. codetalker's `live` mode with `cadence=per_cluster` gives you a useful narration cadence without spamming. +- Replit Agent's connectors platform (24 pre-built integrations as of 2026) is more suited to "do something in $external_service" workflows than to "narrate work locally," so codetalker is a unique fit for the auditory-feedback niche. +- If ngrok isn't an option (corporate firewall), consider running Replit's "code in browser" but executing the agent locally via codetalker's daemon + Replit's CLI export. Or wait for a future codetalker cloud edition. diff --git a/docs/integrations/roo-code.md b/docs/integrations/roo-code.md new file mode 100644 index 0000000..50ed656 --- /dev/null +++ b/docs/integrations/roo-code.md @@ -0,0 +1,45 @@ +# CodeTalker for Roo Code + +Roo Code is a community-driven fork of Cline focused on experimental features. MCP integration follows Cline's pattern. + +## Install + +### 1. Install the daemon + +```bash +pip install --user claude-code-talker +``` + +### 2. Add to Roo Code's MCP config + +VS Code → Roo Code panel → MCP Servers → "Configure" → edit the JSON: + +```json +{ + "mcpServers": { + "codetalker": { + "command": "codetalker-mcp", + "args": [], + "env": {}, + "alwaysAllow": ["tts_status", "tts_set_mode", "tts_mute", "tts_unmute"] + } + } +} +``` + +### 3. Reload Roo Code + +VS Code → Command Palette → "Roo Code: Reload" or restart VS Code. + +## Verify + +In Roo Code chat: + +> What MCP servers are connected? + +Roo Code should list `codetalker` with the tools count. + +## Notes specific to Roo Code + +- Roo Code merges new features faster than upstream Cline — if you hit any MCP-handling quirk, check the Roo Code Discord before filing on the codetalker repo. +- Roo Code's autonomous mode is more aggressive than Cline's default. Pair codetalker's `live` mode with `cadence=significant_only` to filter narration to important steps. diff --git a/docs/integrations/windsurf.md b/docs/integrations/windsurf.md new file mode 100644 index 0000000..54b4236 --- /dev/null +++ b/docs/integrations/windsurf.md @@ -0,0 +1,53 @@ +# CodeTalker for Windsurf + +Windsurf (formerly Codeium) supports MCP via Cascade — its agent integrates with MCP servers from Wave 3 (Feb 2025) onward. + +## Install + +### 1. Install the daemon + +```bash +pip install --user claude-code-talker +``` + +### 2. Add to Windsurf's MCP config + +Edit `~/.codeium/windsurf/mcp_config.json`: + +```json +{ + "mcpServers": { + "codetalker": { + "command": "codetalker-mcp", + "args": [], + "env": {} + } + } +} +``` + +Or use Windsurf's Settings → MCP Servers → "Add Server" UI: +- **Name:** `codetalker` +- **Command:** `codetalker-mcp` +- **Args:** *(empty)* + +### 3. Restart Windsurf + +The MCP server is loaded at Cascade startup. Restart Windsurf to pick up the new config. + +### 4. Cascade and the 100-tool ceiling + +Windsurf enforces a hard limit of 100 tools per Cascade session. CodeTalker contributes 9 agent-facing tools (plus 5 internal hook handlers not exposed via the shim). If you have many other MCP servers attached, prioritize codetalker on the "active" list in MCP settings. + +## Verify + +In a Cascade chat: + +> Call the codetalker tts_status tool to report state. + +Look for a blue-checkmark badge on the codetalker server in MCP settings — that means Windsurf verified the server passes their basic compatibility check. + +## Notes specific to Windsurf + +- Cascade's "Write" mode involves longer agentic loops than its "Chat" mode. Switch codetalker to `live` mode (`tts_set_mode live`) when starting a Write task, then back to `direct` for chat. +- If you toggle Cascade between local models and Anthropic Claude / OpenAI GPT, codetalker keeps working — it doesn't care which model is on the other end of MCP. diff --git a/docs/integrations/zed.md b/docs/integrations/zed.md new file mode 100644 index 0000000..b996b76 --- /dev/null +++ b/docs/integrations/zed.md @@ -0,0 +1,63 @@ +# CodeTalker for Zed + +Zed (1.0, released April 2026) supports MCP via its `context_servers` config. + +## Install + +### 1. Install the daemon + +```bash +pip install --user claude-code-talker +``` + +### 2. Add to Zed's settings + +Open Zed → Settings (cmd-,) → `settings.json`. Add a `context_servers` block: + +```json +{ + "context_servers": { + "codetalker": { + "command": { + "path": "codetalker-mcp", + "args": [], + "env": {} + } + } + } +} +``` + +If `codetalker-mcp` isn't on Zed's PATH, use the absolute path: + +```json +"path": "/Users/you/.local/bin/codetalker-mcp" +``` + +### 3. Restart Zed + +Zed's Agent Panel will discover the new context server on startup. + +### 4. Per-action permissions + +Zed deliberately requires explicit permission for each tool call (its "permissioned per-action" model). The first time the Agent Panel wants to call `mcp__codetalker__tts_speak`, you'll see a permission prompt — accept "allow always" for the tools you trust. + +Recommended per-action allowlist: +- `tts_status` — always allow +- `tts_set_mode` — always allow +- `tts_mute` / `tts_unmute` — always allow +- `tts_speak` — ask each time (prevents surprise narration) +- `tts_shutdown` — ask each time (rare) + +## Verify + +In Zed's Agent Panel: + +> Use codetalker.tts_status and tell me the state. + +You should see a permission prompt followed by the status output. + +## Notes specific to Zed + +- Zed 1.0's **parallel agents** feature is a perfect match for codetalker — when multiple agents run in parallel, codetalker's per-session mode + cadence settings (via the webui dashboard) let you narrate one of them in `live` mode while the others are `brief` or muted. Set this up via `claude-code-talker serve` + open the dashboard at http://localhost:17832. +- If you use Zed's collaboration feature (shared editing), only the host's codetalker daemon narrates — codetalker is local-first by design.