hzl-cli 1.5.1 → 1.7.0

package/README.md

@@ -1,164 +1,314 @@
-# HZL
+# HZL (Hazel)
 
-**Lightweight task tracking for AI agents and swarms.**
+**A shared task ledger for OpenClaw and poly-agent workflows.**
 
-HZL is a CLI-first task management system designed for solo developers working with multiple AI agents across multiple projects. It provides durable, local coordination without the overhead of team-oriented project management tools.
+OpenClaw is great at doing work: running tools, coordinating sub-agents, and maintaining memory.
+What it (and most agent tools) do not give you is a durable, shared backlog that survives:
 
-## Why HZL?
+- session boundaries
+- crashes/reboots
+- switching between different agent runtimes (Claude Code, Codex, Gemini, etc.)
 
-Most project management tools assume teams of humans collaborating on shared repositories. When you're a solo developer with AI agents as your primary collaborators, these tools become heavyweight:
+HZL fills that gap: a lightweight, local-first task tracker that any agent can read/write.
 
-- **Repository-level storage is limiting.** You work across many repos and non-code projects. HZL stores tasks at the user level (`~/.hzl/data.db`), giving you one source of truth for all your work.
+Using OpenClaw? Start here: [OpenClaw integration](#openclaw-integration)
 
-- **Agents need machine-readable interfaces.** HZL's CLI is optimized for programmatic use with `--json` output, atomic operations, and deterministic selection policies that agents can rely on.
+Not using OpenClaw? Jump to: [Using HZL with Claude Code, Codex, Gemini CLI, or any coding agent](#using-hzl-with-claude-code-codex-gemini-cli-or-any-coding-agent)
 
-- **Concurrent agents need coordination.** Multiple agents working in parallel can atomically claim tasks, preventing conflicts. No heartbeats required—checkpoints let agents recover each other's work.
+HZL provides:
 
-- **Active work, not archival.** HZL is designed for coordinating current projects, not storing years of task history. Track recent work, see progress stats, then let completed tasks fade.
+- Projects and tasks
+- Dependencies (`B` waits for `A`)
+- Checkpoints (progress snapshots you can resume from)
+- Leases (time-limited claims for multi-agent coordination)
+- Event history (audit trail)
+- Cloud Sync (multi-device/multi-agent synchronization with Turso)
+- A CLI + JSON output that agents can script against
 
-## Design Principles
+Data is stored in SQLite. Default location: `$XDG_DATA_HOME/hzl/data.db` (fallback `~/.local/share/hzl/data.db`); Windows: `%LOCALAPPDATA%\\hzl\\data.db`.
 
-1. **Tracker, not orchestrator.** HZL is a dumb ledger. It tracks work state—it doesn't orchestrate, prioritize, or decide what agents should do. Orchestration belongs elsewhere: in your control agents, workflow tools, or the agents themselves. This separation is intentional. HZL stays simple and reliable because it does one thing well.
+---
 
-2. **Events are truth.** Every change is an append-only event. Current state is a projection. Full audit trails, reconstructable history.
+## Why another task tracker?
 
-3. **Local-first.** SQLite with WAL mode. No network dependency. Works offline.
+Because most task trackers are built for humans.
 
-4. **Hierarchical but simple.** Projects contain tasks. Tasks can have subtasks and dependencies. That's it.
+HZL is built for agents:
 
-## Non-Goals
+- It is backend-first, not UI-first. Think "task database with a CLI," not "another Trello."
+- It is model-agnostic. Your tasks live outside any one vendor's memory or chat history.
+- It is multi-agent safe. Leases prevent orphaned work and enable clean handoffs.
+- It is resumable. Checkpoints let an agent crash, reboot, or swap models and keep going.
 
-HZL intentionally does not do these things:
+If you already have a favorite human todo app, keep it.
+If you need a shared task state that multiple agents can read/write, that is HZL.
 
-- **Orchestration.** HZL doesn't spawn agents, manage their lifecycles, assign work, or decide what should happen next. If you need a control agent that spawns sub-agents, that logic lives in your agent—not in HZL.
+---
 
-- **Task decomposition.** HZL won't break down "build the app" into subtasks. Humans or agents create the task hierarchy; HZL just tracks it.
+## Where HZL fits
 
-- **Smart scheduling.** `hzl next` uses simple, deterministic rules (priority, then FIFO). There's no learning, no load balancing, no routing based on agent capabilities. If you need smarter task selection, your orchestration layer decides and claims by ID.
+### 1) OpenClaw orchestrator + sub-agents
 
-- **Team collaboration.** No permissions, roles, notifications, or multi-user features. HZL assumes a single developer working with their agents.
+```mermaid
+flowchart LR
+  You[You] --> OC["OpenClaw (orchestrator)"]
+  OC --> Tools["OpenClaw tools<br/>(browser, exec, email, etc.)"]
+  OC <--> HZL[(HZL task ledger)]
+  OC --> S1[Claude Code]
+  OC --> S2[Codex / other]
+  S1 <--> HZL
+  S2 <--> HZL
+```
 
-- **Cloud sync.** Local SQLite by design. If you want sync, export/import or backup to your own storage.
+OpenClaw coordinates the work. HZL is the shared, durable task board that OpenClaw and its sub-agents can use across sessions.
 
-## Installation
+### 2) Any poly-agent system (no OpenClaw required)
 
-Requires Node.js 22.14+.
+```mermaid
+flowchart LR
+  U[You] --> O["Orchestrator (human or agent)"]
+  O <--> HZL[(HZL)]
+  O --> C[Claude Code]
+  O --> X[Codex]
+  O --> G[Gemini]
+  C <--> HZL
+  X <--> HZL
+  G <--> HZL
+```
 
-```bash
-npm install -g hzl-cli
+Same idea: once you are switching tools/models, you need a shared ledger.
+
+### 3) One agent, many sessions
+
+```mermaid
+flowchart LR
+  U[You] --> A["Coding agent<br>(Claude Code, Codex, etc)"]
+  A <--> HZL
+  A --> R[Repo / files]
 ```
 
-Or from source:
+Use HZL to persist "what's next" and "what changed" between sessions.
 
-```bash
-git clone https://github.com/tmchow/hzl.git
-cd hzl
-npm install
-npm run build
-npm link packages/hzl-cli
+### 4) HZL as the backend for your own UI
+
+```mermaid
+flowchart LR
+  UI[Lightweight web app] --> HZL
+  Agents[Agents + scripts] --> HZL
 ```
 
-## Quick Start
+If you want a human-friendly interface, build one. HZL stays the durable backend that both humans and agents can use.
 
-```bash
-# Initialize the database
-hzl init
+---
 
-# Create a project
-hzl project create myapp
+## Quickstart
 
-# Create tasks
-hzl task add "Set up authentication" -P myapp --priority 2 --tags backend,auth
-hzl task add "Write API tests" -P myapp --depends-on <task-id>
+### Install
 
-# List available work
-hzl task list --project myapp --available
+Requires Node.js 22.14+.
 
-# Claim and work
-hzl task next --project myapp
-hzl task claim <task-id> --author agent-1
-hzl task checkpoint <task-id> "Completed OAuth flow"
-hzl task complete <task-id>
+```bash
+npm install -g hzl-cli
+hzl init
 ```
 
-## Key Commands
+### Enable Cloud Sync (Optional)
 
-### Task Lifecycle
+Sync with a Turso database for multi-device/multi-agent access:
 
 ```bash
-hzl task add <title> -P <project>             # Create a task
-hzl task list [--project] [--status]          # List tasks
-hzl task next [--project]                     # Show next claimable task
-hzl task claim <id>                           # Claim a task
-hzl task complete <id>                        # Mark done
+hzl init --sync-url libsql://<db>.turso.io --auth-token <token>
 ```
 
-### For Agents
+### Create a project and tasks
 
 ```bash
-# All commands support --json for structured output
-hzl task list --project myapp --available --json
-hzl task claim <id> --author agent-1 --json
+hzl project create portland-trip
 
-# Checkpoints let agents recover each other's work
-hzl task checkpoint <id> "step-3-complete" --data '{"files":["a.ts","b.ts"]}'
-hzl task show <id> --json             # Get task details + history
+hzl task add "Check calendars for March weekends" -P portland-trip --priority 5
+hzl task add "Research neighborhoods + activities" -P portland-trip --priority 4
+hzl task add "Shortlist 2-3 weekend options" -P portland-trip --priority 3 \
+  --depends-on <calendar-task-id> --depends-on <research-task-id>
 ```
 
-### Stuck Task Recovery
+### Work with checkpoints
 
 ```bash
-hzl task claim <id> --lease 30  # Claim with 30-minute lease
-hzl task stuck                 # Find tasks with expired leases
-hzl task steal <id> --if-expired # Reclaim expired work
+hzl task claim <calendar-task-id> --author trevin-agent
+hzl task checkpoint <calendar-task-id> "Found 3 options: Mar 7-9, 14-16, 21-23"
+hzl task complete <calendar-task-id>
 ```
 
-### Human Oversight
+### Link to supporting documents
+
+Tasks stay lightweight. Use `--links` to reference design docs, brainstorms, or specs:
 
 ```bash
-hzl project list               # See all projects
-hzl task show <id>             # Task details + history
-hzl task comment <id> "guidance..."  # Add steering comments
+# Create a task that links to context documents
+hzl task add "Implement auth flow per design" -P myapp --priority 3 \
+  --links docs/designs/auth-flow.md \
+  --links docs/brainstorm/2026-01-auth-options.md
+
+# The agent reads linked files for context, task stays focused on the work
+hzl task show <id> --json
+# → { "links": ["docs/designs/auth-flow.md", "https://somedomain/resource.md"], ... }
 ```
 
-### Dependencies
+This pattern keeps tasks actionable while pointing agents to richer context stored elsewhere.
+
+### Use JSON output when scripting
 
 ```bash
-hzl task add-dep <task> <depends-on> # Task waits for dependency
-hzl task remove-dep <task> <dep>     # Remove dependency
-hzl validate                         # Check for cycles
+hzl task show <id> --json
+hzl task next --project portland-trip --json
 ```
 
-## Configuration
+---
+
+## Core concepts (the stuff that matters)
+
+### Tasks are units of work, not reminders
+
+HZL is optimized for "do work, report progress, unblock the next step."
+
+If you need time-based reminders, pair HZL with a scheduler (cron, OpenClaw cron, etc.).
+
+### Checkpoints are progress snapshots
+
+A checkpoint is a compact, durable record of what happened:
+
+- what you tried
+- what you found
+- what's still missing
+- links, commands, or file paths needed to resume
+
+### Dependencies encode ordering
+
+Dependencies are how an agent avoids premature work:
+
+- "Don't search flights before you know dates."
+- "Don't open a PR before tests pass."
+
+### Leases make multi-agent handoffs reliable
+
+Leases are time-limited claims:
+
+- A worker agent claims a task with `--lease 30`
+- If it disappears, the lease expires
+- Another agent can detect stuck work and take over
+
+### Cloud Sync & Offline-First
+
+HZL uses a **local-first** architecture. You always read/write to a fast local database. Sync happens in the background via Turso/libSQL.
+
+```mermaid
+flowchart TD
+    CLI[User / Agent CLI]
+    subgraph Local["Local Machine"]
+        Cache[(cache.db<br/>Reads)]
+        Events[(events.db<br/>Writes)]
+        Sync[Sync Engine]
+    end
+    Cloud[(Turso / Cloud)]
+
+    CLI -->|Read| Cache
+    CLI -->|Write| Events
+    Events -->|Rebuild| Cache
+    Events <-->|Sync| Sync
+    Sync <-->|Replication| Cloud
+```
+
+---
+
+## Patterns
 
-HZL stores configuration in `~/.hzl/config.json`. The config file is created automatically when you run `hzl init`.
+### Pattern: Poly-agent backlog (recommended)
 
-To use a custom database location:
+Conventions that help:
+
+- Use consistent author IDs: `openclaw`, `claude-code`, `codex`, `gemini`, etc.
+- Claim tasks before work.
+- Checkpoint whenever you learn something that would be painful to rediscover.
+
+Example handoff:
 
 ```bash
-hzl init --db ~/my-project/tasks.db
+# Orchestrator creates task
+hzl task add "Implement REST API endpoints" -P myapp --priority 2
+TASK_ID=<id>
+
+# Worker agent claims with a lease
+hzl task claim "$TASK_ID" --author claude-code --lease 30
+hzl task checkpoint "$TASK_ID" "Endpoints scaffolded; next: auth middleware"
+hzl task complete "$TASK_ID"
 ```
 
-Subsequent commands will automatically use this database.
+### Pattern: Personal todo list (it works, but bring your own UI)
+
+HZL can track personal tasks and has the advantage of centralizing agent and personal tasks.
+This enables scenarios like OpenClaw assigning you tasks without needing to sync with other todo systems.
+
+HZL itself is not trying to be a polished, human-first todo app. You bring other pieces for that.
+
+If you want a todo app, build or use a UI:
+
+- a tiny web app
+- a TUI wrapper
+- a menu bar widget
+
+HZL stays the storage layer and concurrency-safe ledger underneath.
+
+---
+
+## Using HZL with Claude Code, Codex, Gemini CLI, or any coding agent
+
+**Why HZL when your agent already has task tracking?**
 
-**Config resolution order (highest to lowest priority):**
-1. `--db` flag
-2. `HZL_DB` environment variable
-3. `~/.hzl/config.json`
-4. Default: `~/.hzl/data.db`
+Many coding agents (like Claude Code) have built-in task management. HZL complements rather than replaces it:
 
-## Environment Variables
+- **Cross-agent workflows**: If you use Claude Code *and* Codex *and* Gemini, each has its own task system. HZL is the shared ledger they can all read/write.
+- **Session persistence**: Built-in task trackers often reset between sessions. HZL persists to disk (and optionally to cloud).
+- **Orchestration**: When one agent delegates to another, HZL provides the handoff mechanism (claim, checkpoint, complete).
+- **Backup**: With cloud sync enabled, your task state survives machine failures.
 
-| Variable | Description |
-|----------|-------------|
-| `HZL_DB` | Override database location |
-| `HZL_CONFIG` | Override config file location (default: `~/.hzl/config.json`) |
-| `HZL_AUTHOR` | Default author for claims/comments |
-| `HZL_AGENT_ID` | Default agent identifier |
+If you only ever use one agent and never need cross-session persistence, the built-in tracker is fine. Once you need durability or multi-agent coordination, reach for HZL.
 
-## Claude Code Marketplace
+If your coding agent supports an instruction file (for example `CLAUDE.md`, `AGENTS.md`, `GEMINI.md`, etc.), add a short policy so the agent reaches for HZL consistently.
 
-HZL includes a [Claude Code](https://claude.ai/code) plugin marketplace with skills that help AI agents work effectively with HZL.
+### Drop-in policy snippet
+
+```md
+### HZL task ledger (durable, cross-agent task tracking)
+
+HZL is a shared task database that persists across sessions and works across different agents.
+Use it when work spans multiple sessions, involves handoffs to other agents, or needs durable backup.
+If this agent has built-in task tracking, HZL complements it for cross-agent and multi-session work.
+
+When to use HZL:
+- Multi-session work that must survive restarts
+- Coordination with other agents (Claude Code ↔ Codex ↔ Gemini, etc.)
+- Work delegated to sub-agents that need explicit handoff
+- When you need task state backed up to cloud
+
+Workflow:
+1) Create or use an HZL project for the work.
+2) Break work into tasks with dependencies. Use `--links` to reference design docs or specs.
+3) Claim tasks before work and checkpoint after meaningful progress.
+4) Use `--json` when producing output another tool will parse.
+
+Key commands:
+- `hzl project create <name>`
+- `hzl task add "<title>" -P <project> [--depends-on <id>] [--links <file>]`
+- `hzl task claim <id> --author <agent-id> [--lease 30]`
+- `hzl task checkpoint <id> "<progress + next step>"`
+- `hzl task complete <id>`
+```
+
+That snippet is intentionally short. The goal is consistency, not ceremony.
+
+### Claude Code marketplace (optional)
+
+HZL includes a Claude Code plugin marketplace with skills that help agents work effectively with HZL.
 
 ```bash
 # Add the marketplace
