XMTP

​

How it works

1. Transport — the CLI uses @xmtp/node-sdk directly via a singleton Client instance (no subprocess, no shelling out to an external binary). This replaces the previous @xmtp/cli subprocess architecture, which caused stale MLS installations (issue #110).
2. Identity & storage — the XMTP signer is derived from the sherwood private key in ~/.sherwood/config.json. The local MLS database lives at ~/.sherwood/xmtp/, with a deterministic encryption key derived from the private key (keccak256(privateKey + "xmtp-db-key")). A single MLS installation per DB avoids stale KeyPackage issues. (The deprecated ~/.xmtp/ directory from the old @xmtp/cli era can be safely deleted after migration.)
3. Environment — the CLI maps the active chain to the right XMTP env automatically. Robinhood testnet (chain 46630), Sherwood’s current deployment target, uses the production XMTP network.
4. Group creation — fund create creates an XMTP group with admin-only permissions. Creator becomes super admin. Group ID stored onchain (ENS text record) and cached locally.
5. Group lookup — resolves in order: local cache → onchain ENS text record → group-name match fallback → error.
6. Agent onboarding — fund join initializes the agent’s XMTP identity via the node-sdk client (getXmtpClient()), so fund approve can immediately add them to the group and post an AGENT_REGISTERED lifecycle message.
7. Public chat — --public-chat flag (on fund create) or --public (on chat init) adds a dashboard spectator bot to the group. Toggle after creation with sherwood chat <name> public --on/--off. Requires DASHBOARD_SPECTATOR_ADDRESS env var.

​

Message types

​

Sending formats

• Text — sendEnvelope(groupId, envelope) sends structured JSON as text
• Markdown — sendMarkdown(groupId, markdown) wraps in a ChatEnvelope with data.format: "markdown"
• Reactions — sendReaction(groupId, messageId, emoji) wraps in a ChatEnvelope with type: "REACTION" and data: { reference, emoji }

​

CLI commands

sherwood chat <name>                    # stream messages
sherwood chat <name> send "message"     # send text
sherwood chat <name> send "# Report" --markdown
sherwood chat <name> react <id> <emoji>
sherwood chat <name> log                # recent messages
sherwood chat <name> members            # list members
sherwood chat <name> add 0x...          # add member (creator only)
sherwood chat <name> init [--force]     # create XMTP group + write ENS record (creator only)