Skill: pfrederiksen/clankerhive (version 1.0.3)

--- name: clankerhive description: "Shared SQLite-backed context store for multi-session agent coordination. Use when: (1) checking if work was already done recently (email checked, briefing sent), (2) preventing duplicate cron/heartbeat runs via task claiming, (3) passing alerts between sessions (cron queues alert → main session pops it), (4) storing short-lived facts with TTL, or (5) any cross-session state sharing. Replaces ad-hoc JSON state files with a proper coordination bus. Triggers on: deduplication, cross-session state, shared facts, alert queue, task coordination, heartbeat state." homepage: https://github.com/pfrederiksen/clankerhive metadata: { "openclaw": { "emoji": "🐝", "requires": { "bins": ["python3"] }, "install": [], }, } --- # 🐝 ClankerHive Shared context store for OpenClaw multi-session coordination. Three primitives: 1. **Facts** — key/value pairs with optional TTL (auto-expire) 2. **Alerts** — cross-session notification queue (producer/consumer) 3. **Tasks** — claim-based deduplication for in-flight work All backed by a single SQLite database in WAL mode (safe for concurrent access). ## Setup No dependencies beyond Python 3 stdlib. The DB is created automatically on first use. ```bash # Default DB location: ~/.openclaw/hive.db # Override with environment variable: export CLANKERHIVE_DB=/path/to/custom/hive.db ``` Resolve the script path relative to this skill directory: ```bash HIVE="python3 $(dirname "$0")/../scripts/clankerhive.py" # Or use absolute path from skill install location ``` ## Facts — Key/Value with TTL Store short-lived coordination state. Expired facts are auto-pruned on every read. ```bash # Set a fact (lives forever unless --ttl is given) python3 scripts/clankerhive.py set email.last_check "$(date +%s)" --ttl 900 # Read it back (empty output if missing/expired) python3 scripts/clankerhive.py get email.last_check # List all facts matching a prefix python3 scripts/clankerhive.py list --prefix email # Delete a fact python3 scripts/clankerhive.py delete email.last_check # Tag who set it (useful for debugging) python3 scripts/clankerhive.py set weather.checked "1" --ttl 3600 --source heartbeat ``` ### Pattern: Skip-if-recent Before doing expensive work, check if it was done recently: ```bash LAST=$(python3 scripts/clankerhive.py get email.last_check) if [ -z "$LAST" ]; then # Do the work, then record it python3 scripts/clankerhive.py set email.last_check "$(date +%s)" --ttl 900 fi ``` ## Alerts — Cross-Session Queue Cron jobs or sub-agents produce alerts; the main session consumes them. ```bash # Queue an alert (from cron job) python3 scripts/clankerhive.py queue-alert email "urgent: server down — production alert from monitoring" # List unclaimed alerts python3 scripts/clankerhive.py list-alerts # Claim and return all pending alerts (marks them claimed) python3 scripts/clankerhive.py pop-alerts # Claim only alerts for a specific topic python3 scripts/clankerhive.py pop-alerts --topic email # Clean up old claimed alerts (default: older than 24h) python3 scripts/clankerhive.py purge-alerts --age 86400 ``` ### Pattern: Cron → Main Session Handoff Cron job detects something important: ```bash python3 scripts/clankerhive.py queue-alert calendar "Standup with the platform team in 30 minutes" ``` Main session heartbeat checks for alerts: ```bash ALERTS=$(python3 scripts/clankerhive.py pop-alerts) # Process and notify user if non-empty ``` ## Tasks — Deduplication Prevent multiple sessions from doing the same work simultaneously. ```bash # Try to claim a task (exit 0 = got it, exit 1 = someone else has it) python3 scripts/clankerhive.py claim-task daily-briefing-2026-04-01 # stdout: "ok" or "already-claimed by <owner>" # Release when done python3 scripts/clankerhive.py release-task daily-briefing-2026-04-01 --result "sent to telegram" # Check status python3 scripts/clankerhive.py task-status daily-briefing-2026-04-01 ``` ### Pattern: Idempotent Cron ```bash if python3 scripts/clankerhive.py claim-task "morning-briefing-$(date +%Y-%m-%d)"; then # Do the work... python3 scripts/clankerhive.py release-task "morning-briefing-$(date +%Y-%m-%d)" --result "done" else echo "Already running or completed" fi ``` ## Stats Quick summary of the hive state: ```bash python3 scripts/clankerhive.py stats ``` Returns JSON with counts for facts, pending/claimed alerts, and claimed/done tasks. ## Replacing heartbeat-state.json Instead of maintaining a separate `memory/heartbeat-state.json` file, use ClankerHive facts: ```bash # Old way: read/write JSON file # New way: python3 scripts/clankerhive.py set heartbeat.email "$(date +%s)" --ttl 1800 python3 scripts/clankerhive.py set heartbeat.calendar "$(date +%s)" --ttl 3600 python3 scripts/clankerhive.py set heartbeat.weather "$(date +%s)" --ttl 7200 # Check when something was last done: python3 scripts/clankerhive.py get heartbeat.email # Empty = time to check again ``` ## Notes - DB path configurable via `CLANKERHIVE_DB` env var (default: `~/.openclaw/hive.db`) - WAL mode ensures safe concurrent reads/writes from multiple processes - All list/query commands output JSON; scalar commands output plain text - Exit code 0 = success, 1 = error (already-claimed, not-found, etc.) - No external dependencies — pure Python stdlib ## System Access **Reads:** Nothing — no files, env vars, or network beyond the SQLite DB. **Writes:** Only to the SQLite database file at `$CLANKERHIVE_DB` (default `~/.openclaw/hive.db`). Creates parent directories if they don't exist. The default path (`~/.openclaw/`) is typically mode `700` on OpenClaw installs, meaning only the owning user can read the DB. If you change `CLANKERHIVE_DB` to a shared or world-readable location, restrict permissions manually: `chmod 600 hive.db`. **Network:** None. No outbound connections of any kind. **Imports:** `argparse`, `json`, `os`, `sqlite3`, `sys`, `time`, `typing` — all Python stdlib. No third-party packages, no subprocess calls, no eval/exec. **Source:** <https://github.com/pfrederiksen/clankerhive>


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (MEDIUM)