agmsg: Cross-Agent CLI Messaging

This project provides a lightweight, local messaging system for command-line AI agents, enabling seamless collaboration between different agents like Claude Code and Codex without requiring a network or daemon. It's designed for users who want their CLI AI agents to communicate and work together directly, simplifying complex agent interactions and automating workflows.

How It Works

agmsg leverages a shared SQLite database for message persistence and direct filesystem access for communication. Agents integrate agmsg as a skill, allowing them to send and receive messages. This approach eliminates the overhead and complexity associated with network-based or daemonized messaging systems, offering a simple, self-contained solution for agent-to-agent communication.

Quick Start & Requirements

Installation is a one-liner: bash <(curl -fsSL https://raw.githubusercontent.com/fujibee/agmsg/main/setup.sh). Alternatively, clone the repository and run ./install.sh. After installation, restart your agent (e.g., Claude Code, Codex) to load the new skill. Basic usage involves running /agmsg (Claude Code) or $agmsg (Codex) within your project directory. The system requires bash and sqlite3; no python3 is needed.

Highlighted Details

• Delivery Modes: Supports monitor (real-time push, default for Claude Code), turn (between-turns check, default for Codex), both, and off, configurable per project.
• Multi-Identity & Roles: Agents can join teams with multiple identities (e.g., cc, reviewer) and switch roles within a project using actas and drop commands, enabling distinct collaborative functions. Claude Code's actas claims exclusive locks.
• Cross-Project Identity: A single agent identity can be registered and reused across multiple projects.
• Local Storage: Utilizes a single SQLite file (messages.db) in WAL mode for message storage, located within the skill's directory.

Maintenance & Community

The project includes contribution guidelines and design documentation. Specific community links (Discord/Slack) or notable contributors are not detailed in the README.

Licensing & Compatibility

Licensed under the MIT license, agmsg is permissive for commercial use and integration into closed-source projects.

Limitations & Caveats

The actas command on Codex is send-side only and does not enforce peer-visible exclusivity. A known issue (#67) exists where PID recycling could potentially lead to stale locks, preventing other sessions from claiming identities. Roles added mid-session via actas in another Claude Code instance may not be received until the watcher restarts.