agmsg: Cross-Agent Messaging for CLI AI Coding Agents

agmsg is a free, open-source, cross-agent messaging tool for CLI AI coding agents.

It allows your Claude Code, Codex, Gemini CLI, and GitHub Copilot CLI to send messages to each other directly through a shared local SQLite database. Just need bash and sqlite3 installed as an Agent Skill.

When you use multiple AI coding agents in the same project, passing context between them usually means copying output from one terminal and pasting it into another.

agmsg replaces that manual relay with direct peer-to-peer messaging. One agent writes a message to a shared SQLite file, and another agent reads it on its next turn or via a real-time monitor stream.

The tool does not compete with MCP or built-in subagent features. It addresses the narrower case where independent, vendor-diverse CLI agents need to coordinate inside the same local workspace.

If you already run Claude Code for architecture planning and Codex for heavy refactoring, agmsg lets them hand off tasks without you as the courier.

Visit agmsg

Features

Sends messages between separate CLI AI agent sessions.
Connects Claude Code, Codex, Gemini CLI, GitHub Copilot CLI, Antigravity, OpenCode, and other terminal agents.
Keeps agent messages in a shared local room.
Preserves message history after sessions end.
Lets one project join or create a team during setup.
Lets each agent use a clear name inside the team.
Supports different delivery modes for real-time, between-turn, fallback, or manual message checks.
Lets one project switch between named roles, such as tech-lead or biz-analyst.
Uses local storage instead of a hosted messaging service.
Sends short handoffs such as review requests, file paths, commit SHAs, issue numbers, and status updates.
Connects peer agents instead of creating subagents.
Runs separately from MCP servers and MCP tool calls.

agmsg two monitor mode

Use Cases

Send a code review request from Claude Code to Codex.
Ask another agent to inspect a file path, issue number, or commit SHA.
Keep multiple Claude Code sessions in one local team.
Split planning, implementation, review, and analysis across different CLI agents.
Preserve short agent handoff messages across coding sessions.
Run multi-role sessions from one project, such as tech-lead and biz-analyst.
Keep local agent coordination separate from MCP tools and hosted automation platforms.

agmsg vs MCP, Subagents, and Message Queues

Comparison	agmsg
MCP	agmsg is not an MCP server. It connects peer agent sessions through a local SQLite store.
Subagents	agmsg does not spawn child agents. It links separate agent sessions that already exist.
Message queue	agmsg has no broker. SQLite acts as the shared message floor.
Multi-agent manager	agmsg does not create isolated workspaces, previews, or PR dashboards. It only moves short messages between agents.

How To Use It

1. Install agmsg with the one-line installer.

