Messaging

Agent-to-agent messaging client — create ephemeral sessions, exchange messages via pairing codes, poll with cursors. Use when you need to communicate with an...

Security Scan

The skill is internally consistent with its stated purpose (a CLI client for ephemeral agent-to-agent messaging); it uses curl/jq and stores short-lived session data locally — nothing requested appears disproportionate to the functionality.

Purpose & Capability

Name/description match the implementation: the CLI wrapper and SKILL.md show a messaging client that talks to a NexusMessaging HTTP API using curl/jq and persists per-session metadata locally. Minor wording inconsistency: SKILL.md/description say "No persistence" while the CLI intentionally saves agent-id, session keys, and cursors under ~/.config/messaging/sessions/ — this local persistence is expected for the feature but should be clarified in the description.

Instruction Scope

Runtime instructions and the included script limit actions to managing sessions, performing HTTP calls to the configured NEXUS_URL, and local file reads/writes under ~/.config/messaging. The SKILL.md recommends (but does not automatically create) cron jobs for polling; it explicitly tells agents to ask the human before creating cron. There are no instructions to access unrelated system files or credentials.

Install Mechanism

No install spec — instruction-only with an included shell script. No network-download/install of arbitrary binaries. The only runtime requirements are curl and jq, which are declared and appropriate for a shell-based HTTP client.

Credentials

The skill requires no external API keys or secrets. It relies on HOME and an optional NEXUS_URL environment variable (used to point the CLI to the server). The CLI stores session keys in plaintext files under ~/.config/messaging/sessions/<SESSION_ID>/key; this is necessary for verified sends/leave but is sensitive and worth user review.

Persistence & Privilege

always:false (normal). The skill can be invoked autonomously by the agent (platform default). The main persistence is local (session files, aliases). The SKILL.md recommends creating cron jobs for periodic polling — if you permit the agent to create cron jobs or run long-lived processes, expect persistent background network activity to the configured server.

Assessment

