tl : a task ledger (cli) for humans and coding agents | Alexander Holbreich<br>Skip to content
Go back<br>tl : a task ledger (cli) for humans and coding agents<br>30 May, 2026<br>Table of Contents
Open Table of Contents
Where the work lives
The core loop
Pre-planning with tags
The rest of the toolbox
What is in .tl/?
Install and try it
Agent instructions
Closing thoughts
Where the work lives
Humans have memory (but we don’t like to remember too many details) - LLMs have no memory at all (it’s all session memory or supporting tools).
When I work with coding agents - Preferably Pi, but sometimes Codex, Claude Code, whichever I have open today, I keep running into the same question: where does the plan live? How do I hand over work? How does an agent hand work to itself or to the next agent? Where does the context live?<br>There are many angles, but I think slicing work into tasks and organizing agentic collaboration around them is the part worth getting right. That’s my intuition at the moment.
That’s why I was so drawn to Beads a few weeks ago. Beads has the right idea: work items close to the code, dependency-aware ready queues, claim/release primitives for agents. But for my use case it was more than I needed and too opinionated toward a specific “Gas Town” workflow.
So I built tl, a CLI tool. (GitHub)
The core loop
The basic workflow is four commands. Here is how I use it with an agent:
tl ready --json # what needs doing?<br>tl claim task-hfv --actor pi:worker-deepseek # PI: I take this one<br># ... work happens ...<br>tl note task-hfv -m "Got the API endpoint working, tests pass" --actor pi:worker-deepseek<br>tl note task-hfv -m "Endpoint ready for review, check auth/errors.go" --actor pi:worker-deepseek<br>tl release task-hfv --actor pi:worker-deepseek # hand off to reviewer<br>The reviewer picks it up:
tl ready --tag role:reviewer<br>tl claim task-hfv --actor pi:reviewer<br># ... review ...<br>tl close task-hfv --actor pi:reviewer<br>Pre-planning with tags
You don’t need to, but you could define “agent collaboration” around one task via tags. I’m still experimenting with this. It could look like this:
# I have an idea<br>tl create "Implement login" --tag role:implementer --tag role:reviewer
# Worker<br>tl ready --tag role:implementer<br>tl claim task-hfv --actor pi:worker<br>tl refine task-hfv --add-tag stage:done-implement --actor pi:worker<br>tl release task-hfv --actor pi:worker
# Reviewer<br>tl list --tag stage:done-implement --tag role:reviewer<br>tl claim task-hfv --actor pi:reviewer<br>tl refine task-hfv --remove-tag stage:done-implement --add-tag stage:reviewed --actor pi:reviewer<br>tl close task-hfv --actor pi:reviewer<br>The rest of the toolbox
A few other commands worth knowing:
tl show id> # full task detail — frontmatter, description, notes<br>tl history id> # event-by-event audit trail<br>tl stale # claims whose lease has expired<br>tl doctor [--json] [--fix] [--force] # scan ledger for issues, optionally repair<br>tl list [--all --status s --tag t] # browse tasks with filters<br>tl show is what an agent reads before starting. tl history is what it reads for handoff context. tl doctor finds the rot that accumulates when you and an agent share a directory — broken dependencies, orphaned temp files, stale claims. --fix repairs what it can.
What is in .tl/?
The whole ledger is three things:
.tl/<br>config.yaml # defaults (claim TTL, actor settings)<br>tasks/<br>task-.md # one Markdown file per task<br>events.jsonl # append-only audit trail<br>Every mutating command appends one JSON line to events.jsonl. Task files are atomic-write (task-xyz.md.tmp → rename). No daemon, no database, no push — just files you can cat, grep, and git diff at any commit.
Install and try it
The fastest way:
brew install aholbreich/tap/tl<br>Or use the install script:
curl -fsSL https://raw.githubusercontent.com/aholbreich/tl/main/install.sh | sh<br>Then in your project:
cd your-project<br>tl init # creates .tl/<br>tl create "First task"<br>tl agents --write-files # optional: bootstrap AGENTS.md for your coding agent<br>The tl agents --write-files step is worth doing. It writes a managed workflow block into AGENTS.md, CLAUDE.md, or similar files so your agent knows how to use the ledger without being told each time.
Agent instructions
How does an agent know how to work with it? tl needs to be discoverable by agents. So the current AGENTS.md block looks something like this.
No worries, you can always get it via tl agents. Try tl agents --write-files --dry-run, and if you want to update agent files, run it without --dry-run.
I’m not insisting on that instruction set. But I think it summarizes the agent perspective on the tool well.
## tl workflow
This repository uses `tl` cli for local task coordination between humans and agents. Treat the task ledger as the source of truth for non-trivial work: planning, claiming, progress notes, blockers, handoffs, and completion.
Use an explicit actor on mutating commands so claims, notes, and handoffs are attributed clearly:
tl claim --actor agent-name<br>tl note...