ClankerHive

Shared SQLite-backed context store for multi-session agent coordination. Use when: (1) checking if work was already done recently (email checked, briefing se...

Security Scan

ClankerHive is internally consistent: it implements a local SQLite-backed coordination store and requests only Python and a writable DB path, which matches its description and instructions.

Purpose & Capability

Name/description (shared SQLite-backed context store for cross-session coordination) align with the included script and SKILL.md. The script implements facts, alerts, and task claiming using a local SQLite DB; requiring python3 is appropriate and expected.

Instruction Scope

SKILL.md instructions and the script are narrowly scoped to creating/using a local SQLite DB and printing JSON/plain-text results. The only environment interaction is reading CLANKERHIVE_DB and expanding the user home directory; the skill does not read arbitrary files, contact networks, or access unrelated credentials.

Install Mechanism

There is no remote install/download; the package is instruction-only and ships a Python script. No external archives, package installs, or third-party downloads are performed.

Credentials

No credentials or sensitive env vars are required. The only optional env var is CLANKERHIVE_DB to override the DB path, which is reasonable for this purpose. The script will create the DB file and parent dirs as documented.

Persistence & Privilege

The skill does not request always:true and does not modify other skills or system-wide settings. Its persistence is limited to writing a local SQLite DB file (default under ~/.openclaw) and setting file permissions when creating it.

Assessment

This skill appears to do what it says: a local coordination DB managed by a small Python script. Before installing, verify you are comfortable with a writable SQLite file being created where you run the agent. Keep CLANKERHIVE_DB pointed to a user-only location (default ~/.openclaw/hive.db) so others cannot read the DB; if you change the path, set permissions (chmod 600). Review the included script if you want to confirm there are no network calls or additional behaviors in the truncated portion. Ensure python3 is trusted on the host and that multi-user systems don't place the DB in a world-readable directory.

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