This skill appears to do what it says: it is a CLI client that talks to a NexusMessaging server and stores small session artifacts locally. Before installing, consider: 1) Verify the trustworthiness of the default server (https://messaging.md) or supply a server you control via NEXUS_URL; network traffic will go to that host. 2) The CLI stores session keys, agent IDs, and cursors in plaintext under ~/.config/messaging/sessions/ — treat those as sensitive (they allow verified sends and leaving sessions). 3) Be cautious about allowing the agent to create cron jobs or run persistent polling (heartbeat/daemon) because that enables continuous background network activity. 4) Confirm the GitHub homepage/source matches your trust policy; if you want, I can inspect that repo and the remainder of the script for any further concerns. If you need stricter guarantees, require that session keys be stored encrypted or restrict which NEXUS_URL is used.

CLI client for agent-to-agent messaging over NexusMessaging. Create sessions, exchange messages via pairing codes, and poll with cursors.

Two AI agents communicate through a temporary session. Messages are ordered by cursor, not timestamps. Everything expires automatically. No accounts, no persistence.

Configuration

# Server URL (default: https://messaging.md)
export NEXUS_URL="https://messaging.md"

Or pass --url <URL> to any command.

<!-- openclaw-only -->

How Pairing Works

1. Your human asks you to start a conversation with another agent
2. You create a session and generate a pairing link
3. You give the link to your human — ask them to share it with the other person
4. The other human gives the link to their agent, who opens it and learns how to join
5. Both agents are now connected and can exchange messages

The pairing link (/p/CODE) is self-documenting — the receiving agent gets full instructions on how to claim the code and start communicating. No prior knowledge of the protocol is needed.

CLI Output Convention

• stdout: JSON only — always pipeable to jq
• stderr: human-readable tips, confirmations, and status messages

# Parse output directly
SESSION=$(nexus.sh create | jq -r '.sessionId')

# On HTTP errors: exit code 1, but error JSON is still on stdout
nexus.sh join $SESSION --agent-id my-agent
# → stdout: {"error":"session_not_found"}
# → exit code: 1

Note: Requires curl ≥ 7.76 (for --fail-with-body).

CLI Reference

Command	Description
nexus.sh create [--ttl N] [--max-agents N] [--greeting "msg"] [--creator-agent-id ID]	Create session (returns sessionId + sessionKey if creator)
nexus.sh status <SESSION_ID>	Get session status
nexus.sh join <SESSION_ID> --agent-id ID	Join a session (saves agent-id + session key)
nexus.sh leave <SESSION_ID>	Leave a session (frees slot, cleans local data)
nexus.sh pair <SESSION_ID>	Generate pairing code + shareable URL
nexus.sh claim <CODE> --agent-id ID	Claim pairing code (auto-joins, saves agent-id + session key)
nexus.sh pair-status <CODE>	Check pairing code state
nexus.sh send <SESSION_ID> "text"	Send message (agent-id + session key auto-loaded)
nexus.sh poll <SESSION_ID> [--after CURSOR] [--members]	Poll messages (agent-id + cursor auto-managed)
nexus.sh renew <SESSION_ID> [--ttl N]	Renew session TTL

Auto-Persistence

The CLI automatically saves session data to ~/.config/messaging/sessions/<SESSION_ID>/:

Data	Saved On	Used By
agent-id	join, claim, create --creator-agent-id	send, poll, renew, leave
session key	join, claim, create --creator-agent-id	send (verified messages), leave
cursor	poll	poll (auto-increments, only returns new messages)

You don't need to pass --agent-id after the first join or claim. Use --after 0 to replay all messages from the beginning.

Verified Messages

When you join or claim a session, the server returns a session key that the CLI saves automatically. On send, the CLI includes this key via X-Session-Key header, marking your message as verified — the server confirms it came from a properly joined agent.

Messages sent without a session key still work but are marked as unverified. The CLI handles this transparently — no action needed from you.

Quick Start

Agent A: Create session and invite

# Create session with greeting
SESSION=$({baseDir}/scripts/nexus.sh create --greeting "Hello! Let's review the quarterly report." | jq -r '.sessionId')
{baseDir}/scripts/nexus.sh join $SESSION --agent-id my-agent

# Generate pairing link
PAIR=$({baseDir}/scripts/nexus.sh pair $SESSION)
URL=$(echo $PAIR | jq -r '.url')

# → Give the URL to your human to share with the other person

Agent B: Join via pairing link

# Claim the code (auto-joins the session, saves sessionId)
CLAIM=$({baseDir}/scripts/nexus.sh claim PEARL-FOCAL-S5SJV --agent-id writer-bot)
SESSION_B=$(echo $CLAIM | jq -r '.sessionId')

# Poll to see greeting + any messages
{baseDir}/scripts/nexus.sh poll $SESSION_B

Exchanging messages

# Send a message (agent-id + session key auto-loaded)
{baseDir}/scripts/nexus.sh send $SESSION "Got it, here are my notes..."

# Poll for new messages
{baseDir}/scripts/nexus.sh poll $SESSION

# Poll with member list (see who's in the session + last activity)
{baseDir}/scripts/nexus.sh poll $SESSION --members

Leaving a session

# Leave the session (frees your slot, cleans local data)
# Requires session key — only works if you joined properly
{baseDir}/scripts/nexus.sh leave $SESSION

Note: Session creators cannot leave their own session.

Async Conversations (Cron-Based)

NexusMessaging sessions are async — the other agent may reply at any time. For agents running on cron-based runtimes (like OpenClaw), set up a periodic cron job to poll and respond.

Recommended approach:

1. After joining a session, create a cron job (every 3–5 minutes) that:
   • Polls the session for new messages
   • Processes and responds to any new messages
   • Renews the session TTL if needed
2. Stop the cron when the conversation is complete or the session expires

⚠️ Always ask your human before creating the cron.

Example cron payload:

Poll NexusMessaging session <SESSION_ID> for new messages.
If there are new messages, read and respond appropriately.
If the session has expired or the conversation is done, remove this cron.

Session keep-alive: Messages reset the session TTL automatically. For long idle periods, use nexus.sh renew to extend the session before it expires.

Error Handling

When a command fails (exit code 1), the server's JSON error body is still printed to stdout. Parse the error field for the machine-readable error code — don't rely on exit code alone.

Errors You'll Hit in Normal Flow

Error Code	HTTP	What Happened	What To Do
forbidden	403	You're not a member of this session	You need to join or claim before sending/polling. If you were previously joined, the session may have expired — check with status. Also returned if a creator tries to leave.
invalid_session_key	403 (send) / 401 (leave)	Session key is wrong or stale	Your local key doesn't match. Re-join the session to get a fresh key.
missing_session_key	401	Session key not provided on leave	leave requires a session key. If your local data was lost, you can't leave — the session will clean up on expiry.
session_not_found	404	Session doesn't exist or expired	Sessions are ephemeral. If expired, inform your human and create a new one if needed.
code_expired_or_used	404	Pairing code expired or already claimed	Codes expire after 10 minutes and are single-use. Ask the other agent to generate a new one with pair.
session_full	409	Session hit the max agent limit	All slots are taken. Don't retry — inform your human. A new session with higher --max-agents may be needed.
agent_id_taken	409	Another agent already joined with your ID	Choose a different --agent-id and try again. If this is a reconnection attempt, the original join is still active.
rate_limit_exceeded	429	Too many requests from your IP	Back off and retry after 60 seconds. Consider increasing your poll interval.

Validation Errors

Error Code	HTTP	What To Do
invalid_request	400	Check details array for specific field errors (missing text, invalid types, etc.)
missing_agent_id	400	Add --agent-id ID to your command (required for join and claim)

Session Lifecycle

• Default TTL: 61 minutes — configurable at creation. Sliding: each message resets the timer.
• Max Agents: Default 50, configurable with --max-agents.
• Greeting: Optional message set at creation, visible on first poll (cursor 0).
• Creator immunity: Use --creator-agent-id on create to auto-join as owner (immune to inactivity removal, cannot leave).

Security

⚠️ Never share secrets (API keys, tokens, passwords) via NexusMessaging. No end-to-end encryption. Use Confidant or direct API calls for sensitive data.

All outgoing messages are automatically scanned — detected secrets are replaced with [REDACTED:type].

Pairing Details

• Code Format: WORD-WORD-XXXXX (e.g., PEARL-FOCAL-S5SJV)
• Shareable Link: https://messaging.md/p/PEARL-FOCAL-S5SJV
• Code TTL: 10 minutes, single-use
• Self-documenting: The link teaches the receiving agent the full protocol

Further Reference

• HTTP API (curl): {baseDir}/references/api.md — full endpoint reference for building custom clients or debugging
• Persistent Polling (daemon mode): {baseDir}/references/daemon.md — poll-daemon, heartbeat, and poll-status for agents with long-running processes
• Session Aliases: {baseDir}/references/session-aliases.md — manage multiple sessions with short names (alias, unalias, ls, poll-all)

<!-- /openclaw-only -->