agmsg Cross-Agent Messaging
A local SQLite message layer for coordinating CLI coding agents across tools.
Per-dimension scores and reasoning
Evidence: scripts run with user privileges, no privilege escalation; installation and uninstallation require user confirmation; data flow transparent (SQLite file, local storage); dependencies only bash and sqlite3, npm package has SLSA provenance; external effects limited to local filesystem and launching terminals; rollback via uninstall.sh and --keep-data; source attribution clear (MIT license, author fujibee). Deduction: sensitive data handling not explicitly addressed (e.g., message encryption), but local storage and no network transmission, so score 2.
Evidence: README and code consistent, no contradictions; dependencies bash and sqlite3 common and documented; error messages clear (e.g., sqlite3 missing). Deduction: no automated test evidence, but static review cannot verify, so score 2.
Evidence: clear target users (CLI AI agent users), diverse scenarios (multi-agent collaboration); capability boundaries clear (not MCP, not message queue); trigger commands explicit (/agmsg etc.); environment fit (macOS/Linux/Windows Git Bash). Deduction: no major flaws, score 2.
Evidence: information architecture clear (README, docs, site); installation notes detailed; naming stable (agmsg); examples and FAQ rich; known limitations explicit (e.g., Codex monitor limitations); MIT license; version and changelog exist; maintenance responsibility clear (author and contributors). Deduction: no major flaws, score 2.
Evidence: output usable (message passing); marginal value high (solves inter-agent communication); cost-benefit good (only bash and sqlite3). Deduction: no execution verification, but static assessment reasonable, score 2.
Evidence: README claims consistent with code; community projects mentioned but not verified; facts and inferences separated (README distinguishes facts and design notes). Deduction: cross-source corroboration insufficient (only README and code), score 1.
- Static review cannot verify actual runtime behavior; dynamic testing recommended.
- Sensitive data handling not explicitly addressed; review if messages contain sensitive information.
- Cross-source corroboration insufficient; verify community projects authenticity.
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 agmsgThen 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.shThe 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.