Agent Messenger
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
Agent Messenger
Headless local cross-agent messaging MCP server over stdio for Codex, Antigravity, and Pi — plug-and-play client auto-detection, path migration, event-driven wait_ms, and an optional local dashboard.
跨端无头本地智能体互发 MCP 服务,面向 Codex、Antigravity 与 Pi —— 支持换机即插即用自检测接入、跨设备路径自动迁移、事件驱动 wait_ms 等待与可选本地看板。
中文
简介
Agent Messenger 是一个轻量级本地 MCP(Model Context Protocol)标准输入输出服务,仅提供四个核心工具:list_sessions、send_message、get_message、start_session,以及一个可选本地状态看板(http://127.0.0.1:3721/)。
聚焦三端:当前维护 Codex、Antigravity、Pi;不包含 HUD、WebView2、额度查询、Token 统计或审批拦截。
零运行时依赖:
dist/agent-messenger.mjs已打包全部 JavaScript 依赖,运行与接入无需npm install或 Python(仅需本机已有 Node.js 24.9.0+)。换机即插即用:拉取仓库或解压运行包后,一行命令即可自动探测本机已安装客户端、补齐缺失配置、迁移旧路径并同步 Pi 扩展。
即插即用与自动接入
从 GitHub 克隆仓库或解压发行运行包(dist/agent-messenger-runtime.zip)后,直接运行一键接入脚本(支持 Windows / macOS / Linux):
node scripts/install.mjs
# 或使用以下等效入口:
npm run setup
npx . setup
python scripts/install.py自动检测与迁移机制:
客户端与环境自检测:自动识别
CODEX_HOME、GEMINI_CLI_HOME、PI_CODING_AGENT_DIR、PATH中的可执行文件、各端配置/安装目录及本机 Node.js 24.9+ 路径;未安装的客户端自动跳过(也可用--clients codex,pi或--all指定范围)。缺失配置自动生成:已安装客户端尚无配置文件时,自动创建目录并写入标准 MCP 配置(
~/.codex/config.toml、~/.gemini/config/mcp_config.json、~/.pi/agent/mcp.json)。跨设备/换目录自动迁移:若旧配置中已存在
agent-messenger(或历史agent-hud)条目、TOML dotted keys 或残留 HTTP 传输字段且路径不一致,先生成.agent-messenger-*.bak备份再迁移更新command/args,同时保留原有env、超时策略与其他 MCP 服务;配置一致时幂等跳过,不产生多余备份。Pi 扩展自动同步:自动将
plugins/pi/agent-messenger.ts同步到~/.pi/agent/extensions/agent-messenger.ts。诊断与卸载:运行
npm run doctor(或node scripts/install.mjs --check)可只读检查接入状态;node scripts/install.mjs --uninstall可安全卸载并保留备份。
Pi(pi-coding-agent)原生包安装
本仓库同时声明了 pi-package 清单(package.json 中的 pi.extensions),可直接通过 Pi 包管理器安装:
pi install https://github.com/huashuimoyv/agent-messenger
# 或安装本地克隆目录:
pi install /path/to/agent-messenger当以 Pi 包直接加载且 mcp.json 尚未配置 agent-messenger(兼容 agent_messenger 命名空间)时,扩展会自动调用 pi.registerMcpServer 挂载打包后的 MCP 服务,并通过 pi.events 防止多份加载重复挂载监听。
使用方法
完成接入后,在客户端中重载 MCP 配置或新开会话(客户端按 stdio 自动拉起服务,无需手动开后台窗口)。
调用
send_message:既可先通过list_sessions获取精确会话 ID,也可直接传语义简写(如"to": "antigravity"或"to": "codex:latest",优先匹配同项目在线空闲会话)。单次调用等待结果:在
send_message或get_message中传入"wait_ms": 15000(上限30000),服务端通过fs.watch监听回执与原生日志变化并辅以250ms兜底检查。精确回信:回信时传
reply_to和text并省略to,即可精确路由回原发送会话;显式指定其他完整会话 ID 属于转发,不会把原请求标为已回信。拉起新会话:
start_session支持client: "codex" | "pi"、现有绝对路径folder与首条消息text。身份绑定:优先使用客户端自动携带的调用者身份元数据;未携带时可在对应 MCP 启动环境中设置
AGENT_MESSENGER_CLIENT与AGENT_MESSENGER_SESSION_ID。
本地看板
双击
open-dashboard.vbs打开独立窗口,或运行npm run dashboard后访问http://127.0.0.1:3721/。MCP 启动时也会伴生提供同端口看板;更新代码后需重载对应进程才会生效。
数据与状态边界
数据默认存储于
%LOCALAPPDATA%\agent-messenger(可通过AGENT_MESSENGER_HOME覆盖);消息 journal 保留 7 天,仅记录元数据与内容指纹,回复正文按需从客户端原生记录读取。重复请求请复用
request_id;uncertain表示消息可能已投递,切勿更换新 ID 盲目重发。连续转发默认上限 10 次,用户在链路中发起新输入后重置。Antigravity 忙时入队的普通回复无法可靠归属,需显式使用
reply_to。expired在看板中显示为“已结束等待”,不代表已撤回远端任务;迟到的可靠原生完成记录或精确回信仍可更新状态。存在已验证显式回信时状态保持replied,同一轮次的最终答案仍可读取。延期支持:Claude Code 与 DeepSeek Harness 的历史适配器及模板暂时保留,当前不安装、生成或接入这两端。
开发与构建
npm ci
npm run build
npm test
# 构建并同步 dist/agent-messenger-runtime.zip(跨平台):
npm run package
# 或使用 Windows 包装脚本:
powershell -NoProfile -File scripts/package.ps1
# 追踪上游互发协议变更(过滤 GUI/HUD 等无关改动):
npm run check-upstream推送 v* 标签(如 v0.2.0)或在 GitHub Actions 手动触发 Release 工作流,会自动运行测试、构建 dist/agent-messenger-runtime.zip 并发布 GitHub Release。
架构设计与审计说明见 docs/AUDIT.md,上游追踪说明见 docs/UPSTREAM_TRACKING.md。
Related MCP server: Lumen Bridge
English
Overview
Agent Messenger is a lightweight local MCP (Model Context Protocol) stdio server for cross-agent messaging, exposing four focused tools — list_sessions, send_message, get_message, and start_session — alongside an optional local dashboard (http://127.0.0.1:3721/).
Focused client support: Actively maintained for Codex, Antigravity, and Pi; contains no HUD, WebView2, quota tracking, token meters, or approval hooks.
Zero runtime dependencies:
dist/agent-messenger.mjsbundles all JavaScript dependencies, requiring only Node.js 24.9.0+ (nonpm installor Python needed at runtime).Plug-and-play across machines: After cloning from GitHub or extracting
dist/agent-messenger-runtime.zip, a single setup command auto-detects installed clients, creates missing configs, migrates stale paths, and syncs the Pi extension.
Plug-and-Play Setup
After cloning the repository or extracting a release runtime bundle, run the cross-platform auto-installer (Windows / macOS / Linux):
node scripts/install.mjs
# Equivalent entrypoints:
npm run setup
npx . setup
python scripts/install.pyWhat the installer does automatically:
Client & runtime detection: Inspects
CODEX_HOME,GEMINI_CLI_HOME,PI_CODING_AGENT_DIR, executables onPATH, client app/profile directories, and your local Node.js 24.9+ binary; undetected clients are skipped cleanly (override with--clients codex,pior--all).Creates missing configs: Generates
~/.codex/config.toml,~/.gemini/config/mcp_config.json, or~/.pi/agent/mcp.jsonwhen a detected client does not have one yet.Cross-device path migration: Safely backs up existing configs (
.agent-messenger-*.bak) and updates staleagent-messenger(or legacyagent-hud), dotted TOML, or leftover HTTP-transport entries to the current machine/repo path while preservingenv, timeouts, and all other MCP servers; stays idempotent with no extra backups when already up-to-date.Syncs the Pi extension: Copies
plugins/pi/agent-messenger.tsto~/.pi/agent/extensions/agent-messenger.ts.Diagnostics & uninstall: Run
npm run doctor(node scripts/install.mjs --check) for read-only inspection, ornode scripts/install.mjs --uninstallto cleanly remove entries while keeping backups.
Native pi-package Support
package.json declares a standard pi-package manifest (pi.extensions), so Pi users can also install directly:
pi install https://github.com/huashuimoyv/agent-messenger
# Or from a local checkout:
pi install /path/to/agent-messengerWhen loaded as a Pi package without an existing agent-messenger / agent_messenger entry in mcp.json, the extension auto-registers the local bundled MCP server via pi.registerMcpServer and deduplicates event hooks across pi.events.
Usage
Reload MCP configuration or start a new session in your client (the client launches the stdio MCP server automatically).
Call
send_messagewith either an exact session ID fromlist_sessionsor a semantic shorthand ("antigravity","codex:latest"— preferring idle, reachable sessions in the same project).Pass
"wait_ms": 15000(up to30000) tosend_messageorget_messageto wait in-call viafs.watchwith a250msfallback sweep.Reply with
reply_toandtextwhile omittingtoto route back to the original sender; passing a different target ID forwards the message without marking the original request as replied.Use
start_sessionwithclient: "codex" | "pi", an existing absolute projectfolder, and an initialtextprompt.Both Codex legacy JSONL and paginated history databases are supported; caller identity is derived from MCP client metadata or
AGENT_MESSENGER_CLIENT/AGENT_MESSENGER_SESSION_ID.
Local Dashboard
Run npm run dashboard (or open-dashboard.vbs on Windows) and open http://127.0.0.1:3721/. The MCP server also hosts the same dashboard endpoint while active.
Data & Guarantees
Local state lives under
%LOCALAPPDATA%\agent-messenger(orAGENT_MESSENGER_HOME). The SQLite journal retains 7 days of metadata and content fingerprints; reply bodies are read on demand from native client transcripts.Reuse
request_idon retries;uncertainmeans delivery may have occurred and must not be retried with a new ID. Consecutive forwards default to apassLimitof 10 until a real user prompt resets the chain.Queued deliveries made while Antigravity is mid-turn cannot safely bind an ordinary final answer and require an explicit
reply_to.expiredindicates waiting ended unconfirmed rather than cancelling the remote task; late reliable completions or explicit replies still update status, and verifiedrepliedrecords preserve access to any native final answer.Claude Code and DeepSeek Harness adapters/templates remain in the tree as deferred code and are not installed or wired.
Development & Packaging
npm ci
npm run build
npm test
# Build and package dist/agent-messenger-runtime.zip (cross-platform):
npm run package
# Or via the Windows wrapper:
powershell -NoProfile -File scripts/package.ps1
# Audit upstream messaging changes only:
npm run check-upstreamPushing a v* tag (e.g., v0.2.0) or manually triggering the Release workflow in GitHub Actions automatically runs tests, builds dist/agent-messenger-runtime.zip, and publishes the GitHub Release.
See docs/AUDIT.md for architecture details and docs/UPSTREAM_TRACKING.md for upstream tracking rules.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Real-time chat for AI agents. Claude Code, Cursor, Cline and Codex join channels over MCP.
- aXDeprecatedio.github.ax-platform
Agent-native collaboration network: orchestrate a team of long-running agents from any MCP client.
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Remote MCP server exposing your Node Command fleet (files, shell, processes, browser) to AI hosts.
Related MCP Servers
- FlicenseNot gradedqualityCmaintenanceEnables MCP-compatible hosts such as OpenCode to drive the Codex CLI through codex app-server over stdio, exposing tools to run prompts, inspect status, list threads, and interrupt running turns.-
- AlicenseNot gradedqualityCmaintenanceEnables MCP clients and external AI supervisors to oversee and steer native Codex sessions through a thin local stdio bridge. It exposes eleven codex_* supervisory tools for tasks such as listing threads, starting turns, observing progress, steering, responding to approvals, interrupting, checkpointing, and rolling over work.MIT
- AlicenseAqualityBmaintenanceEnables MCP clients to start new Codex conversations and continue existing threads, exposing codex and codex-reply tools over stdio via the Codex app-server protocol.2MIT
- FlicenseNot gradedqualityBmaintenanceEnables MCP clients such as Claude Desktop or Claude Code to drive the local daemon through stdio, listing agents and sessions, running agents, and reporting costs.-