fujibee/agmsg/agmsg

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 > - /agmsg send <agent> <message> — send a message > - /agmsg team — list team members > - /agmsg history — message history

<!-- agmsg:render-overlay claude-code -->

1. REQUIRED — Do NOT skip this step. Choose how incoming messages reach this agent. Show this screen every time (a new join, a new seat added by someone already using agmsg, and when the mode is changed). First run ~/.agents/skills/agmsg/scripts/agmsg daemon offer claude-code; it only reads and prints one line:

• agmsgd=available: ask the user to pick one, in this order:

1. agmsgd — notices delivered directly by a background service (recommended). Choosing it registers a background service that starts at login; agmsg daemon disable stops and removes it. Empty input means this one.
2. monitor (legacy) — the Claude Code Monitor tool streams the inbox (the monitor mode value).
3. turn, 4. both, 5. off — as before.

• agmsgd=on: do not ask which to use. Say "agmsgd is on: notices are delivered directly" and ask only whether to keep using it or switch to monitor (legacy).
• agmsgd=not-running reason=...: agmsgd is turned on but is not running, so do not say notices are delivered directly. Say so with the reason and ask whether to start it (agmsg delivery agmsgd starts it) or switch to monitor (legacy).
• agmsgd=unavailable reason=...: do not offer agmsgd; say the reason in one line, then ask for monitor (legacy), turn, both, or off (empty input means monitor).

To apply the choice, run ~/.agents/skills/agmsg/scripts/agmsg delivery <choice> --type claude-code --project "$(pwd)" with <choice> = agmsgd, monitor, turn, both or off (monitor (legacy) is the value monitor) and show its output and follow the printed AGMSG-DIRECTIVE block:

• agmsgd turns the background service on (daemon enable) and records the choice; the project then receives through agmsgd only, with no Monitor fallback, and a stopped agmsgd is reported with how to restart it. If it fails, say so and offer the other choices.
• Keep using agmsgd (it is on or turned on but not running): run agmsg delivery agmsgd the same way; it also records that this project uses agmsgd.
• monitor (legacy) (and turn, both, off) is a real opt-out: the CLI records that this project does not use agmsgd, so agmsgd stops delivering here and the project keeps the old path. agmsgd stays on for the install's other projects; when it says so, pass on its line that agmsg daemon disable turns agmsgd off for all of them.

1. 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). 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. If the team is in available_teams, run ~/.agents/skills/agmsg/scripts/team.sh <team> and check that the agent name you are about to use (reused or new) is not already in its roster.
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 rather than guessing reachability first — its exit code says whether it worked and, if not, why (see the "peek"/"poke"/"arrange" arguments below).

If no arguments provided (DEFAULT action — always do this when the command is invoked without arguments):

1. IMMEDIATELY run inbox check for each TEAM: ~/.agents/skills/agmsg/scripts/inbox.sh $TEAM $AGENT
2. Do NOT ask the user what to do — just run the inbox check.
3. If there are messages, read and respond appropriately. To reply:

~/.agents/skills/agmsg/scripts/send.sh $TEAM $AGENT <to_agent> "<message>"

An agmsgd notice is the same request. When a message arrives that reads [agmsg:<nonce>] New messages are waiting. Check your agmsg inbox., it came from agmsgd and means the same as invoking this command with no arguments: run ~/.agents/skills/agmsg/scripts/inbox.sh $TEAM $AGENT for each of your TEAMS and read your inbox there. check-inbox.sh is the per-turn hook's script; do not run it by hand for this. (A type that says otherwise below, such as a TUI monitor that owns the inbox, keeps its own rule.)