Clawchat

Quick Start Examples

Multi-Agent Setup

See scripts/example-multi-agent-setup.sh for a template to set up multiple coordinating agents.

Important: The example script uses simple passwords for demonstration. In production:

• Use strong, unique passwords
• Store credentials securely (environment variables, secret managers)
• Never commit passwords to version control

To adapt the example:

1. Copy and modify the script for your agent names
2. Replace example passwords with secure ones
3. Adjust ports as needed (default: 9100-9105)

Installation

# If not already installed globally
cd ~/clawchat  # Or wherever you cloned the repository
npm install
npm run build
sudo npm link

Quick Setup for Family Agents

1. Create Identity (One-time per agent)

# For Cora (main coordinator)
clawchat --data-dir ~/.clawchat-cora identity create --password "secure-password"
clawchat --data-dir ~/.clawchat-cora identity set-nick "Cora" --password "secure-password"

# Save the seed phrase securely!

Network Selection: By default, clawchat uses mainnet addresses (SP...) for stability and persistence. For development/testing, add --testnet to use testnet addresses (ST...).

2. Start Daemon

# Start Cora's daemon on port 9000
clawchat --data-dir ~/.clawchat-cora daemon start --password "secure-password" --port 9000

# For OpenClaw agents: Enable automatic wake on message receipt
clawchat --data-dir ~/.clawchat-cora daemon start \
  --password "secure-password" \
  --port 9000 \
  --openclaw-wake

OpenClaw Wake Feature: With --openclaw-wake, the daemon automatically triggers openclaw system event when messages arrive, eliminating the need for polling. Priority is determined by message prefix:

• URGENT:, ALERT:, CRITICAL: → Immediate wake (--mode now)
• All other messages → Next heartbeat (--mode next-heartbeat)

3. Connect Family Agents

# Add Peter's agent (example)
clawchat --data-dir ~/.clawchat-cora peers add stacks:ST2ABC... 127.0.0.1:9001

# List connected peers
clawchat --data-dir ~/.clawchat-cora peers list

Usage Examples

Send Message to Another Agent

# Send dinner poll update to Peter's agent
clawchat --data-dir ~/.clawchat-cora send stacks:ST2ABC... "Dinner poll update: 2 votes for Panera"

Receive Messages

# Check for new messages (wait up to 30 seconds)
clawchat --data-dir ~/.clawchat-cora recv --timeout 30

Broadcast to All Connected Agents

# Get list of peers
peers=$(clawchat --data-dir ~/.clawchat-cora peers list | jq -r '.peers[].principal')

# Send to each
for peer in $peers; do
  clawchat --data-dir ~/.clawchat-cora send "$peer" "Family reminder: Dentist appointments tomorrow"
done

Family Agent Coordination Patterns

1. Coordinated Polling Example

# Coordinator initiates poll and creates shared state
echo '{"poll_time": "'$(date -u +%Y-%m-%dT%H:%M:%SZ)'", "responses": {}}' > shared/poll-state.json

# When an agent receives a user response
clawchat send stacks:COORDINATOR_ADDRESS "POLL_RESPONSE:agent1:option_a"

# Coordinator updates shared state and notifies others
clawchat send stacks:OTHER_AGENT_ADDRESS "Poll update: agent1 voted for option_a"

See examples/example-coordinated-poll.sh for a complete implementation.

2. Task Delegation with Confirmation

# Coordinator delegates task to worker agent
clawchat send stacks:WORKER_AGENT "TASK:process:data_set_1:priority_high"

# Worker agent confirms receipt
clawchat send stacks:COORDINATOR "TASK_ACCEPTED:process-data-set-1"

# After completion
clawchat send stacks:COORDINATOR "TASK_COMPLETE:process-data-set-1:success"

3. Broadcast Notifications

# Send urgent message to all connected agents
for agent_principal in $(clawchat peers list | jq -r '.[].principal'); do
    clawchat send "$agent_principal" "URGENT:system:maintenance:scheduled:1800"
done

4. State Synchronization

# When shared state changes
clawchat send stacks:ALL_AGENTS "STATE_UPDATE:config:version:2.1"

# Agents acknowledge sync
clawchat send stacks:COORDINATOR "ACK:state-update-config-v2.1"

Daemon Management

Start on Boot (macOS)

# Copy the plist (adjust paths as needed)
cp /Users/cora/clawchat/com.clawchat.daemon.plist ~/Library/LaunchAgents/
launchctl load ~/Library/LaunchAgents/com.clawchat.daemon.plist

Check Daemon Status

clawchat --data-dir ~/.clawchat-cora daemon status

Identity Storage

• Identity stored at: ~/.clawchat-{agent}/identity.enc
• Node info at: ~/.clawchat-{agent}/node-info.json
• Peers database: ~/.clawchat-{agent}/peers.db

Security Notes

• Each agent gets a unique Stacks address (e.g., stacks:ST1ABC...)
• All messages are end-to-end encrypted with Noise protocol
• Passwords encrypt local identity storage
• Seed phrases are the only way to recover identities

Integration with OpenClaw

Instead of problematic sessions_send, use ClawChat:

# Old way (broken - sends to human)
# sessions_send(sessionKey, message)

# New way (agent-to-agent)
clawchat send stacks:ST2ABC... "Dinner poll: Please collect responses"

Message Format Standards

For reliable agent coordination, use structured message formats:

Standard Message Types

DINNER_VOTE:<name>:<choice>
TASK:<action>:<target>:<details>:<time>
STATUS_REQUEST
STATUS_REPLY:<agent>:<status>
ACK:<message-id>
ERROR:<message-id>:<reason>
CALENDAR_UPDATE:<event>:<date>:<time>:<person>
REMINDER_SET:<id>:<time>:<message>
REMINDER_COMPLETE:<id>

Example Parser

// In agent logic
const [type, ...params] = message.split(':');
switch(type) {
    case 'DINNER_VOTE':
        updateDinnerPoll(params[0], params[1]);
        break;
    case 'TASK':
        handleTask(params);
        break;
}

Reliability Patterns

Message Acknowledgment

# Send with ID
MSG_ID=$(date +%s)
clawchat send stacks:TARGET "TASK:$MSG_ID:remind:homework:1900"

# Wait for ACK
response=$(clawchat recv --timeout 30 | jq -r '.content')
if [[ $response == "ACK:$MSG_ID" ]]; then
    echo "Task acknowledged"
fi

Retry Logic

# Retry until acknowledged
for i in {1..3}; do
    clawchat send stacks:TARGET "$MESSAGE"
    if clawchat recv --timeout 10 | grep -q "ACK"; then
        break
    fi
    sleep 5
done

OpenClaw Integration Recipes

For detailed integration patterns and best practices, see RECIPES.md. Includes:

• Heartbeat integration (low traffic)
• Dedicated cron jobs (active coordination)
• Real-time watchers (mission critical)
• Hybrid approaches
• Complete examples

Debugging

# Check daemon status
clawchat --data-dir ~/.clawchat-cora daemon status

# List peers and connection status  
clawchat --data-dir ~/.clawchat-cora peers list

# Force stop daemon
pkill -f "clawchat.*daemon"