llms.txt git:20261022.1a59590A

Immutable. This exact content never changes and is served at /api/v1/blob/5e689af11510d359.

# agmsg

> Cross-agent messaging for CLI AI agents. Claude Code, Codex, Gemini CLI, GitHub Copilot CLI, Antigravity, and OpenCode message each other directly through a shared local SQLite database — no daemon required, no network, no MCP. Just `bash` + `sqlite3`. (An optional resident service, agmsgd, is installed only if you choose it.)

## Quick Start

```bash
# 1. Install (one-liner; needs bash + sqlite3)
bash <(curl -fsSL https://raw.githubusercontent.com/fujibee/agmsg/main/setup.sh)

# 2. Restart your agent so it picks up the new skill

# 3. Invoke the command — it prompts for a team name, an agent name,
#    and a delivery mode on first use:
#      Claude Code / Copilot CLI:        /agmsg
#      Codex / Gemini CLI / Antigravity / OpenCode: $agmsg
```

Everyday commands (same across agents; shown here as the Claude Code `/agmsg` form):

```
/agmsg                      # check inbox
/agmsg send <agent> <msg>   # send a message to a teammate
/agmsg team                 # list team members
/agmsg history              # replay message history
/agmsg mode <monitor|turn|both|off>   # switch delivery mode (which modes are valid depends on the agent type)
/agmsg spawn <type> <name>  # launch a new peer agent in its own terminal
/agmsg spawn <type> <name> --boot-prompt "<task>"   # ...and start it on <task> in its first turn
```

Alternate installs: `npx agmsg` (or `npm i -g agmsg && agmsg install`), or the Claude Code
plugin marketplace (`/plugin marketplace add fujibee/agmsg`). All paths land at
`~/.agents/skills/agmsg/`. See [README.md](README.md) for details.

## Key concepts

- **team** — a named group of agents that can message each other.
- **agent** — a sender/receiver identity within a team (a single session can hold
  multiple roles via `actas`).
- **delivery method** — how incoming messages reach a recipient: agmsgd (the
  recommended, optional resident service; delivers to Claude Code and Codex, including
  on Windows; turned on only when the person picks it), `monitor (legacy)` (real-time
  push), `turn` (pull at the end of each turn), `both` (Claude Code only), or `off`.
  Each agent type supports a subset.
- **4-axis driver model** — `storage` (sqlite default), `agent` (per-runtime hook
  differences), `delivery`, and `terminal` (detected, not configured) are orthogonal,
  each with one active swappable driver.
- **AGMSG-DIRECTIVE** — a machine-readable line agmsg emits to ask the host agent to
  take an action (e.g. start its Monitor tool, install a missing dependency).

## Read first

- [README.md](README.md): install, first run, delivery modes, per-agent usage, FAQ.

## Docs

- [ARCHITECTURE.md](ARCHITECTURE.md): the 4-axis driver model, storage shape, vocabulary.
- [docs/design.md](docs/design.md): design rationale and internal shape.
- [docs/actas.md](docs/actas.md): multiple roles per project, exclusivity locks.
- [docs/teams.md](docs/teams.md): team registry and membership model.
- [docs/spec/driver-interface.md](docs/spec/driver-interface.md): the formal driver contract.
- [docs/adr/](docs/adr/): architecture decision records (the "why").
- [docs/opencode.md](docs/opencode.md): OpenCode-specific integration.
- [docs/codex-monitor-beta.md](docs/codex-monitor-beta.md): Codex monitor (legacy) delivery through the app-server bridge.
- [docs/plugins.md](docs/plugins.md): external drivers and the trust model.
- [CONTRIBUTING.md](CONTRIBUTING.md): how to propose changes.

## Key source files

agmsg is bash, not a compiled package. Top-level `scripts/*.sh` files are the
directly-invokable commands; `scripts/drivers/<axis>/` holds axis drivers and
`scripts/lib/` holds shared helpers.

- [scripts/send.sh](scripts/send.sh): append a message (the write path).
- [scripts/inbox.sh](scripts/inbox.sh): read unread messages for an agent.
- [scripts/watch.sh](scripts/watch.sh): stream incoming messages (monitor mode).
- [scripts/join.sh](scripts/join.sh): join or create a team.
- [scripts/whoami.sh](scripts/whoami.sh): resolve this project's agent identity.
- [scripts/delivery.sh](scripts/delivery.sh): get/set the delivery mode.
- [scripts/daemon.sh](scripts/daemon.sh): enable, start, stop, disable and inspect the optional agmsgd service.
- [scripts/spawn.sh](scripts/spawn.sh) / [scripts/despawn.sh](scripts/despawn.sh): launch / tear down a peer agent.
- [scripts/history.sh](scripts/history.sh): replay a room's history.
- [SKILL.md](SKILL.md): the agent-facing skill definition (full command reference).