HZL: Persistent task tracking for agents

HZL (https://github.com/tmchow/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

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 <id>

  ). 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

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

hzl task add "Install garage sensors" -P openclaw \
  --links docs/sensor-spec.md \
  --links "https://example.com/wiring-guide"

⚠️ DESTRUCTIVE COMMANDS - READ CAREFULLY

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

hzl init --force

hzl init --force --yes

hzl task prune ... --yes

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>

# Work + persist progress
hzl task claim <id> --author <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> --reason "Waiting for API key"
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> --author <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:

--author

claim

--author

The

--author

# Alice owns the task
hzl task claim 1 --author 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

hzl task claim 1 --author "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> --author 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> --author orchestrator
hzl task checkpoint <id> "Implemented login flow. Blocked: need API key for staging."
hzl task block <id> --reason "Waiting for staging API key from DevOps"

# Later, when unblocked:
hzl task unblock <id>
hzl task checkpoint <id> "Got API key, resuming work"
hzl task complete <id>

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

--available

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> --author 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

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

http://<your-box>:3456

To use a different port:

hzl serve --port 8080 --print-systemd > ~/.config/systemd/user/hzl-web.service

macOS note: systemd is Linux-only. On macOS, use

hzl serve --background

Quick commands

hzl serve                    # Start in foreground (port 3456)
hzl serve --background       # Fork to background process
hzl serve --status           # Check if background server is running
hzl serve --stop             # Stop background server
hzl serve --host 127.0.0.1   # Restrict to localhost only

Use

--background

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

  --author

  ids (for example:

  orchestrator

  ,

  subagent-claude

  ,

  subagent-gemini

  ) and rely on leases to avoid collisions.