agmsg Cross-Agent Messaging
A local SQLite message layer for coordinating CLI coding agents across tools.
What does this agent do, and when should you use it?
agmsg is a local cross-agent messaging utility for CLI coding-agent sessions, including Claude Code, Codex, Gemini CLI, and GitHub Copilot CLI. Its runtime is a set of Bash scripts, agent-type drivers, team configuration, and a shared SQLite message store rather than a daemon, server, or network service. Agents exchange durable plain-text messages through a WAL-mode SQLite database, and history.sh can replay a room after a session ends. The product exposes /agmsg or $agmsg plus commands for messaging, identity switching, delivery setup, spawning peers, and teardown. It fits teams already running multiple local terminal agents and seeking direct coordination; it does not enforce task claiming, turn-taking, or loop termination.
agmsg installs its skill and scripts under ~/.agents/skills/<cmd>/. On first use, /agmsg or $agmsg records a team and agent name for the current project and asks for a delivery mode. scripts/send.sh <team> <from> <to> "<message>" appends a message to db/messages.db; scripts/inbox.sh, a Stop hook, or a monitor-mode SQLite stream surfaces inbound messages and records reads. scripts/team.sh lists members, scripts/history.sh returns retained messages, and scripts/whoami.sh resolves a project identity. actas switches to an exclusive role, while spawn launches a separate pre-seeded CLI peer in tmux or a terminal and despawn tears down a spawned member. The transport carries text, so the documented pattern for larger handoffs is to send summaries and references such as paths or commit SHAs.
- A developer using Claude Code and Codex on the same repository can have one agent send a review request and receive the review through the shared team inbox.
- A technical lead working inside tmux can run spawn codex reviewer --boot-prompt "review the diff on this branch" to create a separate review session with an initial role and task.
- An engineering team using Gemini CLI, Copilot CLI, and other local coding agents can register them in one team to exchange short implementation updates with durable history.
- A developer resuming work after an agent restart can run history.sh <team> and provide the retained room transcript to a fresh session.
- Someone who alternates between architecture review and business-analysis duties in one project can use actas to switch identities while preventing another session from taking the same role.
What are this agent's strengths and limitations?
- The core transport uses only Bash and SQLite, with no daemon, socket, network service, or MCP server.
- WAL-mode SQLite retains message history and supports multiple readers with a single writer, while history.sh provides a replay path.
- The repository documents installation or driver paths for several CLI agents, including Claude Code, Codex, Gemini CLI, GitHub Copilot CLI, Antigravity, and OpenCode.
- actas adds exclusive role ownership, and spawn/despawn provide lifecycle controls for independent peer sessions in tmux or terminal windows.
- Participants need access to the same local SQLite store; this is not a hosted, networked, or remote messaging service.
- The runtime depends on bash and sqlite3; minimal Linux environments may need sqlite3 installed separately, and Windows requires consistent Git Bash usage.
- The transport does not implement task claims, leases, turn policy, or runaway-loop stopping conditions; teams must define those in prompts or protocol.
- Codex monitor delivery uses an app-server bridge and has a documented orphan-on-TUI-close limitation; Copilot CLI does not support monitor or both modes.
- send.sh normally rejects unregistered senders and recipients, so intentional pre-registration sends require --force.
How do you install or deploy this agent?
The runtime requires bash and sqlite3. The quickest installation path is:
npx agmsg
Then restart Claude Code, Codex, Gemini CLI, GitHub Copilot CLI, Antigravity, or OpenCode. To install directly from the repository:
git clone https://github.com/fujibee/agmsg.git
cd agmsg
./install.sh
The direct path also supports ./install.sh --cmd m for a custom command name and ./install.sh --agent-type gemini for a Gemini-oriented SKILL.md. On Windows, the scripts run through Git Bash and sqlite3 must be on the Git Bash PATH.
How do you use this agent?
From a project, first run /agmsg in Claude Code or $agmsg in Codex, Gemini CLI, Antigravity, or OpenCode. Choose a team name, agent name, and delivery mode when prompted. Typical requests invoke /agmsg send <agent> <message>, /agmsg team, or /agmsg history; the shell interface is:
~/.agents/skills/agmsg/scripts/send.sh <team> <from> <to> "<message>"
Codex supports turn and off by default. The repository also documents a beta monitor route through an app-server bridge, which changes how interactive Codex starts. In a workspace-write Codex sandbox, configure the skill's db and teams directories as writable roots before using operations that write state.
How does this agent compare with similar options?
Unlike MCP, agmsg has no MCP server or extra runtime and communicates through a local SQLite file. Unlike subagents, spawn creates independent peer sessions that communicate over agmsg rather than child processes managed by the current session. Unlike a message queue, it has no broker: the SQLite file is the shared message layer.