Quick start
From an empty repository to a working queue, in five commands.
Install
npm install -g @speekl/tasksEither way, the command it installs is tasks. Node 20 or newer is required.
Not installing globally?
Everywhere the docs say tasks, npx @speekl/tasks works identically. Agents
should fall back to it automatically when tasks is not on PATH.
Set up a project
Scaffold .tasks/
Run this at the root of the repository whose work you want to track.
tasks initThat creates .tasks/ with a config, a README describing the convention, and a
.gitignore for the transient lock directory. It also installs an agent
skill into .claude/skills/tasks/ so agents in this repo
reach for the CLI instead of inventing their own markdown convention.
✓ Initialized .tasks/ at /Users/you/acme-api/.tasks
.tasks/config.yml
.tasks/README.md
.tasks/.gitignore
.claude/skills/tasks/SKILL.md
.claude/skills/tasks/reference/convention.mdSkip the skill with tasks init --no-skill. Re-running init on an existing tree is
refused with exit 4 unless you pass --force, and even then an edited config.yml
is left alone.
Create some tasks
The first argument is the phase — a directory grouping one body of work. It is created on first use; there is no separate step.
tasks new auth-rework "Design token schema"
tasks new auth-rework "Implement refresh endpoint"The id defaults to a kebab-case slug of the name (design-token-schema), and must be
unique across the whole tree. Override it with --id.
Declare what waits on what
tasks dep add implement-refresh design-token-schemadep add refuses a reference to a task that does not exist, and refuses to introduce a
cycle — so a dependency you can add is one that can eventually resolve.
Fill in the body
tasks new scaffolds ## Description, ## Acceptance criteria, and ## Notes. Open
the file and write them, with any editor.
$EDITOR .tasks/auth-rework/design-token-schema.mdA task whose body is empty is not a task, it is a reminder. Put enough in it that a different agent arriving cold in a later session can do the work without asking.
Work the loop
tasks ready ID STATUS PHASE DEPENDS ON UPDATED
design-token-schema PENDING auth-rework — 2026-08-22 10:02
1 readyimplement-refresh is absent — it is blocked on the schema task. Claim what is ready,
do the work, then close it out:
tasks claim design-token-schema
# ...do the actual work...
tasks status design-token-schema DONERun tasks ready again and implement-refresh has appeared.
Commit it
.tasks/ is meant to be committed. Task state branches, merges, and reviews like the
rest of the repo.
git add .tasks .claude/skills/tasks
git commit -m "Track the auth rework in .tasks/"The one thing not to commit is .tasks/.locks/, and the scaffolded .gitignore
already handles that.
Keep the index fresh
_index.md is a generated overview that only regenerates on demand. Run
tasks reindex before committing, or let tasks validate --fix catch it.