HZL (Hazel)

External task ledger for coding agents.

📚 Full Documentation — Concepts, workflows, and CLI reference

---

Why HZL?

Most task trackers are built for humans. HZL is built for agents:

• Backend-first — Task database with a CLI, not another Trello
• Model-agnostic — Tasks live outside any vendor's memory
• Multi-agent safe — Atomic claiming prevents duplicate work
• Resumable — Checkpoints let work survive session boundaries

If you already have a favorite human todo app, keep it. HZL is for shared task state that multiple agents can read and write.

When to Use HZL

HZL is for when work outlives a single session:

• Cross-agent workflows — Claude Code, Codex, Gemini sharing one task board
• Session persistence — Pick up where you left off tomorrow
• Orchestration — One agent delegates to another with clean handoffs
• Backup — Cloud sync keeps task state safe

If you only use one agent and never need persistence, the built-in tracker is fine. Once you need durability or coordination, reach for HZL.

---

Quickstart

1. Install

Requires Node.js 22.14+.

curl -fsSL "https://raw.githubusercontent.com/tmchow/hzl/main/scripts/install.sh?$(date +%s)" | bash

Alternative install methods

Homebrew (macOS/Linux):

brew tap tmchow/hzl && brew install hzl && hzl init

NPM:

npm install -g hzl-cli && hzl init

2. Add to Your Project

Append the agent policy to your repo so agents know when to use HZL:

curl -fsSL https://raw.githubusercontent.com/tmchow/hzl/main/snippets/AGENT-POLICY.md >> AGENTS.md

3. Create Tasks and Work

# Create a project and tasks
hzl project create my-feature
hzl task add "Design the API" -P my-feature
hzl task add "Implement endpoints" -P my-feature --depends-on 1

# Claim and work
hzl task claim 1 --assignee claude-code
hzl task checkpoint 1 "API design complete"
hzl task complete 1

# View progress
hzl serve  # Opens web dashboard at localhost:3456

Enable Cloud Sync (Optional)

hzl init --sync-url libsql://<db>.turso.io --auth-token <token>

---

Documentation

Section	What's There
Getting Started	Installation, quickstart, agent setup
Concepts	Projects, tasks, dependencies, checkpoints, leases
Workflows	Single-agent, multi-agent, handoffs, breakdown patterns
CLI Reference	Complete command documentation
Web Dashboard	Kanban board setup and usage
Troubleshooting	Common issues and fixes

---

Agent Setup

Claude Code

/plugin marketplace add tmchow/hzl
/plugin install hzl@hzl

OpenAI Codex

mkdir -p ~/.codex/skills/hzl
curl -fsSL https://raw.githubusercontent.com/tmchow/hzl/main/skills/hzl/SKILL.md -o ~/.codex/skills/hzl/SKILL.md

OpenClaw

Copy/paste into an OpenClaw chat:

Install HZL from https://github.com/tmchow/hzl and run hzl init. Install the HZL skill from https://www.clawhub.ai/tmchow/hzl. Then append the HZL policy from https://raw.githubusercontent.com/tmchow/hzl/main/openclaw/OPENCLAW-TOOLS-PROMPT.md to my TOOLS.md.

See Coding Agents Setup for full details.

---

Packages

Package	Description	Install
hzl-cli	CLI for task management	npm install -g hzl-cli
hzl-core	Core library for programmatic use	npm install hzl-core
hzl-web	Web server and Kanban dashboard	npm install hzl-web

---

License

MIT