v1.7.3

agmsg

fujibee@fujibee⭐ 1.6k stars· last commit 9h ago· 327 open issues

Cross-agent messaging via SQLite. Send messages between Claude Code, Codex, Gemini CLI, and other agents. No daemon, no network, no dependencies beyond bash and sqlite3.

Choose how to use this skill

You do not need every option. Choose the path your AI client supports. The stable page stays the same; versioned files are immutable.

1. Native installer

This listing has no registered native installer command. Use the complete package or source fallback below, depending on what your client supports.

Do not guess an installer command or replace an existing version without reviewing the diff.

2. Complete package recommended

Download the ZIP when available. It includes SKILL.md plus the references, security notes and version metadata.

No complete ProSkills package is published for this listing yet.

3. Prompt-only

Copy the prompt above when the agent can read the stable page or when you want to adopt the workflow without installing a skill.

Need only the instruction file?

Download SKILL.md only if your client requires a single file. The complete ZIP is safer for a full installation because it preserves the references and release context.

No path installs or executes anything by itself. Your agent still needs access to the project files. Before updating, compare the installed version and review the diff.

7.0/10
Verified
Oct 12, 2026

// RATINGS

⭐GitHub Stars
⭐⭐⭐⭐⭐ 1.6k on GitHubGitHub ↗

Very popular

🟢ProSkills ScoreAI Verified
7.0/10
📍

Not yet listed on ClawHub or SkillsMP

// README

agmsg

日本語

CI release license

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:

Two Claude Code agents autonomously playing tic-tac-toe over agmsg

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

Claude Code and Codex exchanging code review messages via 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 automatic

// HOW IT'S BUILT

// FILES

