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

Agent Messaging

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.

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

How to use

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 flow only drops the skill content into ~/.claude/plugins/cache/). Before any other command, bootstrap if needed:

if [ ! -d ~/.agents/skills/agmsg ]; then
  # Locate the plugin install script (any version), run it once.
  installer=$(ls ~/.claude/plugins/cache/fujibee-agmsg/agmsg/*/install.sh 2>/dev/null | head -1)
  if [ -n "$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

After this runs once, ~/.agents/skills/agmsg/ is populated and you can skip Step 0 on future invocations.

Step 1: Check identity

~/.agents/skills/agmsg/scripts/whoami.sh "$(pwd)" <type>
# type: claude-code, codex, gemini, antigravity, copilot
# Returns: agent=... / multiple=true ... / suggest=true ... / not_joined=true ...

Step 2a: If not in a team — join one

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 run join.sh. Go directly to the remote pull command under Step 2b. Before pulling, run 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 here so the user can register a new local agent in the team that pull just created.

Ask the user for a team name. If it's an existing team, run team.sh <team> first to see the current roster 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. For a brand-new team, skip the roster check and just ask. Then run:

~/.agents/skills/agmsg/scripts/join.sh <team> <agent_name> <type> "$(pwd)" [--force]

Do NOT manually edit config files. Always use join.sh. If the name was recently renamed away with rename.sh, join.sh refuses to revive it (printing the new name it maps to) instead of silently re-registering it — this guards against a CLI slash-command history resubmitting actas <old_name> after a rename. Pass --force only for a deliberate, unrelated reuse of that exact name.

Step 2b: If already in a team — execute command

Default (no arguments): IMMEDIATELY check inbox. Do NOT ask what to do.

# Check inbox (marks messages as read) — DEFAULT action
~/.agents/skills/agmsg/scripts/inbox.sh <team> <agent_id>

# Send a message (from/to must already be registered in <team>; add --force to bypass)
~/.agents/skills/agmsg/scripts/send.sh <team> <from_agent> <to_agent> "<message>" [--force]

# Message history
~/.agents/skills/agmsg/scripts/history.sh <team> [agent_id] [limit]

# Export a team's message history as JSONL — one message_sent record per line,
# chronological. Default to stdout (pipeable); --out <file> writes a file.
# --agent limits to one agent; --limit keeps the most recent N (omit = all
# currently retained). Output is plaintext (the local store is plaintext).
~/.agents/skills/agmsg/scripts/export.sh --team <team> [--agent <agent>] [--limit N] [--out <file>]

# List team members
~/.agents/skills/agmsg/scripts/team.sh <team>

# List every locally known team (read-only, secret-free — "agmsg team list").
# Distinct from `team.sh <team>` above: check for "team list" FIRST so
# "list" is never mistaken for a team name. --json emits a strict,
# versioned object ({schema_version, teams: [{name, remote_team_id, scope,
# binding_state}]}) and exits non-zero with NO payload if any team was
# unreadable or the count was truncated — never a partial list dressed up
# as complete. See scripts/team-list.sh's own header comment for the exact
# enums and why onboarding_state/promote_eligible/blocked_reason are
# deliberately NOT in this schema yet (their meaning depends on ADR 0010,
# which hasn't landed).
~/.agents/skills/agmsg/scripts/team-list.sh [--json] [--scope all|project] [<project_path>]

# Leave a team
~/.agents/skills/agmsg/scripts/leave.sh <team> <agent_id>

# Rename a team (moves dir, updates config + messages).
# After renaming, each existing member should re-run whoami.sh to refresh
# their cached team name in any running session.
~/.agents/skills/agmsg/scripts/rename-team.sh <old_team> <new_team>

# Show the installed version — the git-describe provenance string recorded at
# install time (tag + commits-since + abbreviated commit, plus -dirty when
# installed from a tree with uncommitted changes). See #117.
~/.agents/skills/agmsg/scripts/version.sh

# Clear registrations for the current project/type.
# A trailing <session_id> additionally releases any actas exclusivity locks
# this session held on <agent_id> so peers can pick them up immediately.
~/.agents/skills/agmsg/scripts/reset.sh "$(pwd)" <type> [agent_id] [session_id]

# Set delivery mode for this project.
#   monitor — real-time push via SessionStart + Monitor tool (claude-code only)
#   turn    — Stop-hook pulls at the end of each assistant turn
#   both    — monitor primary, turn as fallback
#   off     — no automatic delivery
~/.agents/skills/agmsg/scripts/delivery.sh set <mode> <type> "$(pwd)"
~/.agents/skills/agmsg/scripts/delivery.sh status <type> "$(pwd)"

# Multiple roles per project (one CC = one active role).
# Claude Code: `actas` claims an exclusivity lock for <name> across sessions
# and restarts the Monitor filtered to <name> only; peer watchers stop
# subscribing to <name> while this session holds the lock. `drop` releases.
# Codex: actas is send-side only (no stable session_id during slash commands
# → no peer-visible lock). See README "Codex caveat" for details.
# If <name> is new and none was given upfront (bare `actas`, or the user asks
# for a suggestion), check the target team's roster first (team.sh <team>).
# 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 names. Either way, names must not
# collide with the roster. Ask the user to pick before continuing.
~/.agents/skills/agmsg/scripts/actas-claim.sh "$(pwd)" <type> <name> "$session_id"
~/.agents/skills/agmsg/scripts/reset.sh "$(pwd)" <type> <name> "$session_id"

# (Both of the above are normally driven by `/agmsg actas <name>` and
#  `/agmsg drop <name>` slash commands, which also handle the Monitor
#  TaskStop + relaunch dance described in the cmd template.)

# Spawn a NEW agent process that takes an actas identity on boot.
# Pre-joins <name> to a team, then launches the agent CLI in a tmux pane/window
# (when run inside tmux) or a new OS terminal, with `/agmsg actas <name>` as the
# initial prompt. By default it BLOCKS until the new agent's watcher attaches
# (prints `status=ready`), so a leader can send work right after spawn returns
# without losing it to the agent's cold start. claude-code/codex only; macOS
# primary, Linux/Windows best-effort. Non-tmux + no usable terminal (headless)
# errors out.
#   --project <path>     project to launch in (default: $PWD)
#   --team <team>        team to join into (default: auto-resolved from project)
#   --window             new tmux window instead of splitting the current one
#   --split h|v          tmux split direction (default h)
#   --terminal <tmpl>    terminal command template ({cmd} = path to the boot
#                        script) for the non-tmux path; overrides $AGMSG_TERMINAL
#                        / config spawn.terminal. macOS default uses `open -a`
#                        (no Automation/TCC permission prompt).
#   --no-wait            don't block on readiness (fire-and-forget)
#   --ready-timeout N    seconds to wait for readiness (default 90; on timeout
#                        prints status=timeout and exits 3). Codex skips the
#                        wait (it has no Monitor).
#   --boot-prompt <text>      hand the new agent an initial task: the boot prompt
#                        becomes the actas command followed (newline-separated)
#                        by <text>, so it claims its identity AND starts the task
#                        in its first turn. The only way to give a one-shot goal
#                        to a codex peer (no Monitor → a post-spawn send to its
#                        idle session is never noticed).
~/.agents/skills/agmsg/scripts/spawn.sh <claude-code|codex> <name> [options]

# Tear down a spawned member — the inverse of spawn.
# Default (graceful): sends a `ctrl:despawn` control message to <name>; the
# member's watcher drops its own role (releasing the actas lock + registration)
# and closes its own tmux pane, ending the agent. Blocks until the lock releases
# (--timeout, default 30s) then prints `status=ok`; on timeout prints
# status=timeout and exits 3 (retry with --force). Only an exclusive watcher
# dedicated to <name> acts on it — the despawning session is never torn down.
# --force: skip the message and tear the member down from the placement recorded
# at spawn time (kill its tmux pane/window, drop its registration) — for a dead
# watcher or a codex member (no Monitor). A hand-started member with no placement
# record can't be --forced.
#   --force              tear down from the recorded placement, no message
#   --timeout N          seconds to wait for graceful teardown (default 30)
~/.agents/skills/agmsg/scripts/despawn.sh <team> <from> <name> [--force] [--timeout N]

Rename

If argument starts with "rename" but not "rename-team":

1. Accept only an explicit user request. Parse either <team> <old_name> <new_name>, or <old_name> <new_name> only when this agent belongs to exactly one team.
2. Never invent either name. Before execution, repeat the resolved team, old name, and new name and ask the user to confirm. Wait for confirmation.
3. Run: bash ~/.agents/skills/agmsg/scripts/rename.sh <team> <old_name> <new_name>
4. Show the result. For a connected team, the member_renamed journal event propagates the rename to other machines.

If argument starts with "rename-team":

1. Accept only an explicit user request. Parse <old_team> <new_team>.
2. Never invent either team name. Before execution, repeat the old and new team names and ask the user to confirm. Wait for confirmation.
3. Run: bash ~/.agents/skills/agmsg/scripts/rename-team.sh <old_team> <new_team>
4. Show the result.

Remote sync

Remote setup is no-auth. Do not ask for a token or create one.

If argument starts with "remote connect":

1. Parse the required --endpoint <url> and <team>, plus optional --e2ee.
2. Run: bash ~/.agents/skills/agmsg/scripts/remote.sh connect --endpoint <url> [--e2ee] <team>
3. Show the output to the user. Plain sync is the default; pass --e2ee only when the user explicitly requests end-to-end encryption. The choice is fixed by the first connect.
4. End by showing this copy-paste command for the other machine, with the actual endpoint and team substituted: bash ~/.agents/skills/agmsg/scripts/remote.sh pull --endpoint <actual-url> <actual-team>

If argument starts with "remote pull":

1. When the user asks to join or bring in a team that already exists on a server, NEVER use join.sh, create a team, or create a same-named local team. Always use remote pull.
2. Before pulling, check for a same-named local team. If one already exists without an active remote connection, stop and ask the user how to proceed; do not overwrite, merge, connect, or rename it on your own.
3. Parse the required --endpoint <url> and <team>, plus optional --team-id <uuid>.
4. Run: bash ~/.agents/skills/agmsg/scripts/remote.sh pull --endpoint <url> [--team-id <uuid>] <team>
5. Show the output to the user.

Machine B needs its own install, not just its own environment variables. Only remote.sh, remote-sync.sh, key.sh and the two internal helpers read AGMSG_SYNC_CONNECTION_DIR; send.sh, history.sh, team.sh and inbox.sh resolve the team config from the install directory. So a pull driven by environment variables alone succeeds, and the send that is supposed to confirm it then reports the team as missing — the failure lands one step after the cause. See "Use a separate install for testing" in docs/remote-setup.md.

If argument starts with "remote unlock":

1. Parse <team>, --bundle <file>, and --confirm-digest <sha256>.
2. Run: bash ~/.agents/skills/agmsg/scripts/remote.sh unlock <team> --bundle <file> --confirm-digest <sha256>
3. The snapshot digest must be compared over a separate live channel. Never infer or auto-confirm it. The bundle is permanent secret key material; tell the user to transfer and handle it only through their own trusted channel, never by pasting it into agent chat.
4. Show the complete result, including the imported-envelope count and engine PID.
5. The advanced form with repeatable --snapshot plus --identity or --identity-stdin remains available when explicitly requested.

If argument starts with "remote status":

1. Parse an optional <team> and --json.
2. Run: bash ~/.agents/skills/agmsg/scripts/remote.sh status [<team>] [--json]
3. Show the output to the user.

If argument starts with "remote sync start":

1. Parse the required <team>.
2. Run: bash ~/.agents/skills/agmsg/scripts/remote.sh sync start <team>
3. Show the output to the user.

If argument starts with "remote disconnect":

1. Parse the required <team>.
2. Run: bash ~/.agents/skills/agmsg/scripts/remote.sh disconnect <team>
3. Show the output to the user.

If argument starts with "remote forget":

1. Parse the required <team>. This permanently deletes that team's local roster, history, keys, trust, and sync state, but never changes the server.
2. Do not add --yes yourself. Run: bash ~/.agents/skills/agmsg/scripts/remote.sh forget <team>
3. The command requires the user to confirm in their terminal. If this agent has no interactive terminal, show the deletion summary and tell the user to rerun the displayed command directly; never bypass confirmation for them.

End-to-end encryption

If argument starts with "key generate" followed by an optional team name:

1. Run: bash ~/.agents/skills/agmsg/scripts/key.sh generate [<team>]
2. Show the full output to the user, including the mandatory key-backup notice.

If argument starts with "key show":

1. Parse an optional team name and --reveal-secret.
2. Run: bash ~/.agents/skills/agmsg/scripts/key.sh show [<team>] [--reveal-secret]
3. --reveal-secret requires a real interactive terminal and is refused in agent mode. Tell the user to run it directly in their own terminal.
4. Show the output to the user.

If argument starts with "key handoff" followed by a team name:

1. Parse optional --out <file> and run: bash ~/.agents/skills/agmsg/scripts/key.sh handoff <team> [--out <file>]
2. The output bundle contains every epoch identity and is itself permanent secret key material. Never read it into agent chat or display its contents.
3. Show the bundle path, latest snapshot digest, and full secrecy warning.

If argument starts with "key import" followed by a team name:

1. Do not ask the user to paste the private identity into this chat, and do not run the command yourself. Tell the user to run this in their own terminal:

   read -rsp 'Identity: ' IDENTITY; echo
   printf '%s' "$IDENTITY" | ~/.agents/skills/agmsg/scripts/key.sh import <team> --identity-stdin
   unset IDENTITY
   

2. Ask them to paste back only the command output, never the identity itself.
3. Do not offer an environment-variable path. An identity file is a permanent secret; always use the human-in-own-terminal flow above.

If argument starts with "key rotate" followed by a team name:

1. Rotation mints a replacement epoch for a team that already has a key and announces it on the roster journal. It requires an existing current key, an identity journal (connect or migrate the team first), and age; it refuses with a message naming whichever is missing.
2. Confirm with the user before running it. It changes the team's key state, and every other machine has to receive the new identity out of band.
3. Run: bash ~/.agents/skills/agmsg/scripts/key.sh rotate <team>
4. Show the output: epoch, key_id, and recipient fingerprint. The private key is never written to the journal. Revealing it needs key show <team> --key-id <id> --reveal-secret, which is refused in agent mode — tell the user to run that in their own terminal.
5. Messages before the acknowledged rotation boundary remain readable with the old key.

Device pairing (key request / key approve) is not implemented — they are not key.sh subcommands, so a call prints usage and exits 1. If the user asks for one, tell them so instead of attempting to run it.

Permission prompts (Claude Code)

Every agmsg step above runs through the host's Bash tool, so on Claude Code each call is gated by the permission system until you allowlist the script directory. Add these to ~/.claude/settings.json (or project-level .claude/settings.local.json):

{
  "permissions": {
    "allow": [
      "Bash(~/.agents/skills/agmsg/scripts/*)",
      "Bash(/Users/<you>/.agents/skills/agmsg/scripts/*)",
      "Bash(bash ~/.agents/skills/agmsg/scripts/*)",
      "Bash(bash /Users/<you>/.agents/skills/agmsg/scripts/*)"
    ]
  }
}

Four entries rather than one because a rule matches the command string as written: the scripts are invoked both as ~/... and as an absolute path, and with or without an explicit bash prefix. Replace /Users/<you> with your home directory, and the agmsg path segment with your command name if you installed under a different one.

Every subcommand needs its own match. Claude Code's permission docs state that a rule must match each subcommand independently, and that the recognized separators are &&, ||, ;, |, |&, &, and newlines. Chaining two agmsg scripts is fine — both match the entries above. What reintroduces the prompt is mixing in a command those entries do not cover: delivery.sh status … ; printenv AGMSG_SPAWNED prompts because of the printenv, not because of the ;. Splitting it into its own call does not remove that prompt — it only keeps it from gating the agmsg call. Allowlist the command as well if it needs to be prompt-free.

Sandbox compatibility (Claude Code)

When Claude Code's sandbox is enabled, watch.sh (monitor mode) runs inside the sandbox and needs to write pidfiles and SQLite WAL files under ~/.agents/skills/agmsg/. Add an allowlist entry to ~/.claude/settings.json (or project-level .claude/settings.local.json):

{
  "sandbox": {
    "filesystem": {
      "allowWrite": [
        "~/.agents/skills/agmsg/"
      ]
    }
  }
}

The allowlist merges across scopes and takes effect immediately — no restart needed. If agmsg was installed under a custom command name (e.g. m), adjust the path accordingly.

Note on BASH_SOURCE: The sandboxed Bash tool runs commands via pipe/eval, so BASH_SOURCE[0] is empty inside sourced functions like storage.sh. This is handled internally — watch.sh resolves SKILL_DIR from $0 (which works correctly when invoked as a command), and storage.sh falls back to that value. No user configuration needed.

Architecture

• Storage: SQLite with WAL mode in ~/.agents/skills/agmsg/db/messages.db
• Teams: ~/.agents/skills/agmsg/teams/<name>/config.json
• Concurrency: WAL allows multiple readers + 1 writer without conflicts
• No daemon: Direct DB access via sqlite3 CLI
• Dependencies: bash, sqlite3 (no python3 required) for core messaging; remote/key additionally need curl, python3, and age/age-keygen, but only if those commands are used

agmsg

日本語

Cross-agent messaging for CLI AI agents. No daemon, 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 monitor-mode Claude Code instances, 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:

In real use it looks like this — Claude Code asking Codex for a code review and getting it back, all over 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. There is no daemon, no socket, no broker — the file is the shared floor and the agents take turns on 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 & Codex

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 naturally 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 automatically. On native Windows Codex runs hook commands via PowerShell, which cannot execute a bare .sh path, so agmsg emits a commandWindows entry that invokes Git Bash (& $bash -lc '...'). No setup needed — see windows_wrap() in scripts/delivery.sh.

• Interactive / agent-typed commands call the scripts through Git Bash, e.g. bash -lc 'scripts/whoami.sh "$(pwd)" codex'.

• Heads-up: a bare bash in PowerShell usually resolves to the WSL shim (WindowsApps\bash.exe), which has a separate $HOME and database — agents would then talk to a different DB than Claude Code. Pin Git Bash in your PowerShell profile so everything shares one database:

  Set-Alias bash 'C:\Program Files\Git\bin\bash.exe'
  

First run

Open your project in your agent (Claude Code, Codex, Gemini CLI, etc.) and run:

/agmsg              # Claude Code, Copilot CLI
$agmsg              # Codex, Gemini CLI, Antigravity

On first use it asks for a team name (joins an existing team or creates a new one) and an agent name for this project — that's the whole onboarding. After that, talk to your agent naturally:

• "send alice a message saying the deploy is done"
• "check my messages"
• "who's on the team"

The agent picks the right subcommand and runs it for you. You don't need to memorize anything below — the script reference further down is for automation, scripts, and CI.

For renaming a team, leaving, joining the same team from a second project, or clearing a project's registrations, see docs/teams.md.

Multiple roles per project (actas / drop)

Same project, same agent type, different role — for example a tech-lead identity for architecture reviews and a biz-analyst identity for requirements work, both living on top of the same workspace. Toolset and assets are shared; only the role differs.

/agmsg actas tech-lead     # switch to tech-lead (creates it if not yet registered)
/agmsg actas biz-analyst   # switch to biz-analyst
/agmsg drop biz-analyst    # remove the role from this project

actas <name> is exclusive across sessions: it switches both sending and receiving to <name>, claims a lock that stops peer sessions from subscribing to the same name, and refuses if another session already holds it. drop releases the lock. If a lock g