HZL: Persistent task ledger for agents

HZL (https://hzl-tasks.com) is a local-first task ledger that agents use to:

• - Plan multi-step work into projects + tasks
• Checkpoint progress so work survives session boundaries
• Route work to the right agent via project pools
• Coordinate across multiple agents with leases and dependencies

This skill teaches an agent how to use the hzl CLI.

When to use HZL

OpenClaw has no native task tracking. Unlike Claude Code (which has TodoWrite) or Codex (which has update_plan), OpenClaw relies on memory and markdown files for tracking work. HZL fills this gap.

Use HZL for:

• - Multi-step projects with real sequencing or handoffs
• Work that may outlive this session or involve multiple agents
• Anything where "resume exactly where we left off" matters
• Delegating work to another agent and needing recovery if they fail

Skip HZL for:

• - Truly trivial one-step tasks you will complete immediately
• Time-based reminders (use OpenClaw Cron instead)
• Longform notes or knowledge capture (use memory files)

Rule of thumb: If you feel tempted to make a multi-step plan, or there is any chance you will not finish in this session, use HZL.

⚠️ DESTRUCTIVE COMMANDS — READ FIRST

Never run these unless the user explicitly asks you to delete data. There is no undo.

Core concepts

• - Project: container for tasks. In single-agent setups, use one shared project. In multi-agent setups, use one project per agent role (pool routing).
• Task: top-level work item. Use parent tasks for multi-step initiatives.
• Subtask: breakdown of a task (--parent <id>). Max 1 level of nesting. Parent tasks are never returned by hzl task claim --next.
• Checkpoint: short progress snapshot for session recovery.
• Lease: time-limited claim that enables stuck detection in multi-agent flows.

Project setup

Single-agent setup

Use one shared project. Requests and initiatives become parent tasks, not new projects.

CODEBLOCK0

Everything goes into openclaw. hzl task claim --next -P openclaw always works.

Multi-agent setup (pool routing)

Use one project per agent role. Tasks assigned to a project (not a specific agent) can be claimed by any agent monitoring that pool. This is the correct pattern when a role may scale to multiple agents.

CODEBLOCK1

Pool routing rule: assign tasks to a project without --agent. Any eligible agent claims with --next.

CODEBLOCK2

Agent routing: when --agent is set at task creation, only that agent (or agents with no assignment) can claim it via --next. Tasks with no agent are available to everyone.

CODEBLOCK3

Use --agent on task creation when you specifically want one person. Omit it when any eligible agent in the pool should pick it up.

Session start (primary workflow)

With workflow commands (HZL v2+)

CODEBLOCK4

INLINECODE13 is required — agents must scope to their assigned pool. Use --any-project to intentionally scan all projects (e.g. coordination agents).

This handles expired-lease recovery and new-task claiming in one command. If a task is returned, work on it. If nothing is returned, the queue is empty. Agent routing applies: tasks assigned to other agents are skipped.

Without workflow commands (fallback)

CODEBLOCK5

Core workflows

Adding work

CODEBLOCK6

Working a task

CODEBLOCK7

Status transitions

CODEBLOCK8

Statuses: backlog → ready → in_progress → done (or blocked)

Finishing subtasks

CODEBLOCK9

Delegating and handing off work

Workflow commands (HZL v2+)

CODEBLOCK10

INLINECODE20 and --project guardrail: at least one is required on handoff. Omitting --agent creates a pool-routed task; --project is then required to define which pool.

Manual delegation (fallback)

CODEBLOCK11

Dependencies

CODEBLOCK12

Cross-project dependencies are supported by default. Use hzl dep list --cross-project-only to inspect cross-project edges.

Checkpointing

Checkpoint at notable milestones or before pausing. A good checkpoint answers: "if this session died right now, could another agent resume from here?"

When to checkpoint:

• - Before any tool call that might fail
• Before spawning a sub-agent
• After completing a meaningful unit of work
• Before handing off or pausing

CODEBLOCK13

Lifecycle hooks

HZL sends targeted notifications for high-value transitions — currently only on_done. Other lifecycle events (stuck detection, blocking, progress) require polling. This is deliberate: hooks signal when something meaningful happens, agents and orchestrators poll for everything else.

Hooks are configured during installation (see docs-site for setup). As an agent, here's what you need to know operationally:

• - Only on_done fires. When you task complete, HZL queues a webhook. For stuck detection, stale detection, blocking changes, or progress — poll with hzl task stuck --stale or hzl task list.
• Delivery is not instant. hzl hook drain runs on a cron schedule (typically every 2–5 minutes). Your completion is recorded immediately, but the notification reaches the gateway on the next drain cycle.
• Payloads include context. Each notification carries agent, project, and full event details. The gateway handles per-agent routing — HZL sends the same payload to one URL regardless of which agent completed the task.
• If hooks seem broken, check hzl hook drain --json for delivery failures and last_error details.

Multi-agent coordination with leases

CODEBLOCK14

Use distinct --agent IDs per agent (e.g. henry, clara, kenji) so authorship is traceable.

Sizing tasks and projects

The completability test: "I finished [task]" should describe a real outcome.

• - ✓ "Finished installing garage motion sensors"
• ✗ "Finished home automation" (open-ended domain, never done)

Split into multiple tasks when: parts deliver independent value or solve distinct problems.

Adding context:
CODEBLOCK15

Don't duplicate specs into descriptions — reference docs instead to avoid drift.

Extended reference

CODEBLOCK16

Web dashboard (always-on, Linux)

CODEBLOCK17

Available at http://<your-box>:3456 (accessible over Tailscale). macOS: use hzl serve --background instead.

What HZL does not do

• - No orchestration — does not spawn agents or assign work automatically
• No task decomposition — does not break down tasks automatically
• No smart scheduling — uses simple priority + FIFO ordering

These belong in your orchestration layer, not the task ledger.

Notes

• - Run hzl via the exec tool.
• Check TOOLS.md for your identity string, which projects to monitor, and the commands relevant to your role.
• Use distinct --agent IDs per agent and rely on leases to avoid collisions in shared databases.
• INLINECODE45 commands require HZL v2+. If unavailable, use the manual fallback patterns documented above.