/agmsg

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:

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)". If that name is not in `available_teams` and `~/.agents/skills/agmsg/scripts/team-list.sh --json --scope all` shows a team whose `binding_state` is not `none`, do not create it yet: ask whether to create a new local team or bring in the team of that name from a server (`remote pull`; after it succeeds, return to Identity setup). With no such team, create it locally without mentioning remote. 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 > -