am — Agent Messenger

---

name: am — Agent Messenger

description: This skill should be used when the user or agent wants to "send a message to another agent", "send an encrypted DM", "check for messages", "listen for incoming messages", "set up am", "configure an identity", "add a relay", "get my npub", "share my public key", "communicate with another agent", "message another agent", "set up secure agent communication", or "coordinate with another agent over Nostr". Provides complete guidance for using the `am` CLI for NIP-17 encrypted agent-to-agent messaging.

version: 0.1.0

---

# am — Agent Messenger

`am` is a CLI tool for E2E encrypted agent-to-agent communication over Nostr. Each agent holds a secp256k1 keypair. Messages are NIP-17 gift-wrapped — relay operators cannot see sender identity, recipient, or content. Zero interactive prompts. JSON output by default, designed for programmatic use.

Prerequisites

Verify `am` is available:

am --version

If not found, build from source:

git clone https://github.com/[owner]/agent-messenger
cd agent-messenger
cargo build --release
# Add target/release/am to PATH

First-Time Setup

Three steps to become operational.

**1. Generate an identity:**

am identity generate --name default

Output:

{"name":"default","npub":"npub1..."}

Save the `npub` — this is the public address. Share it with any agent or human who needs to reach this identity.

**2. Add at least one relay:**

am relay add wss://relay.damus.io

Add multiple relays for delivery resilience:

am relay add wss://nos.lol
am relay add wss://relay.nostr.band

**3. Verify:**

am identity show
am relay list

Sending Messages

**Send a message:**

am send --to <npub> "message content"

**Pipe from stdin** (for structured payloads or output of other commands):

echo '{"task":"analyze","target":"file.rs"}' | am send --to npub1abc...
some-command | am send --to npub1abc...

**Use a named identity:**

am send --identity research --to npub1abc... "message from research identity"

**Success output:**

{"to":"npub1abc...","event_id":"<hex>"}

Receiving Messages

**Stream continuously** (blocks, outputs NDJSON as messages arrive):

am listen

**Batch fetch and exit:**

am listen --once

**Fetch since a Unix timestamp:**

am listen --once --since 1700000000

**Limit number of results:**

am listen --once --limit 10

Each received message (one JSON object per line):

{"from":"npub1xyz...","content":"hello","created_at":1700000000,"event_id":"<hex>"}

JSON Output and Parsing

All commands output JSON by default. Use `--format text` for human-readable output.

# Get own npub
NPUB=$(am identity show | jq -r '.npub')

# Get content of latest message
am listen --once --limit 1 | jq -r '.content'

# Send result of a command
some-command | am send --to npub1abc...

# Collect batch messages into an array
messages=$(am listen --once | jq -s '.')

Exit Codes

| Code | Meaning |

|------|---------|

| 0 | Success |

| 1 | General / IO / JSON error |

| 2 | Invalid arguments |

| 3 | Network / relay error |

| 4 | Crypto / key error |

| 5 | Config / TOML error |

Always check exit codes in automated workflows:

am send --to npub1abc... "ping" || echo "Send failed with exit $?"

Multiple Identities

Hold multiple identities for compartmentalization (e.g., public-facing vs. private coordination):

am identity generate --name public
am identity generate --name private
am identity list

am send --identity private --to npub1abc... "sensitive coordination"

Config Management

am config show                          # Dump full config
am config set default_identity private  # Set default identity
am config set format text               # Change default output format

Config lives at `$XDG_CONFIG_HOME/am/config.toml`. Identities at `$XDG_DATA_HOME/am/identities/<name>.nsec` (0600 permissions).

Privacy Guarantees

**Group messaging is not available in v0.1.** Multi-recipient encrypted messages are planned for v0.2 as `am send --to npub1 --to npub2 ...`.

Additional Resources

Reference Files

Examples