agent-messenger

MCP server that unifies agent-to-agent messaging and task management for AI coding agents — Cursor, Claude Code, Codex, Windsurf, Aider, and any MCP-capable tool. Agents send messages, reply in threads, create and track tasks, manage dependencies, and follow structured workflows. Messages use a fast local file store (.am/); tasks and project tracking are backed by Beads for persistent, version-controlled storage.

Quick Start

Prerequisites: Node.js 20+, Beads (bd CLI) v1.0.0+, Dolt v1.85.0+

# Install globally (the CLI command is "agent-messenger")
npm install -g cursor-claude-messenger

# Set up in your project
cd your-project
agent-messenger init

# Restart Cursor. Done.

Windows: If agent-messenger isn't recognized after install, the npm global bin directory likely isn't in your PATH. Run npm prefix -g to find it (usually C:\Users\<you>\AppData\Roaming\npm), then add it permanently:

[Environment]::SetEnvironmentVariable("PATH", $env:PATH + ";$(npm prefix -g)", "User")

Restart your terminal after.

The init command handles message store setup (.am/), Beads initialization, MCP config generation, Cursor rules, and Claude Code skills. If something doesn't work, run:

agent-messenger doctor

How It Works

All agents connect to the same MCP server with different identities. The server auto-detects the agent environment (Cursor, Codex, Windsurf, etc.) or accepts any string via --env. Messages are stored in a fast local file store (.am/) with metadata/body separation for instant reads. Tasks and project tracking use Beads (Dolt) for version-controlled persistence. Threading, channels, and routing work the same across both stores.

┌──────────────┐         ┌─────────────────────┐         ┌──────────────┐
│    Cursor     │◄─stdio─►│  agent-messenger MCP │◄─stdio─►│  Claude Code  │
│  one shared   │         │                     │         │  cc-design    │
│  connection   │         │  send_message       │         └──────────────┘
│ #cm #sm #id   │         │  check_inbox        │
└──────────────┘         │  reply / get_thread  │         ┌──────────────┐
                          │  set_channel / ...   │◄─stdio─►│  Codex / etc  │
                          │                     │         │  codex-impl   │
                          │  ┌───────────────┐  │         └──────────────┘
                          │  │  .am/ messages │  │
                          │  │  .beads/ tasks │  │              ...
                          │  └───────────────┘  │
                          └─────────────────────┘

Shortcuts (26 tools)

Agents also use tools automatically on your behalf (threading, replying, managing dependencies, etc.). See docs/development.md for the full 26-tool API reference.

Workflows

agent-messenger includes two structured workflows that pair Cursor (orchestrator) with Claude Code (implementer). Each workflow is defined by a living document in your project that evolves through use.

Orchestrate (#orchestrate <feature>) — structured feature development: brainstorm, spec, plan, implement, verify. Built on superpowers.

Debug (#debug <description>) — systematic two-agent debugging: triage, hypothesize, investigate, diagnose, fix, verify. Includes a Diagnostic Resources section for project-specific tools.

Workflow docs are created automatically on first use at docs/guidance/workflows/. Phase transitions are tracked in Beads via workflow_checkpoint. Abandon at any step — no state to clean up.

See docs/setup-guide.md for the full workflow descriptions.

Task Management

Agents can create, track, and coordinate work — not just talk about it. Tasks are stored in Beads (a Dolt database), so they persist across sessions, agent restarts, and conversations.

Lifecycle: Create a task (#ct) → claim it (claim_task) → work → close it (close_task). Tasks have status, priority, labels, assignee, and notes.

Epics: Group related tasks under an epic for phased planning. Agents can create epics and nest tasks beneath them.

Dependencies: Tasks can block, track, or relate to each other. The dependency graph powers #rt (ready tasks) — showing only tasks whose blockers are resolved, so agents always know what to work on next.

Task-message linking: Pass task_id when sending or replying to link conversations to work items. show_task then surfaces all related messages. Context flows both directions — the discussion and the work stay connected.

Project stats: project_stats gives a health snapshot: open/closed counts, ready work, lead time, and recent activity.

Messages live in the fast local file store (.am/) for low-latency conversations. Tasks are the persistent, version-controlled record in Beads of what needs to happen, what's in progress, and what's done.

Identity & Multi-Agent

Cursor shares a single MCP connection across all agent tabs (Opus, Codex, etc.) in a workspace. All Cursor agents appear as one identity — when another agent messages "cursor", every Cursor agent receives it.

Claude Code gets a separate MCP connection per instance (whether in a terminal or a tab), so each has its own identity (e.g. claude-code-a3f2, claude-code-b1c9). Cursor can address them individually.

Other agents (Codex, Windsurf, Aider) are auto-detected via environment variables when possible. Any MCP-capable tool can connect by passing --env <name> — the server accepts any string for forward compatibility.

Use set_identity to pick memorable names — #id cursor-lead in Cursor, /id cc-design and /id cc-impl in each CC instance. Use channels (#ch / /ch) to isolate conversations when multiple agents are active.

CLI Commands

Init options

Troubleshooting

Run agent-messenger doctor first — it checks everything automatically.

See docs/setup-guide.md for the full troubleshooting table and usage guide.

Contributing

See docs/development.md for build-from-source instructions, manual configuration, and project structure. The project uses Beads for issue tracking — run bd ready to find available work.

License

MIT