2 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.

  • SKILL.md7.8 KBupstream ↗
    ---
    name: agmsg
    description: Cross-agent messaging via SQLite. Send messages between Claude Code, Codex, Gemini CLI, and other agents. No daemon, no network, no dependencies beyond bash and sqlite3.
    ---
    
    <!-- agmsg:render-root -->
    
    ## Step 0: First-run bootstrap
    
    agmsg keeps its SQLite database, team registry, and runtime state under `~/.agents/skills/agmsg/`. The `./install.sh` install path creates that tree; the Claude Code plugin install path does not (the plugin marketplace only copies this repository into `~/.claude/plugins/cache/`). Before any other command, bootstrap if needed:
    
    ```bash
    if [ ! -d ~/.agents/skills/agmsg ]; then
      # Newest cached copy of the plugin. Several versions can sit side by side, so
      # pick by version folder name (numeric, portable -- not sort -V, not mtime).
      cache="$HOME/.claude/plugins/cache/fujibee-agmsg/agmsg"
      newest=$(ls "$cache" 2>/dev/null | sort -t. -k1,1n -k2,2n -k3,3n | tail -1)
      installer="$cache/$newest/install.sh"
      if [ -n "$newest" ] && [ -f "$installer" ]; then
        bash "$installer" --cmd agmsg
      else
        echo "agmsg not installed. Either:" >&2
        echo "  - run ./install.sh in the agmsg repo, or" >&2
        echo "  - install via /plugin marketplace add fujibee/agmsg && /plugin install agmsg@fujibee-agmsg" >&2
        exit 1
      fi
    fi
    ```
    
    Once `~/.agents/skills/agmsg/` exists this step does nothing, so it is safe to run every time.
    
    Agent messaging command. **IMPORTANT: Always use the provided scripts. NEVER directly read or edit config files, DB, or team data. There is NO register.sh — use join.sh to join a team.**
    
    **Use agmsg, not the host agent's own inter-session messaging.** Several agent
    CLIs ship a native way for one session to message another on the same machine
    (in Claude Code, the `SendMessage` / `ListAgents` tools over its peer-session
    list). While a project is on agmsg, route agent-to-agent messages through agmsg
    instead. A message sent natively does not exist as far as agmsg is concerned:
    it is absent from `history.sh` and the team's export, it never reaches a member
    on another machine through remote sync, it does not mark read or advance any
    cursor, and it cannot address a member whose CLI is a different type. Half the
    conversation living somewhere unrecorded is worse than either channel alone,
    and the gap is invisible until someone reads the history and finds a decision
    with no message behind it. The native channel stays fine for anything outside
    the team — a subagent you spawned for your own task, or a session that has not
    joined.
    
    **Shell requirement:** All agmsg scripts are Bash scripts. Always execute them via `bash`, never via PowerShell or cmd directly. If your default shell is not Bash (e.g. PowerShell on Windows), wrap every command with `bash -lc '...'`. Example: `bash -lc '~/.agents/skills/agmsg/scripts/send.sh myteam alice bob "hello"'`. Do NOT construct DB paths manually — the scripts handle path resolution internally. If you need to redirect storage, use `AGMSG_STORAGE_PATH` (the supported override).
    
    
    ## Identity
    
    If you already know your AGENT and TEAMS from a previous `/agmsg` call in this session, skip to **Execute** below.
    
    Otherwise, run: `~/.agents/skills/agmsg/scripts/whoami.sh "$(pwd)" claude-code`
    
    Four possible outputs:
    
    **A) Single identity:**
    `agent=<name> teams=<t1,t2,...> type=claude-code project=<path>`
    → Remember AGENT and TEAMS, then go to **Execute**.
    
    **B) Multiple identities:**
    `multiple=true agents=<n1,n2,...> teams=<t1,t2,...> type=claude-code project=<path>`
    → Ask the user which agent name to use for this session, then go to **Execute**.
    
    **C) Not in a team:**
    `not_joined=true available_teams=<t1,t2,...>` (or `available_teams=none`)
    → Show the user the available teams from the output, then:
    
      Before first-time setup, inspect the user's request. If they ask to join, import, or bring in a team that already exists on a server, do not call `join.sh`. Go directly to `remote pull` under Execute. First run `~/.agents/skills/agmsg/scripts/team-list.sh --json --scope all`; if a same-named local team has `binding_state` `none` or `disconnected`, stop and ask the user how to proceed. After pull succeeds, return to Identity setup so the user can register a new local agent in the pulled team.
    
      > **First-time setup required.**
      > Joining a team so this agent can send and receive messages.
      > - **Team name**: a group of agents that can message each other (available: <list from output>)
      > - **Agent name**: this agent's identity within the team
    
      1. Ask: "Enter a team name (joins existing or creates new)"
      2. If the team name given already appears in `available_teams`, run `~/.agents/skills/agmsg/scripts/team.sh <team>` to see the current roster (name, type, project) and note the names already in use. Look for a naming convention already in play (e.g. a shared base name with role and number suffixes (`<base>-<role><n>`), or names derived from the team name) and, when one exists, propose 2-3 unused names that extend it; otherwise propose 2-3 short, distinctive identity names (not a bare tool-type label like `codex`/`cc`). Either way, names must not collide with the roster. Then ask: "Enter a name for this agent (suggestions: <name1>, <name2>, <name3> — or type your own)". For a brand-new team, skip the roster check and just ask: "Enter a name for this agent".
      3. **You MUST use join.sh** — run: `~/.agents/skills/agmsg/scripts/join.sh <team> <agent_name> claude-code "$(pwd)"`
      4. Show the result and explain:
    
      > **Joined!** You can now use `/agmsg` to check and send messages.
      > - `/agmsg` — check inbox
      > - `/agmsg send <agent> <message>` — send a message
      > - `/agmsg team` — list team members
      > - `/agmsg history` — message history
    
    <!-- agmsg:render-overlay claude-code -->
      5. **REQUIRED — Do NOT skip this step.** Ask the user to pick `monitor`, `turn`, `both`, or `off` delivery. Empty input means `monitor`.
         Run `~/.agents/skills/agmsg/scripts/delivery.sh set <mode> claude-code "$(pwd)"` and follow the printed `AGMSG-DIRECTIVE` block.
    
      6. Then check inbox for the newly joined team.
    
    **D) Suggestions for reuse:**
    `suggest=true agents=<n1,n2,...> teams=<t1,t2,...> type=claude-code project=<path> available_teams=<t1,t2,...>`
    → No exact registration exists for this project, but there are same-type agent names registered elsewhere.
    
      1. Show the suggested agent names to the user.
      2. Ask whether to reuse one of those names or choose a new one.
      3. Ask for the team name to join (existing or new).
      4. Run: `~/.agents/skills/agmsg/scripts/join.sh <team> <agent_name> claude-code "$(pwd)"`
      5. Then continue with the normal post-join flow above.
    
    ## Execute
    
    **Only use scripts in `~/.agents/skills/agmsg/scripts/` — do not read or modify files under `teams/` or `db/` directly.** Treat the storage layout as internal: never construct a database path or invoke `sqlite3` directly. The scripts resolve the active store, including `AGMSG_STORAGE_PATH` overrides.
    
    **Terminal/pane self-awareness.** Asked about this session's own terminal, pane, or driver — or before using `arrange`, `peek`, or `poke` below — run `where.sh` (see the "where" argument below) first and answer from its `terminal=`/`capabilities=` fields. Never infer the driver from environment variables or a `grep`/`ps` guess: that is how a session under a real driver ends up reporting a false negative about its own placement, or claiming a capability or a whole driver does not exist when it does (#1171). Each driver's own operational detail lives in `~/.agents/skills/agmsg/scripts/drivers/terminals/<terminal>/README.md`, named by `where.sh`'s own `terminal=` field — never guessed at from a remembered syntax.
    
    Asked about a *teammate's* placement or status, or what can be done to one, that is `team.sh <team>`'s question (see the "team" argument below), not something to infer from a stale memory of their last known pane. Act on a teammate with `peek.sh`/`poke.sh`/`arrange.sh <team> <name>` directly r
  • README.mdupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

Plain-text copy, no login: /skill-bundles/fujibee-agmsg.md

// REPO STATS

1.6k stars
327 open issues
Last commit: 9h ago