agent-talk
Bridge Codex/Claude Desktop conversations with DSH Web via MCP so you can delegate, monitor, and coordinate AI tasks.
List native Codex, Claude, and DSH conversations, optionally filtered by exact directory.
List existing DSH workspaces and their directories.
Bind exact conversations and directories to aliases.
Create DSH conversations with optional workspace, title, model defaults, and automatic return to an initiating conversation.
Send prompts and up to 30 local file paths with request-ID deduplication and persistent queuing.
Read recent messages, native state, progress, final replies, questions, and return-route receipts.
Follow DSH final replies, questions, abnormal endings, and user interventions back to the initiating Codex/Claude conversation.
Inspect and answer ordinary DSH questions; permission approvals remain in DSH Web.
Pause, resume, or mark reviewed tasks complete.
Inspect delivery outbox, route errors, and event connectivity.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@agent-talk Delegate the code review to DSH and bring back the results."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Agent Talk MCP
Let your AI conversations work together — without the copy and paste.
A lightweight, local MCP bridge between existing Codex Desktop / Claude Desktop Code conversations and DSH Web.
Why it exists
You discuss a task with one AI, write a plan, paste it into another AI, then copy the result back for review. Agent Talk handles that handoff while keeping the conversations in their original apps.
Use your existing Codex or Claude conversation to delegate work to DSH, receive questions and results, and decide what happens next. The bridge does not prescribe a development methodology, repository layout, or fixed planner/executor prompt. It also works for research, writing, and other local tasks.
flowchart LR
U[You] <--> P[Existing Codex or Claude conversation]
P <-->|MCP tools and native return messages| M[Agent Talk MCP]
M <-->|Local DSH API| D[DSH Web conversations]
M --- S[(Local SQLite state)]Related MCP server: codex-chatgpt-bridge
What you can do
Capability | Behavior |
Use existing conversations | Bind exact native conversation IDs and directories; continue chatting in the original apps. |
Create DSH conversations | Choose an existing DSH workspace by name, or start in a local directory. |
Delegate with local files | Send a prompt and absolute paths to Markdown, images, PDFs, or other material. The recipient reads the files using its own capabilities. |
Receive results and questions | New DSH conversations require a return destination by default. Ordinary questions can be answered from the initiating conversation. |
Inspect progress | Read recent messages, tool activity, native state, and delivery receipts. |
Coordinate several tasks | Assign separate DSH conversations to independent work while keeping one initiating conversation per return route. |
Pause and finish | Pause one task without pausing the others; mark reviewed work complete to prevent reuse. |
Renew DSH credentials | A small DSH extension supplies the local login URL; the bridge renews its cookie when needed. |
Scope: create native Codex/Claude Desktop conversations and send tasks and follow-up answers. Existing DSH workflows remain compatible; no replacement CLI sessions or automatic archiving.
Requirements and compatibility
This is an early, source-installed release (0.5.0), intended for a trusted local machine.
macOS is the currently supported environment. The Claude native adapter is macOS-only; Windows/Linux support has not been validated.
Node.js 22.13 or later and npm. Node.js 22.23.2 was used for local verification. Node's SQLite experimental warning may appear.
Codex Desktop and/or Claude Desktop Code, signed in and able to run a local stdio MCP server. Regular Claude web chats are not supported by this adapter.
A working DSH Web installation on the same machine, with access to the same local files.
The native apps and the receiving conversation must remain available for automatic return.
Earlier DSH verification used Claude Code 2.1.280 and DSH 0.1.7-rc.1, plus the installed Codex Desktop. Bidirectional desktop verification on 2026-10-10 used Claude Code 2.1.295; see the sanitized local verification record. These are compatibility observations, not a guarantee for every release. Native IPC and DSH RPC interfaces can change independently of MCP.
Codex and Claude Desktop conversations
Version 0.5 supports creating native Codex and Claude Desktop Code conversations, sending tasks and follow-up answers to an exact bound conversation, and returning final replies. Existing DSH routes remain compatible.
Use Codex Desktop's signed bundled Node runtime for Agent Talk in both clients (for example /Applications/ChatGPT.app/Contents/Resources/cua_node/bin/node). Forward CODEX_APP_TOOLS_PIPE_PATH and CODEX_THREAD_ID through the Codex MCP entry's env_vars, then connect Agent Talk from Codex once to provide the private Desktop relay. Reconnect affected MCP clients after an update.
Bind your own session with talk_list / talk_bind. Create the counterpart with explicit app: "codex" or "claude", an existing trusted project cwd, a fresh stable UUID requestId, and your alias in replyTo. Creation sends only a ready handshake. Send work with talk_send, supplying your alias as sender; continue questions and answers in the same destination. talk_read supports all three clients.
Claude creation currently requires macOS Accessibility/Automation access, an already-running Code session in the target project, and a visible sidebar project. It never trusts a directory, changes permission mode, overwrites an unsent draft, or guesses another recipient. title applies to Codex/DSH; Claude names its own task. A creation with an uncertain outcome is only observed, never replayed. A confirmed pre-Send failure may recover its original draft. Desktop return routes have a separate polling lease so older DSH clients can remain connected during an upgrade.
Quick start
1. Install the source
git clone https://github.com/YanZiBin/agent-talk-mcp.git
cd agent-talk-mcp
npm ci --ignore-scripts
npm run check
npm run smokeThe smoke test uses temporary state and a local mock DSH service. It does not send messages to your AI conversations.
Keep the checkout in a stable location: client configurations and the DSH extension will reference its absolute path. There is no npm package installation required; private: true intentionally prevents accidental npm publication.
2. Connect DSH and enable credential renewal
Start your existing DSH installation with dsh web. Generate the extension URL from the repository root:
node --input-type=module -e 'import { pathToFileURL } from "node:url"; import path from "node:path"; console.log(pathToFileURL(path.resolve("src/dsh-auth-plugin.mjs")).href)'In the verified DSH version, the Web profile patch file is ~/.dsh/profiles/web/cordis.patch.yml. Back it up, then append the following item to its existing YAML patch list, replacing the example URL with the command's output. Preserve existing entries and do not add a duplicate agent-talk-auth item. If the file does not exist, create its parent directory and a file containing this list item.
- insert:
- id: agent-talk-auth
name: "file:///absolute/path/to/agent-talk-mcp/src/dsh-auth-plugin.mjs"Restart DSH Web, or use its native profile reload mechanism. This is a DSH Web extension, not a second MCP server to install in DSH.
The extension obtains a login URL from DSH's own connection.authenticatedUrl, saves it privately, and checks credentials every hour. The bridge renews when the cookie has less than 12 hours left, the login URL changes, or authentication is rejected. You do not need to paste a fresh token each time DSH restarts.
If the extension is not available, save the local login URL printed by DSH into work/dsh-login-url.txt, then run:
mkdir -p work
chmod 700 work
# Save the login URL into work/dsh-login-url.txt using your editor.
chmod 600 work/dsh-login-url.txt
npm run connect:dsh < work/dsh-login-url.txtThe script does not print tokens or cookies. Do not put the login URL in shell arguments, issues, or commits. Manual login alone does not install automatic renewal; enable the DSH extension for that.
3. Register with Codex and/or Claude Code
From the repository root, in a shell where the relevant client CLI is installed:
AGENT_TALK_NODE="$(command -v node)"
AGENT_TALK_DIR="$PWD"
# Codex
codex mcp add agent-talk -- "$AGENT_TALK_NODE" "$AGENT_TALK_DIR/src/server.mjs"
# Claude Code, including its Desktop Code environment
claude mcp add --transport stdio --scope user agent-talk -- "$AGENT_TALK_NODE" "$AGENT_TALK_DIR/src/server.mjs"Install only the entries for the clients you use. Alternatively, merge the following entry into the corresponding configuration, substituting absolute paths.
Codex — ~/.codex/config.toml:
[mcp_servers.agent-talk]
command = "/absolute/path/to/node"
args = ["/absolute/path/to/agent-talk-mcp/src/server.mjs"]Claude Code — user-level MCP configuration:
{
"mcpServers": {
"agent-talk": {
"type": "stdio",
"command": "/absolute/path/to/node",
"args": ["/absolute/path/to/agent-talk-mcp/src/server.mjs"]
}
}
}Do not replace your entire configuration with these snippets. Restart or reconnect the clients after setup or source updates. Each client launches its own MCP process; they share local state. No separate boot-time daemon is installed. npm start is a stdio server entry point, not an interactive chat command.
4. Try it in a conversation
List the DSH workspaces available on this machine.
Then:
Create a conversation in the DSH workspace “MyProject”. Ask it to summarize the project without modifying files. Return its questions and result to this conversation, and give me your assessment.
For a development task:
Give DSH the instructions in
/absolute/path/to/task.md. Use the “MyProject” workspace. Bring questions and results back here; review the result and ask for revisions as needed. Ask me when a decision is mine to make.
You normally do not need to name the MCP explicitly. The AI selects tools from their descriptions. Tool guidance currently uses Simplified Chinese and instructs clients to follow the user's language; the documentation is available in both English and Simplified Chinese.
How coordination works
The initiating AI identifies its exact native conversation with
talk_listand binds it withtalk_bind. It must not guess from a title alone.It creates a DSH conversation with
talk_create, supplyingreplyToas its own bound alias. Return is enabled as part of creation; a secondtalk_followcall is unnecessary.It sends the task with
talk_send, using a stable UUID for the request. Creation itself sends no task.DSH runs in its original conversation. New final replies, ordinary questions, abnormal endings, and direct user interventions can return to the initiator.
The initiator interprets the result in the context of the user's goal. It should summarize from its own perspective, distinguish reported claims from verified facts, and quote verbatim only when requested.
Revisions can continue in the same executor conversation. Once reviewed work is marked
completed, use a new conversation for the next task.
autoReturn: false explicitly opts out when creating a conversation and must not be combined with replyTo. Existing DSH conversations can be bound and then linked with talk_follow; starting a follow watches new events, not the entire previous history. New defaults do not retroactively enable old routes.
Workspace names must match exactly. Missing names produce an error; duplicate names require an exact cwd. If workspaceName and cwd are both provided, they must agree. Put a separate execution/worktree path in the task instructions. Without a workspace name, cwd creates an ungrouped DSH conversation.
MCP tools
Tool | Purpose |
| List native conversations, optionally filtered by exact directory. |
| Read existing DSH workspace names, directories, and conversation counts. |
| Bind an exact native conversation and directory to a stable alias. |
| Read DSH's available models, their reasoning efforts, and fast-tier support. |
| Create a native Codex/Claude Desktop conversation, or a DSH conversation, with automatic return by default; DSH-only optional |
| Send a prompt and local file paths to a DSH conversation with request-ID deduplication. Codex and Claude conversations do not message each other directly. |
| Read a DSH conversation's recent messages, progress, native state, questions, and return status. |
| Enable or disable a DSH → initiating conversation return route. |
| Inspect ordinary questions and permission requests. |
| Answer ordinary questions; never grant permission approvals. |
| Pause, explicitly resume, or mark reviewed work complete. |
| Inspect recent delivery receipts, route errors, and event connectivity. |
Aliases accept 1–64 ASCII letters, digits, underscores, or hyphens. Request IDs must be UUIDs. File references must be existing absolute local paths.
Delivery states and stopping
State | Meaning / action |
| Not yet sent. Busy or temporarily unavailable recipients wait in a persistent queue. |
| The native app accepted the message. This does not mean the task is complete or reviewed. |
| The exact message was found in the native recipient's transcript. |
| The native recipient retained the message but has not admitted it to the model. Inspect the original client; do not resend. |
| The outcome is unconfirmed. Inspect the conversation before taking further action; no automatic replay. |
| The native adapter or recipient rejected the request or lacks support. |
| An unsent message was cancelled after stopping, completion, route changes, or a question being resolved. |
talk_read.returnRoute shows whether return is enabled; lastReturn shows its latest receipt. A held receipt is not evidence that return is disabled. Its exact internal cause is not supplied by the receipt.
conversation.state controls bridge delivery; nativeStatus describes the native app. They are separate. Native Stop detection latches bridge delivery as paused. Explicit active resumes delivery; a correction in the native app alone does not silently resume it. Pausing DSH requests native cancellation and cancels stale queued prompts. Pausing a Codex/Claude alias gates bridge messages only, not its ongoing model turn.
Privacy, runtime, and limits
Local bridge, not local inference. Agent Talk adds no hosted relay or model API call of its own. The AI clients still process messages using their configured providers and permissions.
Private state lives in
.local/: SQLite coordination state, queued message bodies, question data, and DSH credentials. Treat it as sensitive. The directory is ignored by Git; credential files use mode600and their directory mode700.The DSH auth adapter accepts loopback HTTP addresses only. Native IPC checks ownership and permissions. The extension does not read DSH's signing secret or change client permissions.
Ordinary questions can be relayed. Permission approvals remain in DSH Web. A peer message does not grant new authority.
Results are checked every 3 seconds; questions use a DSH event connection. Polling does not call an AI model. Receiving and processing a forwarded message can start a model turn and consume usage.
At least one MCP process, DSH, and the recipient must be available for return. Closing all MCP processes stops forwarding. There is no guaranteed full catch-up after a long offline period.
talk_sendaccepts up to 100,000 JavaScript string units, subject to a stricter 120,000-byte assembled message limit, and at most 30 file paths. Large material should be passed by path. Return messages do not use the same size guard, but native-client and model limits still apply.Reads are bounded: up to 40 recent messages; desktop transcript reads inspect the final 2 MiB.
truncatedsignals omitted history. Progress is recorded tool activity, not token-by-token streaming.One local DSH Web instance is supported. Files are shared by absolute path, not uploaded or synchronized across machines.
No automatic archive, desktop conversation creation, approval bypass, or built-in Git/worktree/PR policy.
Troubleshooting
Symptom | Check |
Tools are missing or descriptions are old | Reconnect/restart the client's MCP process; check its Node and script paths. |
DSH cannot authenticate | Confirm DSH Web is running and |
Missing return destination | Bind the exact initiating conversation and pass its alias as |
DSH finished but nothing returned | Inspect |
Claude target cannot be found | Open an actual Desktop Code conversation. The adapter requires a live native worker; the app window alone is not sufficient. |
Workspace is missing or ambiguous | Call |
Message is too large | Save the material in a local document and send its path. |
A stopped task does not resume | Explicitly resume with |
Development and verification
npm run check
npm run smokeThe existing smoke test covers queueing, concurrent deduplication, uncertain delivery, native Stop handling, question validation, approval refusal, workspace resolution, credential renewal, and the MCP tool contract. It also verifies Chinese guidance and default return behavior with isolated mock endpoints. It is not an exhaustive compatibility test against every desktop release.
Real local checks have exercised DSH creation/send/read, workspace selection, question/answer continuation, result return into both Codex and Claude, and credential recovery. All native Stop variants, all reconnect races, long offline catch-up, and every complete development/review workflow have not been exhaustively verified. Claude can return held depending on native behavior.
src/server.mjs MCP tools and coordination guidance
src/adapters.mjs Native conversation adapters
src/delivery.mjs Persistent delivery and return polling
src/store.mjs SQLite state and deduplication
src/dsh-events.mjs DSH questions and approval notifications
src/dsh-auth.mjs Private credentials and renewal
src/dsh-auth-plugin.mjs DSH Web credential extension
src/vendor/ Adapted native IPC code and upstream license
scripts/ Manual connection and smoke checksContributions are welcome. Keep changes focused, preserve native permission boundaries and no-replay behavior, and run the existing checks. For a bug report, include app versions, tool name, state, and sanitized reproduction steps—not cookies, login URLs, session transcripts, or private task content.
License and acknowledgments
MIT. Native IPC portions are adapted from WebisityStudio/claude-codex-mcp-bridge; the original MIT notice is preserved. See THIRD_PARTY.md for attribution and design references.
This is an independent project, not an official integration from OpenAI, Anthropic, or the DSH maintainers.
Available Tools
11 toolstalk_answerC
回答指定的 DSH 普通问题,不支持代答权限审批。selected 填原始选项的精确标签,custom 可填写文字回答。相同答案不会重复提交。
Inputs: alias (required), answers (required), questionId (required).
talk_bindA
将精确的已有对话和目录绑定到固定别名。用此工具绑定当前发起任务的 Codex/Claude 对话。不发送消息。
Inputs: app (required), cwd (required), alias (required), sessionId (required).
talk_createA
创建 DSH 原生对话。workspaceName 按精确名称选择已有 DSH 工作区,其目录作为 cwd;不指定工作区时需提供 cwd,对话进入未分组。同时提供两者时目录必须一致。默认开启自动回传:先绑定当前发起方 Codex/Claude 对话,再将别名填入 replyTo;创建成功即开启,无需额外调用 talk_follow。只有用户明确不要回传时才设置 autoReturn=false 并省略 replyTo;缺少目标会报错,不会静默关闭回传。相同别名和 ID 复用同一对话;调用 talk_send 前不会派发任务。
Inputs: alias (required), requestId (required), app, cwd, +4 more.
talk_delivery_controlA
暂停或恢复投递,或将审查通过的任务标记完成。暂停 DSH 时也会请求原客户端停止并取消排队中的提示;暂停桌面对话只会暂停桥接投递。明确设置 active 才会恢复原客户端停止后的投递。标记完成会关闭回传,不会归档。
Inputs: alias (required), state (required).
talk_followB
将开启后新增的 DSH 最终回复、问题、异常结束和用户直接介入的消息回传给发起方 Codex/Claude 对话。接收方忙碌时等待,暂停后需明确恢复。至少一个 MCP 进程及相关原客户端须保持运行。
Inputs: source (required), destination (required), enabled.
talk_listA
列出原客户端中的对话。cwd 按精确目录筛选;Claude 列出正在运行的 Desktop Code 对话,Codex 列出近期本地任务。不绑定或恢复对话。
Inputs: app (required), cwd.
talk_outboxA
读取近期回执、自动回传错误和事件连接状态。queued 表示排队中,可以等待;unknown/sending/held 不得重发。observed 表示已在原客户端历史中读回完全一致的消息文本。
Inputs: no named parameters.
talk_questionsB
读取 DSH 的普通问题和权限请求。普通问题可用 talk_answer 回答;需要用户决定时向用户提问。权限审批只能在 DSH Web 中处理。
Inputs: alias (required).
talk_readA
读取原客户端状态、近期进度、最终回复、用户消息和问题。returnRoute 显示自动回传是否开启,lastReturn 显示最近回传回执;held 表示接收方暂存、尚未交给模型,不代表回传未开启,不得重发。桥接状态 paused 表示暂停,即使原客户端状态变化也需明确恢复。truncated=true 表示省略了较早历史;idle 只表示空闲,不代表审查通过。
Inputs: alias (required).
talk_sendA
向已绑定的对话发送提示词和本地文件路径。同一 requestId 不会重复发送。接收方忙碌或暂时不可用时,消息持久保存到队列。发送结果不确定时绝不重发。文件保留在本机。
Inputs: prompt (required), requestId (required), destination (required), files.
talk_workspacesA
列出已有 DSH 工作区的精确名称和目录。只读,不创建或重命名工作区。在 talk_create 中使用 workspaceName 选择工作区。
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 11 tools
Most tools have distinct purposes (list, bind, send, create, control, etc.), but talk_list, talk_read, and talk_outbox have overlapping read functionalities—talk_read covers original client state and talk_outbox covers delivery receipts, which could cause some confusion. talk_follow and talk_delivery_control also share overlap in managing return/delivery flow.
All tool names use the consistent talk_ prefix followed by a verb (list, bind, read, send, create, delivery_control, outbox, follow, questions, answer). Minor deviation: talk_delivery_control uses a noun+verb pattern, while others use simple verbs, but the overall pattern is clear and consistent.
11 tools is a well-scoped count for a bridging/communication server. Each tool covers a distinct aspect of the workflow: workspace management, listing, binding, reading, sending, creating, delivery control, outbox monitoring, follow-up, and answering questions. No tool feels redundant or unnecessary.
The tool set covers the full lifecycle of creating, sending, reading, and controlling conversations, including error handling and retry semantics. Minor gap: there is no explicit tool for unblocking or archiving conversations, and permission approvals are handled externally (in DSH Web), which is a slight hole but acknowledged in the descriptions.
Maintenance
Related MCP Connectors
No-data MCP handoff for local Claude Code to Codex harness moves. $49 lifetime.
Shared memory MCP server for Claude Code, Codex, Gemini CLI and Cursor. Cited, editable.
Connect ChatGPT and Claude to your Mac, Windows or Linux with secure MCP remote access.
Real-time chat for AI agents. Claude Code, Cursor, Cline and Codex join channels over MCP.
Related MCP Servers
- AlicenseNot gradedqualityFmaintenanceThe self-hosted MCP bridge between Claude Chat and Claude Code.46AGPL 3.0
- AlicenseNot gradedqualityDmaintenanceLocal MCP bridge enabling ChatGPT web to access approved local files and execute tasks via local Codex.16MIT
- FlicenseNot gradedqualityDmaintenanceCodex Bridge MCP is a local MCP orchestration service for a stable Claude Code x Codex CLI development workflow.2-
- AlicenseAqualityBmaintenanceA local MCP bridge that connects Claude Code and OpenAI Codex via a durable SQLite mailbox, with support for orchestrating and resuming Codex sessions.174MIT