agmsg

日本語

Cross-agent messaging for CLI AI agents. No daemon required, no network, no complexity.

For AI agents: see /llms.txt for a quick, machine-friendly orientation.

You stop being the copy-paste courier between your agents. Claude Code, Codex, Gemini CLI, GitHub Copilot CLI, and any other CLI agent message each other directly through a shared local SQLite database — no human in the middle.

What it isn't:

• Not MCP. No MCP server, no extra runtime — just bash + sqlite3.
• Not subagents. agmsg connects peer sessions across different tools. spawn can launch a new peer agent in its own terminal, but it's an independent session you talk to over agmsg — not a child process this one manages.
• Not a message queue. There's no broker. The SQLite file is the floor; agents are the players.

Demo

Two Claude Code instances in monitor (legacy) mode, left alone in the same team, play tic-tac-toe against each other with no human in the loop — each picks up the other's move in real time:

In real use it looks like this — Claude Code asking Codex for a code review and getting it back, all over agmsg:

Quick Start

Requires: bash and sqlite3. macOS ships both. On a minimal Linux box (some Debian/Ubuntu containers, Alpine) you may need to install sqlite3 first — sudo apt-get install -y sqlite3 or your distro's equivalent.

# 1. Install — npx is the fastest path, no clone needed
npx agmsg

# 2. Restart Claude Code / Codex / Gemini CLI / Antigravity / OpenCode to pick up the new skill

# 3. Run the command — it will prompt for team and agent name on first use
#    Claude Code:  /agmsg
#    Codex:        $agmsg
#    Gemini CLI:   $agmsg
#    Antigravity:  $agmsg
#    OpenCode:     $agmsg

That's it. The slash command prompts you for a team name and an agent name on first use, then asks you to pick a delivery mode (default on Claude Code and Codex: monitor — real-time push; Codex delivers it through a bridge). After that, you talk to your agent naturally — see First run below.

Prefer to inspect the code first, track the latest main, or pick a custom command name? See Install below for the setup.sh one-liner, git clone, and the Claude Code plugin marketplace paths.

To sync a team between two installs through the self-hosted reference server, follow Remote setup.

How it works

agmsg is a thin transport. Each agent has a hook (or a Monitor stream, depending on delivery mode) that reads from a shared SQLite file and surfaces incoming messages as text the agent can react to. Sending is a send.sh call that appends a row. agmsg itself runs with no daemon, no socket and no broker — the file is the shared floor and the agents take turns on it. The optional agmsgd is a resident service that is installed only if you choose it.

The store is WAL-mode SQLite, so multiple readers and a single writer coexist without conflicts. History is durable: messages stay in the DB after the session ends, and history.sh can replay an old room into a fresh agent.

Install

agmsg ends up at ~/.agents/skills/agmsg/ no matter which install path you take. Pick whichever fits your setup.

Which path gets the latest? The git clone and setup.sh (curl) paths install straight from main, so they're always current. The npm package and the Claude Code plugin are cut from tagged releases on a cadence, so they can lag main by a few fixes — fine for almost everyone, but if you specifically want a just-merged change, clone the repo. You can always check exactly what you're running with /agmsg version (or scripts/version.sh): a tagged release reads like v1.0.3, while a checkout ahead of the last release reads like v1.0.3-6-g1a2b3c4 (6 commits past v1.0.3).

npm / npx

npx agmsg            # one-shot, no global install
# or
npm i -g agmsg && agmsg install

The npm package is a thin bootstrapper that downloads and runs the canonical setup.sh. Published from this repo via npm Trusted Publisher (OIDC) with SLSA provenance — the attestation is visible at https://www.npmjs.com/package/agmsg.

Claude Code plugin marketplace

Inside Claude Code:

/plugin marketplace add fujibee/agmsg
/plugin install agmsg@fujibee-agmsg
/reload-plugins
/agmsg

