HZL: Persistent task tracking for agents

HZL () is a local-first task ledger (database-backed, optionally cloud-synced for backup) that an agent can use to:

• plan multi-step work into projects + tasks
• checkpoint progress (so work survives session boundaries)
• coordinate sub-agents or multiple coding tools with leases
• generate reliable status reports ("what's done vs what's left")

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

When to use HZL

OpenClaw has NO native task tracking tools. Unlike Claude Code (which has TodoWrite) or Codex (which has update_plan), OpenClaw relies on memory and markdown files for tracking work. This makes HZL especially valuable for OpenClaw.

Use HZL by default for any non-trivial task tracking:

• Multi-step projects with real sequencing (dependencies) and handoffs
• Work that spans multiple sessions, days, or tools/agents
• Orchestration: delegating work to sub-agents and needing recovery if they crash
• Anything where "resume exactly where we left off" matters
• Any work you want to persist beyond this session
• Any work that needs structure (nesting, dependencies, progress tracking)

Why HZL is the right choice for OpenClaw:

Without HZL, OpenClaw tracks tasks in-context (burns space, fragments during compaction) or in markdown files (requires manual management, no nesting/dependencies, no dashboard). HZL provides:

• Persistent storage that survives session boundaries
• Nesting (parent tasks + subtasks) and dependencies
• Web dashboard for human visibility (hzl serve)
• Leases for multi-agent coordination
• Checkpoints for progress recovery

Only skip HZL for:

• Truly trivial, one-step tasks you will complete immediately in this session
• Time-based reminders/alerts (use OpenClaw Cron instead)
• Longform notes or knowledge capture (use a notes or memory system)

Personal tasks: HZL is not a polished human to-do app, but it is usable for personal task tracking, and it can also serve as a backend for a lightweight UI.

Core concepts

• Project: stable container. For OpenClaw, use a single openclaw project—this keeps hzl task next simple. Check hzl project list before creating.
• Task: top-level work item. For multi-step requests, this becomes a parent task.
• Subtask: breakdown of a task into parts (--parent ). Max 1 level of nesting. Parent tasks are organizational containers—never returned by hzl task next.
• Checkpoint: short progress snapshot to support recovery
• Lease: time-limited claim (prevents orphaned work in multi-agent flows)

Anti-pattern: Project Sprawl

Use a single openclaw project. Requests and initiatives become parent tasks, not new projects.

Wrong (creates sprawl):

hzl project create "garage-sensors"
hzl project create "query-perf"
# Now you have to track which project to query

Correct (single project, parent tasks):

# Check for existing project first
hzl project list

# Use single openclaw project
hzl task add "Install garage sensors" -P openclaw
# → Created task abc123

hzl task add "Wire sensor to hub" --parent abc123
hzl task add "Configure alerts" --parent abc123

# hzl task next --project openclaw always works

Why this matters:

• Projects accumulate forever; you'll have dozens of abandoned one-off projects


• hzl task next --project X requires knowing which project to query


• With a single project, hzl task next --project openclaw always works

Sizing Parent Tasks

HZL supports one level of nesting (parent → subtasks). Scope parent tasks to completable outcomes.

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

• ✓ "Finished installing garage motion sensors"


• ✓ "Finished fixing query performance"


• ✗ "Finished home automation" (open-ended domain, never done)


• ✗ "Finished backend work" (if frontend still pending for feature to ship)

Scope by problem, not technical layer. A full-stack feature (frontend + backend + tests) is usually one parent if it ships together.

Split into multiple parents when:

• Parts deliver independent value (can ship separately)


• You're solving distinct problems that happen to be related

Adding context: Use --links to attach specs or reference docs when the description isn't enough:

hzl task add "Install garage sensors" -P openclaw \
  --links docs/sensor-spec.md \
  --links ""

⚠️ DESTRUCTIVE COMMANDS - READ CAREFULLY

The following commands PERMANENTLY DELETE HZL DATA and cannot be undone:

Command

Effect

hzl init --force	DELETES ALL DATA. Prompts for confirmation.
hzl init --force --yes	DELETES ALL DATA WITHOUT CONFIRMATION. Extremely dangerous.
hzl task prune ... --yes	PERMANENTLY DELETES old done/archived tasks and their event history.

