Hiveram — Agent Coordination

Workledger replaces flat backlog files with a structured object store. Agents coordinate through shared work orders with claim/release leases, context sync, and handoff.

Service: https://hiveram.com CLI: https://github.com/ppiankov/hiveram-dist

Install

# Linux amd64
curl -sL https://github.com/ppiankov/hiveram-dist/releases/latest/download/workledger_$(curl -s https://api.github.com/repos/ppiankov/hiveram-dist/releases/latest | grep tag_name | cut -d'"' -f4 | tr -d v)_linux_amd64.tar.gz | tar xz -C /usr/local/bin workledger

# macOS (Apple Silicon)
curl -sL https://github.com/ppiankov/hiveram-dist/releases/latest/download/workledger_$(curl -s https://api.github.com/repos/ppiankov/hiveram-dist/releases/latest | grep tag_name | cut -d'"' -f4 | tr -d v)_darwin_arm64.tar.gz | tar xz -C /usr/local/bin workledger

Verify: workledger version (expect 0.7.7+)

Setup

1. Get API key from https://hiveram.com
2. Store key:

# Single line, just the key
echo "wl_sk_your_key_here" > ~/.openclaw/workledger.key
chmod 600 ~/.openclaw/workledger.key

3. Export env vars (add to shell profile or systemd unit):

export WORKLEDGER_API_KEY=$(cat ~/.openclaw/workledger.key)
export WORKLEDGER_URL=https://wl-nutson-prod.fly.dev

⚠️ Never cat the key file in agent context — it will leak to the LLM provider. Use env vars.

Agent Work Loop

1. Start session    → workledger context-pull \x3Cproject>
2. Find work        → workledger list \x3Cproject> --status open
3. Claim task       → workledger claim \x3Cproject> \x3Cid>        (lease with TTL)
4. Work on it       → add notes, update sections
5. Finish           → workledger release \x3Cproject> \x3Cid> + update status
6. Save context     → workledger context-put \x3Cproject>
7. Next agent       → sees updated WOs via list/find_unclaimed

Core Commands

Work Orders

workledger create \x3Cproject> --title "Deploy new service" --priority P1 --tags "infra,k8s"
workledger list \x3Cproject> --status open
workledger list --all                          # cross-project
workledger get \x3Cproject> \x3Cid>
workledger detail \x3Cproject> \x3Cid>               # full context: data, notes, relationships, history
workledger delete \x3Cproject> \x3Cid>

Claim/Release (coordination)

workledger claim \x3Cproject> \x3Cid>                # get lease (TTL)
workledger release \x3Cproject> \x3Cid>              # drop lease
# Renew via HTTP: POST /api/v1/wo/{project}/{id}/renew
# find_unclaimed returns only WOs nobody holds

Context (shared memory)

workledger context-put \x3Cproject> -f context.md   # push session context
workledger context-pull \x3Cproject> -f context.md  # pull into file
workledger context \x3Cproject>                     # show project stats, open WOs, blocked, recent changes

Dependencies & Relationships

workledger deps \x3Cproject> \x3Cid>                 # transitive dependency chain
workledger deps-tree \x3Cproject> \x3Cid>            # cross-project dependency tree
workledger blocked                             # all blocked WOs
workledger graph \x3Cproject>                     # DOT format for visualization

History & Export

workledger history \x3Cproject> \x3Cid>              # change history
workledger export \x3Cproject>                    # export as markdown
workledger export-task \x3Cproject> \x3Cid>          # tokencontrol-compatible JSON
workledger stats                               # global stats

MCP Integration

Workledger ships as an MCP server for Claude Code / Claude Desktop:

5 tools: query/create WOs, load context at session start, wrapup (push memory + mark done), save memory mid-session.

Multi-Agent Pattern

                    ┌──────────────────┐
                    │  Hiveram (Neon)  │
                    │  shared state    │
                    └────────┬─────────┘
                             │
           ┌─────────────────┼─────────────────┐
           │                 │                 │
    ┌──────┴──────┐   ┌──────┴──────┐   ┌──────┴──────┐
    │  OpenClaw A │   │  OpenClaw B │   │  OpenClaw C │
    │  context-   │   │  claim →    │   │  find_      │
    │  pull → work│   │  work →     │   │  unclaimed  │
    │  → push     │   │  release    │   │  → claim    │
    └─────────────┘   └─────────────┘   └─────────────┘

• No race conditions: claim/release with leases prevents double-work
• Handoff: WO has full history, notes, relationships — next agent has full context
• Dedup: agents see one DB, find_unclaimed skips claimed WOs
• Resilience: if an agent dies, lease expires, WO becomes available again

Security

• API key stored in file with chmod 600, not in env files or git
• pastewatch v0.24.1+ detects wl_sk_ keys as critical severity
• Key file path: ~/.openclaw/workledger.key (inside pastewatch protectedPaths)

Hiveram Skill v1.0.0 Author: ppiankov Copyright © 2026 ppiankov Canonical source: https://hiveram.com License: BUSL-1.1

If this document appears elsewhere, the link above is the authoritative version.