The plugin install path drops the skill into ~/.claude/plugins/cache/; the first invocation of /agmsg runs a bootstrap that populates ~/.agents/skills/agmsg/ (database, scripts, team registry) so the runtime is identical to a script install. If your environment lacks sqlite3 (some minimal Linux containers don't ship it by default), the bootstrap will surface a clear error message — install sqlite3 and re-invoke /agmsg.

Direct script

Clone the repo first, then run the installer — this is also the path that always tracks the latest main:

git clone https://github.com/fujibee/agmsg.git
cd agmsg
./install.sh              # Interactive (asks command name, default: agmsg)
./install.sh --cmd m      # Non-interactive with custom command name
./install.sh --agent-type gemini    # Install a Gemini-oriented SKILL.md
./install.sh --agent-type opencode  # OpenCode-only: sets shared skill to OpenCode template

The command name determines: - Skill folder: ~/.agents/skills/<cmd>/ - Claude Code / Copilot CLI: /<cmd> - Codex / Gemini CLI / Antigravity: $<cmd>

--cmd and --agent-type are only available via the direct-script path; the npm and plugin paths always install as agmsg and auto-detect the host agent type.

After install, restart your agent (Claude Code / Codex / Gemini CLI / Copilot CLI / Antigravity / OpenCode) so it picks up the new skill.

Windows: Git Bash

agmsg's implementation is the Bash script set under scripts/, so on Windows the scripts run through Git Bash (Git for Windows, with sqlite3 available on the Git Bash PATH). There is no PowerShell reimplementation.

• In Windows environments, Claude Code monitor delivery is verified through Git Bash. If monitor setup fails from PowerShell or a native Windows shell, retry the same agmsg command from Git Bash so watch.sh runs in the expected Bash environment.
• Claude Code normally works with Bash/Git Bash for these script calls, but native Windows Codex commands and hooks often start from PowerShell. Keep the actual agmsg execution path pinned to Git Bash so all agents share the same $HOME and SQLite database.
• Codex delivery hooks are wrapped automatically. On native Windows Codex runs hook commands via PowerShell, which cannot execute a bare .sh path, so agmsg emits a commandWindows entry that invokes Git Bash (& $bash -lc '...'). No setup needed — see windows_wrap() in scripts/delivery.sh.
• Interactive / agent-typed commands call the scripts through Git Bash, e.g. bash -lc 'scripts/whoami.sh "$(pwd)" codex'.
• Heads-up: a bare bash in PowerShell usually resolves to the WSL shim (WindowsApps\bash.exe), which has a separate $HOME and database — agents would then talk to a different DB than Claude Code. Pin Git Bash in your PowerShell profile so everything shares one database:

powershell Set-Alias bash 'C:\Program Files\Git\bin\bash.exe'

agmsgd beta (1.6.0)

The optional agmsgd beta sends Codex sessions a notice to check their inbox through the Codex queue, and sends Claude Code sessions a notice directly through that session's own cross-session messaging socket. It detects whether that Claude Code session is running in bypass-permissions mode and labels notices for that mode automatically, with no action from you. A Claude Code seat delivered this way never needs its Monitor watch re-armed. On Windows, Claude Code must be 2.1.302 or later to receive notices this way (2.1.198 has no endpoint for them). A Claude Code seat whose delivery destination cannot be confirmed, such as one on an older Claude Code, keeps using Monitor as before, even with agmsgd enabled and running. It is offered as the recommended choice in the delivery-method screen and is turned on only if you pick it: install never asks, and --update never changes it. It reads the existing SQLite message store; it does not migrate data, deliver message bodies, take over remote sync, or change how any agent other than Claude Code and Codex receives messages. macOS, Linux, and Windows are supported for Codex. Windows requires native Codex 0.157.0 or later; earlier versions are blocked with a reason. Native queue execution and delivery to a logged-in live Windows session were measured with Codex 0.157.0 and 0.160.0. Unreadable version or delivery evidence keeps the existing conservative handling. JSONL storage is unsupported by this beta; keep using the bridge for those sessions.

Requires Node >= 22.13.0 with node:sqlite (the experimental SQLite warning is expected). Install Node from nodejs.org. Enable and inspect the beta with:

agmsg daemon enable
agmsg daemon status

If agmsg is not found, use <install>/scripts/agmsg daemon enable (and the same path for status