AI agents: NEVER run these commands unless the user EXPLICITLY asks you to delete data.

• hzl init --force deletes the entire event database: all projects, tasks, checkpoints, and history
• hzl task prune deletes only tasks in terminal states (done/archived) older than the specified age
• There is NO undo. There is NO recovery without a backup.

Quick reference

# Setup
hzl init                                      # Initialize (safe, won't overwrite)
hzl init --reset-config                       # Reset config to default location (non-destructive)
hzl project create <project>
hzl project list

# Create tasks
hzl task add "<title>" -P <project>
hzl task add "<title>" -P <project> --priority 2 --tags backend,auth
hzl task add "<title>" -P <project> --depends-on <other-id>

# Subtasks (organize related work)
hzl task add "<title>" --parent <parent-id>   # Create subtask
hzl task list --parent <parent-id>            # List subtasks
hzl task list --root                          # Top-level tasks only
hzl task next --parent <parent-id>            # Next subtask of parent

# Find work
hzl task list --project <project> --available
hzl task next --project <project>

# Create with initial status (skip the claim dance)
hzl task add "<title>" -P <project> -s ready               # Create ready to claim
hzl task add "<title>" -P <project> -s in_progress --assignee <name>  # Create and claim

# Work + persist progress
hzl task claim <id> --assignee <agent-id>
hzl task checkpoint <id> "<what changed / what's next>" [--progress 50]
hzl task progress <id> 50                     # Set progress without checkpoint
hzl task show <id> --json
hzl task complete <id>

# Blocked tasks (stuck on external issues)
hzl task block <id> --comment "Blocked: waiting for API key from DevOps"
hzl task unblock <id>                         # Returns to in_progress

# Dependencies + validation
hzl task add-dep <task-id> <depends-on-id>
hzl validate

# Diagnostics
hzl status   # database mode, paths, sync state
hzl doctor   # health check for debugging

# Web Dashboard (human visibility into task state)
hzl serve                    # Start on port 3456 (network accessible)
hzl serve --host 127.0.0.1   # Restrict to localhost only
hzl serve --background       # Fork to background
hzl serve --status           # Check if running
hzl serve --stop             # Stop background server

# Multi-agent recovery
hzl task claim <id> --assignee <agent-id> --lease 30
hzl task stuck
hzl task steal <id> --if-expired --author <agent-id>

Tip: When a tool needs to parse output, prefer --json.

Authorship tracking

HZL tracks authorship at two levels:

Concept

What it tracks

Set by

Assignee	Who owns the task	--assignee on claim or add
Event author	Who performed an action	--author on other commands

The --assignee flag on claim and add (with -s in_progress) sets task ownership. The --author flag on other commands (checkpoint, comment, block, etc.) records who performed each action:

# Alice owns the task
hzl task claim 1 --assignee alice

# Bob adds a checkpoint (doesn't change ownership)
hzl task checkpoint 1 "Reviewed the code" --author bob

# Task is still assigned to Alice, but checkpoint was recorded by Bob

For AI agents that need session tracking, use --agent-id on claim:

hzl task claim 1 --assignee "Claude Code" --agent-id "session-abc123"

Recommended patterns

Start a multi-step project

1) Create (or reuse) a stable project name.
2) Decompose into tasks.
3) Use dependencies to encode sequencing, not just priority.
4) Validate.

hzl project create myapp-auth

hzl task add "Clarify requirements + acceptance criteria" -P myapp-auth --priority 5
hzl task add "Design API + data model" -P myapp-auth --priority 4 --depends-on <reqs-id>
hzl task add "Implement endpoints" -P myapp-auth --priority 3 --depends-on <design-id>
hzl task add "Write tests" -P myapp-auth --priority 2 --depends-on <impl-id>
hzl task add "Docs + rollout plan" -P myapp-auth --priority 1 --depends-on <tests-id>

hzl validate

Work a task with checkpoints and progress

Checkpoint early and often. A checkpoint should be short and operational:

• what you verified


• what you changed


• what's next


• what's blocking you (if anything)

