nanoclaw-whatsapp

name	nanoclaw-whatsapp
description	Send WhatsApp messages through NanoClaw's IPC. Use when an agent needs to notify the human via WhatsApp about completed work, failures, decisions needed, or status updates.

How It Works

NanoClaw watches a filesystem directory for JSON message files. Write a .json file to NanoClaw's IPC messages directory, and NanoClaw picks it up within 1 second and sends it via WhatsApp.

IPC Directory

Write to the notifications/ directory in the Factory workspace. This is a symlink to NanoClaw's IPC:

notifications/

Message Format

Write a JSON file with a unique name (timestamp + random suffix recommended):

{
  "type": "message",
  "chatJid": "[e-mail]",
  "text": "Your message content here"
}

• type must be "message"
• chatJid is the WhatsApp chat to send to (the self-chat JID above is the human's main channel)
• text is the message body (plain text, WhatsApp formatting supported: bold, italic, strikethrough, code)

File Naming

Use this pattern to avoid collisions:

{timestamp}-{agent}-{brief}.json

Example: 1740470400000-verifier-spec-passed.json

When to Notify

Use judgement. Not every action needs a WhatsApp message. Good reasons to notify:

• Verification complete — spec passed or failed (Verifier)
• Decision needed — ambiguity blocking progress (Spec, Builder)
• Build complete — significant deliverable ready for review (Builder)
• Health alert — deployed project unhealthy twice in a row (Operator)
• Research brief ready — findings that change project direction (Researcher)

Do NOT notify for routine heartbeat activity, daily log entries, or minor internal state changes.

Message Style

Keep messages brief and actionable. The human reads these on a phone.

Good:

Spec "multi-cli-backend-support" verified. 4/4 scenarios pass. Ready for deployment.

Bad:

Hello! I wanted to let you know that I have completed the verification process for the specification titled "multi-cli-backend-support". The verification involved running 4 scenarios, all of which passed successfully. The work is now ready for the next stage of the pipeline.

Example

cat > notifications/$(date +%s%3N)-operator-health.json << 'EOF'
{
  "type": "message",
  "chatJid": "[e-mail]",
  "text": "Health alert: git-commit-viewer API returning 503 for 2 consecutive checks. Maintenance task created."
}
EOF

Access Control

Only agents with write access to the NanoClaw IPC path can send messages. The NanoClaw IPC watcher validates that messages originate from the main group directory (which has unrestricted send permissions).