@@ -170,62 +320,92 @@ HZL includes a [Claude Code](https://claude.ai/code) plugin marketplace with ski
 
 See [`packages/hzl-marketplace`](./packages/hzl-marketplace) for details.
 
-## Related Projects
+---
+
+## OpenClaw integration
 
-- [Beads](https://github.com/steveyegge/beads) - Steve Yegge's task management for agents
-- [beads-rust](https://github.com/Dicklesworthstone/beads_rust) - Rust port of Beads
+OpenClaw is a self-hosted AI assistant that can coordinate tools and sub-agents.
+HZL fits well as the task ledger that OpenClaw (and its sub-agents) can share.
 
-HZL takes a different approach: user-level storage, CLI-first for agents, and designed for solo developers coordinating multiple agents across projects.
+### Quick start (recommended)
 
-## Development
+Copy/paste this into an OpenClaw chat (single prompt):
 
-```bash
-npm install
-npm run build
-npm test
-npm run lint
+```
+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/docs/openclaw/tools-prompt.md to my TOOLS.md.
+```
+
+### Manual setup
+
+1) Install HZL on the machine running OpenClaw:
 
-# Try the sample project
-hzl sample-project
+```bash
+npm install -g hzl-cli
+hzl init
 ```
 
----
+2) Install the HZL skill from https://www.clawhub.ai/tmchow/hzl  
+   Skill source (for reference only): **[`docs/openclaw/skill-hzl.md`](./docs/openclaw/skill-hzl.md)**
 
-## CLAUDE.md / AGENTS.md Snippet
+3) Teach OpenClaw when to use HZL (important):
+   - Copy/paste from: **[`docs/openclaw/tools-prompt.md`](./docs/openclaw/tools-prompt.md)**
+   - Or tell OpenClaw to add this policy to `TOOLS.md`:
 
-Copy this into your project's `CLAUDE.md` or `AGENTS.md`:
+```
+HZL is a tool available to you for task management in certain cases. I want you to add this information to your TOOLS.md in the right way so you remember how to use it:
+https://raw.githubusercontent.com/tmchow/hzl/main/docs/openclaw/tools-prompt.md
+```
 
-````markdown
-## Task Management
+---
 
-This project uses [HZL](https://github.com/tmchow/hzl) for task tracking.
+## When to use HZL (and when not to)
 
-### Choosing a project name
+### Use HZL when:
 
-Use a **stable identifier** you can always derive:
+- work has multiple steps and you want explicit sequencing
+- work spans multiple sessions (resume tomorrow with confidence)
+- you are coordinating multiple agents or model providers
+- you need durable status reporting (done / in progress / blocked / next)
+- you want a task ledger your own UI can sit on top of
 
-- **Working in a repo?** Use the repository name (e.g., `hzl`, `my-app`)
-- **Long-lived agent?** Use your agent identity (e.g., `openclaw`, `kalids-openclaw`)
+### Consider something else when:
 
-Projects group related work. Don't create per-feature projects—keep them long-lived. If no project is specified, tasks default to `inbox`.
+- you need time-based reminders or notifications (use a scheduler + a notifier)
+- you need rich human workflow features (due dates, recurring tasks, calendar views)
+- you are tracking an org-wide backlog (GitHub/Jira/etc. may be a better fit)
 
-### Commands
+---
+
+## CLI reference (short)
 
 ```bash
+# Setup
+hzl init                                      # Initialize database (add --sync-url for cloud)
+
 # Projects
-hzl project list                                   # List all projects
-hzl project rename <old> <new>                     # Rename a project
+hzl project create <name>                     # Create a project
+hzl project list                              # List all projects
 
 # Tasks
-hzl task add "Task title" -P <project>             # Create task
-hzl task next --project <project> --json           # Show next available
-hzl task show <task-id> --json                     # Task details + history
-hzl task checkpoint <task-id> "<name>"             # Save progress
-hzl task complete <task-id>                        # Mark done
-```
+hzl task add "<title>" -P <project>           # Create task (--depends-on, --links, --priority)
+hzl task list --project <project>             # List tasks (--available for claimable only)
+hzl task next --project <project>             # Get highest priority available task
+
+# Working
+hzl task claim <id> --author <name>           # Claim task (--lease <minutes> for expiry)
+hzl task checkpoint <id> "<message>"          # Save progress snapshot
+hzl task complete <id>                        # Mark done
 
-Use `--json` for structured output. HZL handles atomic claiming.
-````
+# Coordination
+hzl task stuck                                # Find expired leases
+hzl task steal <id> --if-expired              # Take over abandoned task
+hzl task show <id> --json                     # Task details (--json for scripting)
+
+# Diagnostics
+hzl sync                                      # Sync with cloud (if configured)
+hzl status                                    # Show database and sync state
+hzl doctor                                    # Health checks
+```
 
 ---
 

package/dist/__tests__/integration/cli-integration.test.js

@@ -3,8 +3,8 @@ import fs from 'fs';
 import path from 'path';
 import { execSync } from 'child_process';
 import { fileURLToPath } from 'url';
-import Database from 'better-sqlite3';
-import { initializeDb, closeDb } from '../../db.js';
+import Database from 'libsql';
+import { initializeDbFromPath, closeDb } from '../../db.js';
 import { createTestContext, hzlJson, hzlMayFail, } from './helpers.js';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -32,7 +32,7 @@ describe('CLI Integration Tests', () => {
         it('creates database file', () => {
             const result = hzlJson(ctx, 'init');
             expect(result.created).toBe(true);
-            expect(result.path).toBe(ctx.dbPath);
+            expect(result.eventsDbPath).toBe(ctx.dbPath);
             expect(fs.existsSync(ctx.dbPath)).toBe(true);
         });
         it('is idempotent', () => {
@@ -44,15 +44,15 @@ describe('CLI Integration Tests', () => {
         });
         it('returns path information', () => {
             const result = hzlJson(ctx, 'init');
-            expect(result.path).toBe(ctx.dbPath);
+            expect(result.eventsDbPath).toBe(ctx.dbPath);
             expect(result.created).toBe(true);
         });
     });
     describe('which-db command', () => {
         it('returns resolved database path', () => {
             const result = hzlJson(ctx, 'which-db');
-            expect(result.path).toBe(ctx.dbPath);
-            expect(result.source).toBe('cli');
+            expect(result.eventsDbPath).toBe(ctx.dbPath);
+            expect(result.cacheDbPath).toBe(ctx.cachePath);
         });
     });
     describe('task lifecycle round-trip', () => {
@@ -107,14 +107,14 @@ describe('CLI Integration Tests', () => {
             const addResult = hzlJson(ctx, `task add-dep ${task2.task_id} ${task1.task_id}`);
             expect(addResult.task_id).toBe(task2.task_id);
             expect(addResult.depends_on_id).toBe(task1.task_id);
-            const db = new Database(ctx.dbPath);
+            const db = new Database(ctx.cachePath);
             const deps = db
                 .prepare('SELECT depends_on_id FROM task_dependencies WHERE task_id = ?')
                 .all(task2.task_id);
             expect(deps.map((d) => d.depends_on_id)).toContain(task1.task_id);
             db.close();
             hzlJson(ctx, `task remove-dep ${task2.task_id} ${task1.task_id}`);
-            const dbAfter = new Database(ctx.dbPath);
+            const dbAfter = new Database(ctx.cachePath);
             const depsAfter = dbAfter
                 .prepare('SELECT depends_on_id FROM task_dependencies WHERE task_id = ?')
                 .all(task2.task_id);
@@ -243,6 +243,7 @@ describe('CLI Integration Tests', () => {
             expect(fs.existsSync(exportPath)).toBe(true);
             const content = fs.readFileSync(exportPath, 'utf-8');
             const lines = content.trim().split('\n').filter((line) => line.length > 0);
+            // 1 project_created (inbox) + 2 task_created events
             expect(lines).toHaveLength(3);
             const events = lines.map((line) => JSON.parse(line));
             expect(events[0].type).toBe('project_created');
@@ -283,7 +284,7 @@ describe('CLI Integration Tests', () => {
             const task = addTask('inbox', 'Stuck task');
             hzlJson(ctx, `task set-status ${task.task_id} ready`);
             const pastLease = new Date(Date.now() - 60000).toISOString();
-            const services = initializeDb(ctx.dbPath);
+            const services = initializeDbFromPath(ctx.dbPath);
             try {
                 services.taskService.claimTask(task.task_id, {
                     author: 'stalled-agent',