hzl task claim <id> --assignee orchestrator
# ...do work...
hzl task checkpoint <id> "Implemented login flow. Next: add token refresh." --progress 50
# ...more work...
hzl task checkpoint <id> "Added token refresh. Testing complete." --progress 100
hzl task complete <id>

You can also set progress without a checkpoint:

hzl task progress <id> 75

Handle blocked tasks

When stuck on external dependencies, mark the task as blocked:

hzl task claim <id> --assignee orchestrator
hzl task checkpoint <id> "Implemented login flow. Blocked: need API key for staging."
hzl task block <id> --comment "Blocked: waiting for staging API key from DevOps"

# Later, when unblocked:
hzl task unblock <id> --comment "Unblocked: received API key from DevOps"
hzl task checkpoint <id> "Got API key, resuming work"
hzl task complete <id>

Comment best practices: Include context about the action, not just the state:

• Good: "Blocked: waiting for API keys from infra team"


• Good: "Unblocked: keys received, resuming work"


• Bad: "waiting for API keys" (missing action context)

Blocked tasks stay visible in the dashboard (Blocked column) and keep their assignee, but don't appear in --available lists.

Coordinate sub-agents with leases

Use leases when delegating, so you can detect abandoned work and recover.

hzl task add "Implement REST endpoints" -P myapp-auth --priority 3 --json
hzl task claim <id> --assignee subagent-claude-code --lease 30

Delegate with explicit instructions:

• claim the task (with their author id)


• checkpoint progress as they go


• complete when done

Monitor:

hzl task show <id> --json
hzl task stuck
hzl task steal <id> --if-expired --author orchestrator

Break down work with subtasks

Use parent/subtask hierarchy to organize complex work:

# Create parent task
hzl task add "Implement vacation booking" -P portland-trip --priority 2
# → abc123

# Create subtasks (project inherited automatically)
hzl task add "Research flights" --parent abc123
hzl task add "Book hotel" --parent abc123 --depends-on <flights-id>
hzl task add "Plan activities" --parent abc123

# View breakdown
hzl task show abc123

# Work through subtasks
hzl task next --parent abc123

Important: hzl task next only returns leaf tasks (tasks without children). Parent tasks are organizational containers—they are never returned as "next available work."

When all subtasks are done, manually complete the parent:

hzl task complete abc123

Web Dashboard

HZL includes a built-in Kanban dashboard for monitoring task state. The dashboard shows tasks in columns (Backlog → Blocked → Ready → In Progress → Done), with filtering by date and project.

Setting up the dashboard (recommended for OpenClaw)

For always-on access on your OpenClaw box, set up as a systemd service (Linux only):

# Create the systemd user directory if needed
mkdir -p ~/.config/systemd/user

# Generate and install the service file
hzl serve --print-systemd > ~/.config/systemd/user/hzl-web.service

# Enable and start
systemctl --user daemon-reload
systemctl --user enable --now hzl-web

# IMPORTANT: Enable lingering so the service runs even when logged out
loginctl enable-linger $USER

# Verify it's running
systemctl --user status hzl-web

The dashboard will be available at (accessible over Tailscale). To use a different port: __CODE_BLOCK_15__ **macOS note:** systemd is Linux-only. On macOS, use hzl serve --background or create a launchd plist manually. ### Quick commands __CODE_BLOCK_16__ Use --background for temporary sessions. Use systemd for always-on access. ## Troubleshooting | Error | Cause | Solution | |-------|-------|----------| | "Task is not claimable (status: backlog)" | Task needs to be ready before claiming | hzl task set-status ready, or create with -s ready | | "Cannot block: status is X, expected in_progress or blocked" | Task must be claimed before blocking | Claim the task first: hzl task claim --assignee | | "Cannot complete: status is X" | Task must be in_progress or blocked | Claim the task first | ## OpenClaw-specific notes - Run hzl ... via the Exec tool. - OpenClaw skill gating checks requires.bins on the host at skill load time. If sandboxing is enabled, the binary must also exist inside the sandbox container too. Install it via agents.defaults.sandbox.docker.setupCommand (or use a custom image). - If multiple agents share the same HZL database, use distinct --assignee ids (for example: orchestrator, subagent-claude, subagent-gemini`) and rely on leases to avoid collisions.