tl : a task ledger (cli) for humans and coding agents

Table of Contents

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? 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 tlcli tool. (Git hub)

The core loop

The basic workflow is four commands. Here is how I use it with an agent:

tl ready --json                             # what needs doing?
tl claim task-hfv --actor pi:worker-deepseek     #PI: I take this one
# ... work happens ...
tl note task-hfv -m "Got the API endpoint working, tests pass"
tl note task-hfv -m "Endpoint ready for review, check auth/errors.go"
tl release task-hfv --actor pi:worker-deepseek    # hand off to reviewer

The reviewer picks it up:

tl ready --tag role:reviewer
tl claim task-x3n --actor pi:reviewer
# ... review ...
tl close task-x3n --actor pi:reviewer

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
tl create "Implement login" --tag role:implementer --tag role:reviewer

# Worker
tl ready --tag role:implementer
tl claim task-hfv
tl refine task-hfv --add-tag stage:done-implement
tl release task-hfv

# Reviewer
tl list --tag stage:done-implement --tag role:reviewer
tl claim task-hfv
tl refine task-hfv --remove-tag stage:done-implement --add-tag stage:reviewed
tl close task-hfv

The rest of the toolbox

A few other commands worth knowing:

tl show <id>                       # full task detail — frontmatter, description, notes
tl history <id>                    # event-by-event audit trail
tl stale                           # claims whose lease has expired
tl doctor [--json] [--fix] [--force]  # scan ledger for issues, optionally repair
tl list [--all --status s --tag t]  # browse tasks with filters

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/
  config.yaml         # defaults (claim TTL, actor settings)
  tasks/
    task-<id>.md      # one Markdown file per task
  events.jsonl        # append-only audit trail

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

Or use the install script:

curl -fsSL https://raw.githubusercontent.com/aholbreich/tl/main/install.sh | sh

Then in your project:

cd your-project
tl init                          # creates .tl/
tl create "First task"
tl agents --write-files          # optional: bootstrap AGENTS.md for your coding agent

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 instrucitons

Well how will agent get to know who to work with it? tl needs to be fully understood by agents. So the current AGENTS.md is something like this.

no worries you can allays get it via tl agents try also tl agents --write-files --dry-run and if you want to update Agent files without —dry-run.

I’m not insisting on that instruction set. But i think it summarizes the agent perspective on the tool well.

<!-- BEGIN TL WORKFLOW -->
## 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 <task-id> --actor agent-name
tl note <task-id> -m "..." --actor agent-name
tl close <task-id> --actor agent-name

Recommended workflow:

1. Start from the task ledger.
   - Run `tl ready --json` to find unclaimed work, or `tl ready --tag <role> --json` to filter by role-ish tags.
   - If the human hands you a task, run `tl show <task-id>` and `tl history <task-id>` before editing.
   - For non-trivial implementation work, prefer a matching tl task. If none exists, create one or ask whether to create one before editing.
2. Preserve and follow context.
   - Treat `References:` from `tl show` as context pointers; inspect referenced files, docs, URLs, tickets, or feature specs before editing.
   - If no suitable task exists, create one with `tl create "<title>" -d "<description>" --ref <path-or-url>`.
   - If your work uncovers a separable follow-up, create it with `tl create` and add useful `--ref` values instead of silently expanding scope.
3. Claim before editing.
   - Run `tl claim <task-id> --actor agent-name` before making code, doc, config, or test changes.
   - Do **not** work on a task claimed by another active actor unless explicitly told.
4. Re-check context after claiming.
   - Run `tl show <task-id>` to confirm scope, dependencies, references, and notes.
   - Run `tl history <task-id>` to read prior events, stale claims, decisions, and handoff context.
5. Record progress while working.
   - Re-run `tl claim <task-id> --actor agent-name` periodically on long work — it extends the lease (heartbeat pattern).
   - Use `tl note <task-id> -m "..." --actor agent-name` for meaningful progress, decisions, failed approaches, blockers, test results, and handoff context.
6. Use dependencies and stalled-work commands when needed.
   - `tl dep add <task-id> --on <task-id>` - make one task wait for another.
   - `tl dep remove <task-id> --on <task-id>` - remove a dependency.
   - `tl stale` — list expired claims that may need cleanup or handoff.
   - If unsure whether a command exists in this version, run `tl <cmd> --help`.
7. End every session with an explicit task ledger state.
   - `tl close <task-id> --actor agent-name` - work is done and verified.
   - `tl cancel <task-id> -m "<reason>" --actor agent-name` - work won't be done.
   - `tl block <task-id> -m "<blocker>" --actor agent-name` - external blocker; claim is released.
   - `tl unblock <task-id> --actor agent-name` - external blocker is resolved.
   - `tl pending <task-id> --question "..." --actor agent-name` - you need a human decision; claim is released.
   - `tl resolve <task-id> --answer "..." --actor agent-name` - record the human answer and reopen the task.
   - `tl release <task-id> --actor agent-name` - you're stepping away cleanly; leave a comprehensive note first.

Rules:

- Prefer tasks from `tl ready`; blocked, pending, done, cancelled, or actively claimed tasks are not ready.
- Use `--json` for automation and parsing (`tl ready --json`, `tl show <task-id> --json`, `tl history <task-id> --json`).
- Leave notes for partial progress, failed approaches, decisions, test results, blockers, and handoffs.
- Attach references with `--ref` when they help the next human or agent recover context quickly.
- Do **not** edit `.tl/events.jsonl` manually.
- If `.tl/` is missing, ask the human whether to run `tl init`.
<!-- END TL WORKFLOW -->

Closing thoughts

I built tl because I needed something between a chat thread and a full issue tracker. Something that lives in the repo, works offline, and gives agents a structured way to coordinate without a server.

It is early days - I have been using it for maybe two weeks for real work. The thing I like most is how it changes the conversation with the agent. Instead of “implement this feature” followed by a long silence, I get claims, notes, questions, answers. The work becomes visible.

There is more I want to do. The tool is open source, contributions welcome.

If you have been through a similar loop - what do you use to keep work visible between sessions?

Support on Github