hzlPersistent task ledger for agent coordination. Plan multi-step work, checkpoint progress across session boundaries, and coordinate across multiple agents wit...
Install via ClawdBot CLI:
clawdbot install tmchow/hzlHZL (https://hzl-tasks.com) is a local-first task ledger that agents use to:
This skill teaches an agent how to use the hzl CLI.
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:
Skip HZL for:
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.
| Command | Effect |
|---------|--------|
| hzl init --force | DELETES ALL DATA. Prompts for confirmation. |
| hzl init --force --yes | DELETES ALL DATA WITHOUT CONFIRMATION. |
| hzl task prune ... --yes | PERMANENTLY DELETES old done/archived tasks and history. |
Never run these unless the user explicitly asks you to delete data. There is no undo.
--parent ). Max 1 level of nesting. Parent tasks are never returned by hzl task claim --next.Use one shared project. Requests and initiatives become parent tasks, not new projects.
hzl project list # Check first — only create if missing
hzl project create openclawEverything goes into openclaw. hzl task claim --next -P openclaw always works.
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.
hzl project create research
hzl project create writing
hzl project create coding
hzl project create marketing
hzl project create coordination # for cross-agent workPool routing rule: assign tasks to a project without --agent. Any eligible agent claims with --next.
# Assigning work to the research pool (no --agent)
hzl task add "Research competitor pricing" -P research -s ready
# Kenji (or any researcher) claims it
hzl task claim --next -P research --agent kenjiOnly use --agent when you specifically want one person. Use --project when any eligible agent should pick it up.
hzl workflow run start --agent <agent-id> --project <project> --jsonThis 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.
hzl task list -P <project> --available # What's ready?
hzl task stuck # Any expired leases?
# If stuck tasks exist, read their state before claiming
hzl task show <stuck-id> --view standard --json
hzl task steal <stuck-id> --if-expired --agent <agent-id>
hzl task show <stuck-id> --view standard --json | jq '.checkpoints[-1]'
# Otherwise claim next available
hzl task claim --next -P <project> --agent <agent-id>hzl task add "Feature X" -P openclaw -s ready # Single-agent
hzl task add "Research topic Y" -P research -s ready # Pool-routed (multi-agent)
hzl task add "Subtask A" --parent <id> # Subtask
hzl task add "Subtask B" --parent <id> --depends-on <a-id> # With dependencyhzl task claim <id> # Claim specific task
hzl task claim --next -P <project> # Claim next available
hzl task checkpoint <id> "milestone X" # Checkpoint progress
hzl task complete <id> # Finishhzl task set-status <id> ready # Make claimable
hzl task set-status <id> backlog # Move back to planning
hzl task block <id> --comment "reason" # Block with reason
hzl task unblock <id> # UnblockStatuses: backlog → ready → in_progress → done (or blocked)
hzl task complete <subtask-id>
hzl task show <parent-id> --view summary --json # Any subtasks remaining?
hzl task complete <parent-id> # Complete parent if all done# Hand off to another agent or pool — complete current, create follow-on atomically
hzl workflow run handoff \
--from <task-id> \
--title "<new task title>" \
--project <pool> # --agent if specific person; --project for pool
# Delegate a subtask — creates dependency edge by default
hzl workflow run delegate \
--from <task-id> \
--title "<delegated task>" \
--project <pool> \
--pause-parent # Block parent until delegated task is done--agent 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.
hzl task add "<delegated title>" -P <pool> -s ready --depends-on <parent-id>
hzl task checkpoint <parent-id> "Delegated X to <pool> pool. Waiting on <task-id>."
hzl task block <parent-id> --comment "Waiting for <delegated-task-id>"# Add dependency at creation
hzl task add "<title>" -P <project> --depends-on <other-id>
# Add dependency after creation
hzl task add-dep <task-id> <depends-on-id>
# Query dependencies
hzl dep list --agent <id> --blocking-only # What's blocking me?
hzl dep list --from-agent <id> --blocking-only # What's blocking work I created?
hzl dep list --project <p> --blocking-only # What's blocking in a pool?
hzl dep list --cross-project-only # Cross-agent blockers
# Validate no cycles
hzl validateCross-project dependencies are supported by default. Use hzl dep list --cross-project-only to inspect cross-project edges.
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:
hzl task checkpoint <id> "Implemented login flow. Next: add token refresh." --progress 50
hzl task checkpoint <id> "Token refresh done. Testing complete." --progress 100
hzl task progress <id> 75 # Set progress without a checkpointWhen a task transitions to done, HZL enqueues a callback to your configured endpoint. The drain command delivers queued callbacks.
hzl hook drain # Deliver all queued callbacks (run on a schedule)
hzl hook drain --dry-run # Preview what would be deliveredConfigure in ~/.config/hzl/config.json (create if missing):
{
"hooks": {
"on_done": {
"url": "<OPENCLAW_GATEWAY_URL>/events/inject",
"headers": {
"Authorization": "Bearer <YOUR_GATEWAY_TOKEN>"
}
}
}
}HZL uses a host-process model — no built-in daemon. In OpenClaw, run hzl hook drain as a recurring cron job every 2 minutes. Without a scheduler, callbacks queue but never fire.
# Claim with lease (prevents orphaned work)
hzl task claim <id> --agent <agent-id> --lease 30 # 30-minute lease
# Monitor for stuck tasks
hzl task stuck
# Recover an abandoned task
hzl task show <stuck-id> --view standard --json # Read last checkpoint first
hzl task steal <stuck-id> --if-expired --agent <agent-id>Use distinct --agent IDs per agent (e.g. henry, clara, kenji) so authorship is traceable.
The completability test: "I finished [task]" should describe a real outcome.
Split into multiple tasks when: parts deliver independent value or solve distinct problems.
Adding context:
hzl task add "Install sensors" -P openclaw \
-d "Mount at 7ft height per spec." \
-l docs/sensor-spec.md,https://example.com/wiring-guideDon't duplicate specs into descriptions — reference docs instead to avoid drift.
# Setup
hzl init # Initialize (safe, won't overwrite)
hzl status # Database mode, paths, sync state
hzl doctor # Health check
# List and find
hzl task list -P <project> --available # Ready tasks with met dependencies
hzl task list --parent <id> # Subtasks of a parent
hzl task list --root # Top-level tasks only
hzl task list -P <project> --tags <csv> # Filter by tags
# Create with options
hzl task add "<title>" -P <project> --priority 2 --tags backend,auth
hzl task add "<title>" -P <project> -s in_progress --agent <name>
# Web dashboard
hzl serve # Start on port 3456
hzl serve --host 127.0.0.1 # Restrict to localhost
hzl serve --background # Fork to background
hzl serve --status / --stop
# Authorship
hzl task claim <id> --agent alice
hzl task checkpoint <id> "note" --author bob # Records who did the action
hzl task claim <id> --agent "Claude" --agent-id "session-abc123"
# Cloud sync (optional)
hzl init --sync-url libsql://<db>.turso.io --auth-token <token>
hzl synchzl serve --print-systemd > ~/.config/systemd/user/hzl-web.service
systemctl --user daemon-reload
systemctl --user enable --now hzl-web
loginctl enable-linger $USERAvailable at http:// (accessible over Tailscale). macOS: use hzl serve --background instead.
These belong in your orchestration layer, not the task ledger.
hzl via the exec tool.TOOLS.md for your identity string, which projects to monitor, and the commands relevant to your role.--agent IDs per agent and rely on leases to avoid collisions in shared databases.hzl workflow run commands require HZL v2+. If unavailable, use the manual fallback patterns documented above.Generated Mar 1, 2026
A development team uses HZL to manage multi-step feature implementation across sessions. Tasks like 'Implement API endpoint', 'Write unit tests', and 'Update documentation' are added as subtasks under a parent task, with dependencies to ensure correct sequencing. Developers claim tasks from a 'coding' project pool, checkpoint progress after each session, and resume exactly where they left off, preventing work loss.
A marketing agency employs HZL to coordinate content production across writers, editors, and designers. Tasks such as 'Research topic', 'Draft blog post', and 'Design graphics' are assigned to respective project pools (e.g., 'research', 'writing', 'design'). Agents claim tasks based on availability, use checkpoints to save drafts, and handle dependencies to ensure timely delivery, improving handoff efficiency.
Researchers use HZL to plan and execute long-term studies with multiple phases. Tasks like 'Literature review', 'Data collection', and 'Analysis' are structured as parent tasks with subtasks, assigned to a 'research' project pool. Team members claim tasks, checkpoint findings after each session, and use leases to prevent overlaps, ensuring progress persists across weeks or months.
A support team implements HZL to manage complex customer issues requiring multi-agent coordination. Tickets are added as tasks in a 'support' project pool, with subtasks for 'Initial diagnosis', 'Technical investigation', and 'Resolution follow-up'. Agents claim tasks, use checkpoints to log updates, and route stuck tasks via leases, reducing response times and improving accountability.
An event planning company uses HZL to organize large-scale events with sequential tasks. Activities like 'Venue booking', 'Vendor coordination', and 'Guest management' are added as tasks in a 'coordination' project pool. Team members claim tasks, checkpoint milestones, and handle dependencies to ensure smooth execution, with work surviving across multiple planning sessions.
Offer HZL as a cloud-hosted service with tiered pricing based on team size and features. Revenue comes from monthly subscriptions, with plans for small teams (basic task tracking), mid-sized teams (advanced coordination and analytics), and enterprises (custom integrations and support). This model leverages the need for persistent, multi-agent task management in collaborative environments.
Sell HZL as a self-hosted solution for organizations with strict data privacy requirements, such as government or healthcare. Revenue is generated through one-time licensing fees or annual maintenance contracts, with add-ons for customization, training, and support. This model targets industries where local-first data control is critical.
Provide a free version of HZL for individual users or small teams with basic task tracking, while monetizing through premium features like advanced analytics, multi-agent pool routing, and API access. Revenue streams include upgrades to paid plans and in-app purchases for additional capabilities, encouraging adoption and upselling.
💬 Integration Tip
Integrate HZL with existing tools like Slack for notifications and Git for version control to enhance workflow automation and reduce manual overhead.
Guide for creating effective skills. This skill should be used when users want to create a new skill (or update an existing skill) that extends Claude's capabilities with specialized knowledge, workflows, or tool integrations.
Provides a 7-step debugging protocol plus language-specific commands to systematically identify, verify, and fix software bugs across multiple environments.
A comprehensive skill for using the Cursor CLI agent for various software engineering tasks (updated for 2026 features, includes tmux automation guide).
Write, run, and manage unit, integration, and E2E tests across TypeScript, Python, and Swift using recommended frameworks.
Control and operate Opencode via slash commands. Use this skill to manage sessions, select models, switch agents (plan/build), and coordinate coding through Opencode.
Coding style memory that adapts to your preferences, conventions, and patterns for consistent coding.