TaskRail is a deterministic, file-based task and specification tracking CLI designed for coding agents. It maintains work progress as plain Markdown files within your repository, ensuring transparency and accessibility for both humans and AI.
Key Features:
Automatically selects the next task using dependencies, priority, and stable tie-breaking rules.
Manages status changes through command-line commands to ensure consistent updates.
Records verification outcomes with evidence stored in plain text files under planning/artifacts/.
Identifies gaps between specifications and tasks via coverage analysis.
Integrates directly with Git without requiring external databases or daemons.
Supports deployment via WinGet for easy installation on Windows.
Target Audience and Benefits:
TaskRail is ideal for developers, coding agents, project managers, and maintainers of large codebases. It provides a transparent ledger within your repositories, ensuring consistent task tracking whether managed by humans or AI. By integrating with Git and avoiding external databases, TaskRail offers a reliable way to manage complex projects. Its focus on plain Markdown files makes it versatile and easy to integrate into existing workflows.
TaskRail’s design ensures every status transition is recorded deterministically, eliminating ambiguity and fostering clear communication among team members.
README
Taskrail
Keep long-running work on the rails — in your repo, in plain Markdown, for humans and AI agents alike.
The Problem
An agent finishes a session and the plan is gone. The next session re-derives it,
picks a task someone already did, or declares work "done" with nothing to show
for it. You get plausible-looking progress and no way to audit it.
Chat history is not a work ledger. Neither is an issue tracker your agent cannot
reach, or a TODO.md nobody validates.
Taskrail puts the ledger in the repository: tracked work as Markdown files with a
machine-checkable schema, a generated current-state projection, and a CLI that
owns every status transition. Same repo, same question, same answer — whether a
person or an agent is at the keyboard. Git supplies history and review. There is
no database, no daemon, and no hidden automation.
taskrail init # adopt Taskrail in an existing repo, non-destructively
taskrail validate # confirm the layout and state are consistent
taskrail status # active spec, task counts, and what's next
Use Cases
1. Drive an AI agent through tracked work without losing the plot
The agent asks the CLI what to do next instead of guessing, and cannot fake a
transition — every status change goes through a command that rewrites the
ledger.
taskrail next --json # deterministic selection
taskrail start T-001 # mark it active
taskrail complete T-001 --note "implemented" # implementation done
taskrail verify T-001 --result pass --summary "acceptance met"
Selection follows status, dependencies, priority, and stable tie-breaking, and is
anchored to the active spec — so a fresh session lands on the same task a stale
one would. Every --json command emits one versioned envelope
(schema_version, command, warnings, and exactly one of result or
error), so an agent parses one shape.
For unattended runs, loop executes explicitly allowed tasks inside operator-set
bounds — see docs/loop.md.
2. Adopt it in a repository that already has work in flight
Nothing is rewritten and nothing is generated behind your back.
taskrail init --apply # scaffold specs/ + planning/
taskrail import notes.md --to tasks # rough notes -> task drafts, no LLM
taskrail import --apply draft.json # validate a draft and write real files
retrofit handles messier existing layouts, repair reconciles mechanical
STATE.md drift, and --with-skills installs the packaged agent skills. import
never calls a model: it structures what you wrote, and --emit-prompt hands an
agent a prompt for a richer draft you then review.
3. Make "done" mean something
Completing implementation and verifying it are separate steps. Verification
records a pass/fail outcome, writes inspectable evidence, and can open the
follow-up task in the same breath:
Each run leaves plain files under
planning/artifacts/verify//-/ —
plan.md, report.json, report.md. That tree is gitignored (a fresh
taskrail init inside a Git worktree writes the .gitignore rule for you),
reproducible local output: committed state never depends on it surviving a Git
round-trip.
4. See where the work actually stands
All read-only, all safe to run mid-session:
taskrail status # live snapshot, incl. work pointing away from the active spec
taskrail stats # aggregate metrics and dependency graphs
taskrail coverage # which spec areas have no task linked
coverage --gaps extends this with mechanical structural-gap candidates —
never violations, and never a reason validate fails.
What It Is Not
Not a built-in LLM provider integration — Taskrail is provider-agnostic and
manual-first.
Not a sandbox, container, or worktree orchestrator.
Not a background daemon, distributed worker pool, or multi-lane scheduler.
Not a built-in semantic spec-to-task generator or reviewer — the binary
provides mechanical reports and reviewed write boundaries, while optional
skills let an external agent supply judgement.
Install
brew install tessariq/tap/taskrail # macOS and Linux
winget install Tessariq.Taskrail # Windows
taskrail --version
From source (needs Go 1.26):
go install github.com/tessariq/taskrail/cmd/taskrail@latest
A plain go build/go install reports version 0.0.0-dev; release builds inject
it with -ldflags "-X main.version=vX.Y.Z". Tagged v* releases are published
automatically with GoReleaser for Linux/macOS/Windows on
amd64/arm64. Shell completion ships via Cobra —
source <(taskrail completion bash), and taskrail completion --help for zsh and
fish.
What a Task Looks Like
---
id: T-001
title: Bootstrap repository structure
status: todo
priority: high
spec_ref: specs/v0.1.0.md#summary
dependencies: []
updated_at: "2026-08-05T00:00:00Z"
---
# T-001 Bootstrap repository structure
## Description
Create the initial Taskrail structure, specs, and planning area.
## Acceptance
- `planning/STATE.md` exists.
- `taskrail validate` passes.
## Verification Notes
- Run `taskrail validate` and record the successful observation.
## Implementation Notes
Task files are the durable ledger. planning/STATE.md is the generated
projection of them — active spec, current task, status summary, blockers, next
action, latest verification result. Never hand-edit it or a status field; the
taskrail commands own those writes. Repository-wide human context belongs in
planning/NOTES.md, a human-owned sidecar the CLI creates once and never
rewrites.
Create and steer tasks through the CLI rather than editing frontmatter:
taskrail task new --title "Add machine envelope" --area uniform-agent-machine-results
taskrail task rename T-007 --slug add-slug # re-slug id + filename atomically
taskrail task repoint T-007 --area some-anchor # move it onto another spec area
taskrail task dependency add T-010-api T-009-model # one reviewed edge
mise provisions the pinned toolchain (Go, task,
lefthook) from mise.toml — optional; direct go commands and the
Taskfile.yml targets work without it:
mise run setup # provision, build taskrail onto PATH, wire the opt-in git hooks
go build ./cmd/taskrail && go test ./...
CI (.github/workflows/ci.yml) is the authoritative gate and runs the build/test
matrix over Linux, Windows, and macOS. Optional
lefthook hooks mirror it locally
(task hooks:install), with pre-push on the shorter task test:short lane;
pre-commit also runs the agent-identity guard, and commit-msg/pre-push
refuse agent-attribution trailers and session links. Do not bypass them with
--no-verify. See
CONTRIBUTING.md for the PR checklist and the AI-assisted
contribution policy, and
AGENTS.md for the binary-freshness
contract that matters when hacking on Taskrail itself.
Status
Taskrail is an in-progress open-source project. The current release is v0.4.0;
the active development specification is v0.5.0.
v0.1.0 — the repository contract: deterministic task progression, the authoritative STATE.md, verification as a first-class concept.
New v0.5 spec reviews publish schema-2 manifests retaining declared review
rounds and explicitly unverified disposition claims. Decomposition requires
that evidence; schema-1 spec reviews remain readable as history only. See the
reviewed import contract for the boundary.
Roadmap beyond that is tracked in specs/README.md. The
versioned specs in specs/ are the normative source of truth for release scope
and behavior.
Read Next
docs/commands.md — command reference: write effects, the JSON envelope, selection, locks and recovery, slugs, repoint, imports