Skip to main content
Glama

Agent Messenger

中文 | English

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 防止多份加载重复挂载监听。

使用方法

  1. 完成接入后,在客户端中重载 MCP 配置或新开会话(客户端按 stdio 自动拉起服务,无需手动开后台窗口)。

  2. 调用 send_message:既可先通过 list_sessions 获取精确会话 ID,也可直接传语义简写(如 "to": "antigravity" 或 "to": "codex:latest",优先匹配同项目在线空闲会话)。

  3. 单次调用等待结果:在 send_message 或 get_message 中传入 "wait_ms": 15000(上限 30000),服务端通过 fs.watch 监听回执与原生日志变化并辅以 250ms 兜底检查。

  4. 精确回信:回信时传 reply_to 和 text 并省略 to,即可精确路由回原发送会话;显式指定其他完整会话 ID 属于转发,不会把原请求标为已回信。

  5. 拉起新会话:start_session 支持 client: "codex" | "pi"、现有绝对路径 folder 与首条消息 text。

  6. 身份绑定:优先使用客户端自动携带的调用者身份元数据;未携带时可在对应 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.mjs bundles all JavaScript dependencies, requiring only Node.js 24.9.0+ (no npm install or 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.py

What the installer does automatically:

  • Client & runtime detection: Inspects CODEX_HOME, GEMINI_CLI_HOME, PI_CODING_AGENT_DIR, executables on PATH, client app/profile directories, and your local Node.js 24.9+ binary; undetected clients are skipped cleanly (override with --clients codex,pi or --all).

  • Creates missing configs: Generates ~/.codex/config.toml, ~/.gemini/config/mcp_config.json, or ~/.pi/agent/mcp.json when a detected client does not have one yet.

  • Cross-device path migration: Safely backs up existing configs (.agent-messenger-*.bak) and updates stale agent-messenger (or legacy agent-hud), dotted TOML, or leftover HTTP-transport entries to the current machine/repo path while preserving env, 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.ts to ~/.pi/agent/extensions/agent-messenger.ts.

  • Diagnostics & uninstall: Run npm run doctor (node scripts/install.mjs --check) for read-only inspection, or node scripts/install.mjs --uninstall to 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-messenger

When 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

  1. Reload MCP configuration or start a new session in your client (the client launches the stdio MCP server automatically).

  2. Call send_message with either an exact session ID from list_sessions or a semantic shorthand ("antigravity", "codex:latest" — preferring idle, reachable sessions in the same project).

  3. Pass "wait_ms": 15000 (up to 30000) to send_message or get_message to wait in-call via fs.watch with a 250ms fallback sweep.

  4. Reply with reply_to and text while omitting to to route back to the original sender; passing a different target ID forwards the message without marking the original request as replied.

  5. Use start_session with client: "codex" | "pi", an existing absolute project folder, and an initial text prompt.

  6. 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 (or AGENT_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_id on retries; uncertain means delivery may have occurred and must not be retried with a new ID. Consecutive forwards default to a passLimit of 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.

  • expired indicates waiting ended unconfirmed rather than cancelling the remote task; late reliable completions or explicit replies still update status, and verified replied records 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-upstream

Pushing 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…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables 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
    • A
      license
      A
      quality
      B
      maintenance
      Enables 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.
      2
      MIT
    • F
      license
      Not graded
      quality
      B
      maintenance
      Enables 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.
      -