Multi-agent teams: parallel processing, agent-to-agent communication, and request tracking

AGENTS.md

@@ -69,9 +69,18 @@ Please reply with: (1) status (2) blockers (3) next step.
 
 Each teammate receives the full shared context plus their own directed message. Keep shared context concise — it's prepended to every teammate's message.
 
-### Back-and-forth
+### Responding to teammates
 
-You can communicate back and forth by mentioning your teammate in your response and the system will route the messages in real-time.
+When you receive a message from a teammate like:
+> [Message from teammate @sam — respond using [@sam: your reply]]:
+
+You MUST wrap your response in `[@sam: your response here]` so it routes back to them. If you don't, your response goes directly to the user and the requesting agent never sees it.
+
+Example:
+- Teammate asks: `[Message from teammate @sam]: What is 2+2?`
+- Your response: `[@sam: 2 + 2 = 4]`
+
+Only skip the `[@agent: ...]` wrapper if you're intentionally responding to the user instead of the teammate.
 
 ### Guidelines
 

README.md

@@ -35,6 +35,7 @@
 - ✅ **SQLite queue** - Atomic transactions, retry logic, dead-letter management
 - ✅ **Plugin system** - Extend TinyClaw with custom plugins for message hooks and event listeners
 - ✅ **24/7 operation** - Runs in tmux for always-on availability
+- ✅ **Reliable agent handoffs** - Request-reply protocol with ACKs, timeouts, and escalation (see [Agent Communication Protocol](docs/AGENT_COMMUNICATION_PROTOCOL.md))
 
 ## Community
 

backup.sh

@@ -0,0 +1,43 @@
+#!/bin/bash
+# Backup TinyClaw SQLite database daily
+# Usage: ./backup.sh or add to crontab: 0 2 * * * /path/to/backup.sh
+
+set -e
+
+TINYCLAW_HOME="${TINYCLAW_HOME:-$HOME/.tinyclaw}"
+DB_FILE="$TINYCLAW_HOME/tinyclaw.db"
+BACKUP_DIR="$TINYCLAW_HOME/backups"
+RETENTION_DAYS=7
+
+# Create backup directory if needed
+mkdir -p "$BACKUP_DIR"
+
+# Check if database exists
+if [ ! -f "$DB_FILE" ]; then
+    echo "WARNING: Database file not found: $DB_FILE"
+    exit 1
+fi
+
+# Create timestamped backup
+TIMESTAMP=$(date +%Y%m%d_%H%M%S)
+BACKUP_FILE="$BACKUP_DIR/tinyclaw_${TIMESTAMP}.db"
+
+# Atomic hot-backup using SQLite's built-in backup API
+# Safe while database is actively being written to (WAL mode)
+sqlite3 "$DB_FILE" ".backup '$BACKUP_FILE'"
+
+# Verify backup is valid (can open it)
+if ! sqlite3 "$BACKUP_FILE" ".tables" >/dev/null 2>&1; then
+    echo "ERROR: Backup verification failed for $BACKUP_FILE"
+    rm -f "$BACKUP_FILE"*
+    exit 1
+fi
+
+echo "✓ Backup created: $BACKUP_FILE"
+
+# Delete old backups (keep 7 days)
+find "$BACKUP_DIR" -name "tinyclaw_*.db" -mtime +$RETENTION_DAYS -delete 2>/dev/null || true
+
+# Log backup count
+BACKUP_COUNT=$(ls -1 "$BACKUP_DIR"/tinyclaw_*.db 2>/dev/null | wc -l)
+echo "Backup count: $BACKUP_COUNT (retention: ${RETENTION_DAYS} days)"