OpenCircuitDev · OpenCircuitDev · May 10, 2026 · May 10, 2026
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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 <Tag>` 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
@@ -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
@@ -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.