agmsg

Files (200)

• marketplace.json · .claude-plugin/
• plugin.json · .claude-plugin/
• .gitattributes
• dependabot.yml · .github/
• enforced-assertions-baseline · .github/
• errexit-status-reads-baseline · .github/
• herdr-cli-routing-allowlist · .github/
• bats-file-seconds.tsv · .github/scripts/
• check-enforced-assertions.sh · .github/scripts/
• check-errexit-status-reads.sh · .github/scripts/
• check-herdr-cli-routing.sh · .github/scripts/
• check-unguarded-env-reads.sh · .github/scripts/
• pipe-holders.awk · .github/scripts/
• run-bats-timed.sh · .github/scripts/
• shard-tests.sh · .github/scripts/
• summarize-bats-timings.sh · .github/scripts/
• unguarded-env-reads-baseline · .github/
• app-release.yml · .github/workflows/
• pages.yml · .github/workflows/
• release.yml · .github/workflows/
• tests.yml · .github/workflows/
• verify-versions.yml · .github/workflows/
• .gitignore
• ARCHITECTURE.ja.md
• ARCHITECTURE.md
• CHANGELOG.md
• CONTRIBUTING.ja.md
• CONTRIBUTING.md
• LICENSE
• PRIVACY.md
• README.ja.md
• README.md
• RELEASING.md
• SECURITY.md
• SKILL.md
• VERSION
• .gitignore · app/
• extensions.json · app/.vscode/
• AGMSG_CORE_REF · app/
• README.md · app/
• index.html · app/
• package.json · app/
• pnpm-lock.yaml · app/
• .gitignore · app/poc-inject/
• Cargo.lock · app/poc-inject/
• Cargo.toml · app/poc-inject/
• main.rs · app/poc-inject/src/
• agmsg-logo.png · app/public/
• agmsg-mark.png · app/public/
• favicon-32.png · app/public/
• build-notarize.sh · app/scripts/
• bundle-core.sh · app/scripts/
• sign-windows.ps1 · app/scripts/
• .gitignore · app/src-tauri/
• Cargo.lock · app/src-tauri/
• Cargo.toml · app/src-tauri/
• build.rs · app/src-tauri/
• default.json · app/src-tauri/capabilities/
• 128x128.png · app/src-tauri/icons/
• 128x128@2x.png · app/src-tauri/icons/
• …and 140 more

SKILL.md (first lines)

<!-- 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)". 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 -->
  5. **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.

  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). 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):**

From fujibee/agmsg, MIT.