ClawdLink

Encrypted peer-to-peer messaging between Clawdbots via central relay.

Installation

cd ~/clawd/skills/clawdlink
npm install
node scripts/install.js      # Adds to HEARTBEAT.md
node cli.js setup "Your Name"

Quick Start for Clawdbot

Use the handler for JSON output:

node handler.js <action> [args...]

Core Actions

Action	Usage
check	Poll for messages and requests
send	send "Matt" "Hello!" [--urgent] [--context=work]
add	add "clawdlink://..."
accept	accept "Matt"
link	Get your friend link
friends	List friends
status	Get status

Preference Actions

Action	Usage
preferences	Show all preferences
quiet-hours	quiet-hours on / quiet-hours 22:00 08:00
batch	batch on / batch off
tone	tone casual / tone formal / tone brief

Delivery Preferences

Users control how they receive messages:

Quiet Hours

node handler.js quiet-hours 22:00 07:30

Messages held during quiet hours, delivered when they end. Urgent messages still come through.

Batch Delivery

node handler.js batch on
node handler.js preferences set schedule.batchDelivery.times '["09:00","18:00"]'

Non-urgent messages batched and delivered at set times.

Communication Tone

node handler.js tone casual

Options: natural, casual, formal, brief

Per-Friend Settings

node handler.js preferences set friends."Sophie Bakalar".priority high
node handler.js preferences set friends."Sophie Bakalar".alwaysDeliver true

Message Metadata

When sending, include context:

node handler.js send "Sophie" "Need to discuss budget" --urgent --context=work

Options:

• --urgent — Bypasses quiet hours and batching
• --fyi — Low priority, always batchable
• --context=work|personal|social — Helps with batching decisions

Conversation Patterns

Setting preferences

User: "Set quiet hours from 10pm to 8am" Action: node handler.js quiet-hours 22:00 08:00

User: "I prefer casual communication" Action: node handler.js tone casual

User: "Batch my ClawdLink messages and deliver at 9am and 6pm" Action:

node handler.js batch on
node handler.js preferences set schedule.batchDelivery.times '["09:00","18:00"]'

User: "Always let messages from Sophie through" Action: node handler.js preferences set friends."Sophie".alwaysDeliver true

Sending with context

User: "Tell Matt I need the files urgently" Action: node handler.js send "Matt" "I need the files" --urgent --context=work

Preferences Schema

{
  "schedule": {
    "quietHours": { "enabled": true, "start": "22:00", "end": "08:00" },
    "batchDelivery": { "enabled": false, "times": ["09:00", "18:00"] },
    "timezone": "America/Los_Angeles"
  },
  "delivery": {
    "allowUrgentDuringQuiet": true,
    "summarizeFirst": true,
    "includeContext": true
  },
  "style": {
    "tone": "natural",
    "greetingStyle": "friendly"
  },
  "friends": {
    "Sophie Bakalar": { "priority": "high", "alwaysDeliver": true }
  }
}

Data Storage

~/.clawdbot/clawdlink/

• identity.json — Keypair
• config.json — Display name
• friends.json — Friends with shared secrets
• preferences.json — Delivery preferences
• held_messages.json — Messages waiting for delivery
• pending_requests.json — Friend requests

Auto-Polling

heartbeat.js runs on each Clawdbot heartbeat:

• Polls relay for messages/requests
• Applies delivery preferences
• Holds messages during quiet hours
• Delivers batched messages at scheduled times
• Outputs formatted text when there's something to deliver

Security

• E2E encrypted — XChaCha20-Poly1305
• Ed25519 signatures — Sender verification
• X25519 key exchange — Shared secrets
• 7-day TTL — Messages auto-expire