bash <(curl -fsSL https://raw.githubusercontent.com/fujibee/agmsg/main/setup.sh)

2. Clone the repository first when you want to inspect the code before installation.

git clone https://github.com/fujibee/agmsg.git
cd agmsg
./install.sh

3. Restart your CLI coding agent after installation. Claude Code, Codex, Gemini CLI, GitHub Copilot CLI, and Antigravity need a restart before they detect the new skill.

4. Start agmsg inside your project.

# Claude Code and GitHub Copilot CLI
/agmsg
# Codex, Gemini CLI, and Antigravity
$agmsg

5. Enter a team name and an agent name during the first run. The team name creates or joins a room. The agent name identifies the current session inside that room.

6. Pick a delivery mode during the join flow. Claude Code defaults to monitor mode. Codex defaults to turn mode because it has no Monitor tool.

7. Talk to your agent in natural language after registration.

send alice a message saying the deploy is done

check my messages

who's on the team

8. Use short messages for handoffs. Put large diffs, logs, transcripts, or generated files on disk, then send the path or commit SHA through agmsg.

9. Add a stop condition when you let agents respond to each other. Use prompts such as stop after 5 exchanges or reply DONE when the review is complete.

10. Use actas only when one workspace needs distinct roles.

/agmsg actas tech-lead
/agmsg actas biz-analyst
/agmsg drop biz-analyst

Delivery Modes

Mode	Mechanism	Latency	Best Use
`monitor`	SessionStart hook, Monitor tool, blocking SQLite stream.	Around 5 seconds.	Claude Code real-time delivery.
`turn`	Stop hook runs `check-inbox.sh` between assistant turns.	Next interaction.	Codex, Copilot CLI, quieter Claude Code sessions.
`both`	Monitor delivery with turn-end fallback.	Around 5 seconds, with fallback.	Claude Code sessions that need a safety net.
`off`	No automatic delivery.	Manual checks only.	Minimal local setup.

Use these commands to change or inspect delivery mode.

/agmsg mode monitor
/agmsg mode turn
/agmsg mode both
/agmsg mode off
/agmsg mode

monitor mode has one startup detail: the receiving agent must take at least one turn during the current session before it reacts to the first inbound message. A short message such as hi primes the session.

Quick Reference

Install Commands

Command	Purpose
`bash <(curl -fsSL https://raw.githubusercontent.com/fujibee/agmsg/main/setup.sh)`	Run the one-line installer.
`git clone https://github.com/fujibee/agmsg.git && cd agmsg && ./install.sh`	Clone and install after inspection.
`./install.sh`	Run the interactive installer.
`./install.sh --cmd m`	Install with a custom command name.
`./install.sh --agent-type gemini`	Install a Gemini-oriented `SKILL.md`.

The command name controls these paths and command forms.

Item	Result
Skill folder	`~/.agents/skills/<cmd>/`
Claude Code command	`/<cmd>`
Codex, Gemini CLI, and Antigravity command	`$<cmd>`

First-Run Commands

Agent	Command
Claude Code	`/agmsg`
GitHub Copilot CLI	`/agmsg`
Codex	`$agmsg`
Gemini CLI	`$agmsg`
Antigravity	`$agmsg`

Claude Code Commands

Command	Purpose
`/agmsg`	Check inbox across teams.
`/agmsg history`	Show message history.
`/agmsg team`	List team members.
`/agmsg send <agent> <message>`	Send a message to another agent.
`/agmsg mode <monitor\|turn\|both\|off>`	Switch delivery mode.
`/agmsg mode`	Show current mode.
`/agmsg actas <name>`	Switch to another role in the project.
`/agmsg drop <name>`	Remove a role from the project.
`/agmsg hook on`	Legacy alias for `mode turn`.
`/agmsg hook off`	Legacy alias for `mode off`.
`/agmsg reset`	Clear the current project registration.

Shell Scripts

Script	Purpose
`send.sh <team> <from> <to> "<message>"`	Insert a message into the database.
`inbox.sh <team> <agent_id>`	Show unread messages and mark them as read.
`history.sh <team> [agent_id] [limit]`	Show message history.
`team.sh <team>`	List team members.
`whoami.sh <project_path> <type>`	Resolve the current identity.
`delivery.sh set <mode> <type> <project_path>`	Set the delivery mode.
`delivery.sh status [<type> <project_path>]`	Show delivery status.
`reset.sh <project_path> <type> [agent_id]`	Clear registration data.
`hook.sh on`	Legacy alias for turn delivery.
`hook.sh off`	Legacy alias for manual delivery.

send.sh requires exactly four positional arguments.

~/.agents/skills/<cmd>/scripts/send.sh <team> <from> <to> "<message>"

Quote the message as one shell argument.

~/.agents/skills/agmsg/scripts/send.sh myteam alice bob "review src/auth.ts before merge"

Environment Variable

Variable	Default	Purpose
`AGMSG_STORAGE_PATH`	`<skill>/db`	Relocates the SQLite message store directory.

Run an isolated store with this form.

AGMSG_STORAGE_PATH=/tmp/agmsg-sandbox ./scripts/send.sh myteam alice bob "hi"

The override affects the SQLite store only. Team configs remain under the skill’s teams/ directory.

Update Command

cd agmsg
git pull
./install.sh --update

Updates preserve database and team configs.

Uninstall Commands

./uninstall.sh

./uninstall.sh --yes

./uninstall.sh --keep-data

The interactive uninstall asks for confirmation. The --yes option removes everything. The --keep-data option removes the skill while keeping the database and teams.

Test Command

bats tests/

The test command requires bats-core.

Alternatives and Related Tools

Best Open-Source MCP Servers: Browse MCP servers for tasks that require tool access, context retrieval, or external service integration.
10 Best Agent Skills for Claude Code & AI Workflows: Compare Agent Skills that extend Claude Code, Codex, Gemini CLI, and similar agent workflows.
7 Best CLI AI Coding Agents: The best terminal-first AI coding agents all over the world.
Claude Code Commands Cheat Sheet: Review Claude Code slash commands, flags, MCP commands, and workflow controls.
Claude Peers MCP Server: Compare agmsg with an MCP-based multi-session messaging approach for Claude Code.
Manaflow: Consider a dashboard-style tool for running multiple coding agents in parallel.

Pros

Local SQLite storage.
No daemon.
No network service.
Agent Skill install.
Persistent message history.
Cross-agent rooms.

Cons

CLI setup required.
Plain-text messages only.
Codex monitor unavailable.
Stop rules need prompts.
SQLite writer serialization.

FAQs

Q: Is agmsg an MCP server?
A: No. agmsg is not MCP. It does not expose tools through the Model Context Protocol. It passes plain-text messages between peer CLI agent sessions through a local SQLite database.

Q: Does agmsg create subagents?
A: No. agmsg does not spawn child agents or manage background workers. You run the agents yourself, then agmsg lets those sessions message each other.

Q: Does agmsg send data to the cloud?
A: agmsg uses local filesystem access and a local SQLite database. Your connected agent may still send prompts, code context, or messages to its own model provider during normal operation.

Q: Can agmsg handle large files or long outputs?
A: No. agmsg messages are plain text. Save large outputs, diffs, logs, or artifacts to disk, then send a short message with the file path, commit SHA, or issue link.

Q: Does agmsg preserve message history?
A: Yes. Messages remain in the SQLite database after sessions end. The history.sh script can replay room history into a later session.