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:

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

When to use HZL

Use HZL when the agent needs a durable source of truth for work state:

Not ideal for:

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

Quick reference

```bash

Setup

hzl init

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>

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

hzl task show <id> --json

hzl task complete <id>

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

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.

```bash

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

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

```bash

hzl task claim <id> --author orchestrator

...do work...

hzl task checkpoint <id> "Implemented login flow. Next: add token refresh. Blocker: need API key for staging."

hzl task complete <id>

```

Coordinate sub-agents with leases

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

```bash

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:

Monitor:

```bash

hzl task show <id> --json

hzl task stuck

hzl task steal <id> --if-expired --author orchestrator

```

Web Dashboard

HZL includes a built-in Kanban dashboard for monitoring task state:

```bash

hzl serve # Start on port 3456

hzl serve --background # Fork to background

```

The dashboard shows tasks in columns (Backlog → Blocked → Ready → In Progress → Done), with filtering by date and project. Useful for human visibility into what agents are working on.

For always-on access (e.g., via Tailscale), run as a systemd service:

```bash

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

systemctl --user enable --now hzl-web

```

OpenClaw-specific notes