# agmsg

Adopt this skill: https://proskills.md/skills/other/fujibee-agmsg

Page: https://proskills.md/skills/other/fujibee-agmsg
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: SKILL.md
size: 8036
upstream: https://github.com/fujibee/agmsg/blob/HEAD/SKILL.md

````text
---
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
````

## File: README.md
upstream: https://github.com/fujibee/agmsg/blob/HEAD/README.md

````text
# agmsg

*[日本語](README.ja.md)*

[![CI](https://img.shields.io/github/actions/workflow/status/fujibee/agmsg/tests.yml?branch=main&label=CI&logo=github)](https://github.com/fujibee/agmsg/actions/workflows/tests.yml)
[![release](https://img.shields.io/github/v/release/fujibee/agmsg?label=release)](https://github.com/fujibee/agmsg/releases/latest)
[![license](https://img.shields.io/github/license/fujibee/agmsg)](LICENSE)

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

> **For AI agents:** see [`/llms.txt`](llms.txt) for a quick, machine-friendly orientation.

<a href="https://www.producthunt.com/products/agmsg?utm_source=badge-top-post-badge&utm_medium=badge" target="_blank">
  <picture>
    <source media="(prefers-color-scheme: dark)"
            srcset="https://api.producthunt.com/widgets/embed-image/v1/top-post-badge.svg?post_id=1165435&theme=dark&period=daily">
    <img src="https://api.producthunt.com/widgets/embed-image/v1/top-post-badge.svg?post_id=1165435&theme=light&period=daily"
         alt="agmsg — #5 Product of the Day on Product Hunt" width="250" height="54">
  </picture>
</a>

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.

<p align="center">
  <img src="docs/logos/supported-agents.png" width="780"
       alt="Supported agents: Claude Code, Codex, Gemini, GitHub Copilot, Antigravity, OpenCode, Hermes">
</p>

**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](docs/agmsg-demo.gif)

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](docs/screenshot.png)

## 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.

```bash
# 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](#delivery-modes) (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](#first-run) below.

Prefer to inspect the code first, track the latest `main`, or pick a custom command name? See [Install](#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](docs/remote-setup.md).

## 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](#agmsgd-beta-160) 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

```bash
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)](https://docs.npmjs.com/trusted-publishers) with [SLSA provenance](https://slsa.dev/) — 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`:

```bash
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
````
