clankerhive

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.

# 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:

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.

# 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:

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.

# 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:

python3 scripts/clankerhive.py queue-alert calendar "Standup with the platform team in 30 minutes"

Main session heartbeat checks for alerts:

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.

# 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

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:

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:

# 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