tkt

Track tasks as markdown files in your git repo.

What It Does

One markdown file per task, with status and dependencies in the header. tkt tells you what's ready to work on next.

.tickets/
├── 01-auth-system.md        # done
├── 02-api-endpoints.md      # open, waiting on 01
└── 03-deploy-pipeline.md    # open, waiting on 02

Quick Start

You need: git installed, inside a git repo.

# Install
curl -fsSL https://github.com/smileynet/tkt/releases/latest/download/tkt-installer.sh | sh

# Set up your tickets directory
mkdir .tickets && git add .tickets && git commit -m "init tickets"

# Create your first task
tkt new auth-system --title "Implement authentication"
# → ✓ created 01 auth-system (pushed)

# See what's ready
tkt ready
# → Ready (1):
# →   01  Implement authentication

# Claim it (marks in-progress, tells others it's taken)
tkt claim 01
# → ✓ claimed 01 auth-system (→ in_progress)

# Close it when done
tkt close 01 --note "JWT + refresh tokens shipped"
# → ✓ closed 01 auth-system (Resolution written)

Install

Pre-built binaries (fastest):

# macOS / Linux
curl -fsSL https://github.com/smileynet/tkt/releases/latest/download/tkt-installer.sh | sh

# Windows (PowerShell)
irm https://github.com/smileynet/tkt/releases/latest/download/tkt-installer.ps1 | iex

From crates.io:

cargo install tkt

# Or with cargo-binstall (downloads pre-built binary, no compile)
cargo binstall tkt

From source:

cargo install --path .

Single binary, no runtime dependencies beyond git.

Usage

See what's ready

tkt ready              # human-friendly list
tkt ready --json       # machine-readable (JSON Lines)

Shows tasks that are open and have all their dependencies done, sorted by priority.

Create tasks

tkt new fix-login --title "Fix login timeout" --priority high
tkt new deploy --title "Deploy to staging" --blocked-by 01,02
tkt batch "api:Build API" "docs:Write docs" --blocked-by 01

IDs are assigned automatically. In shared repos, tkt checks both local and remote files to avoid collisions.

Work on tasks

tkt claim 03           # mark as in-progress (visible to others)
tkt close 03 --note "Deployed" --ac 1,2   # mark done, check acceptance criteria

claim is optional — close works directly on open tasks. Use claim in shared repos so others know what you're working on.

Edit and maintain

tkt edit 02 --title "New title" --blocked-by 01,03 --priority high
tkt validate           # check for cycles, broken references, contract issues
tkt validate --fix     # auto-repair fixable problems
tkt lint               # normalize frontmatter style (quoting, field order)
tkt lint --check       # CI mode: exit 1 if anything needs fixing
tkt doctor             # health check for current project
tkt doctor ~/code      # scan all projects, flag non-tkt repos
tkt sync-plan --check  # compare ticket status vs a plan document
tkt query              # dump everything as JSON Lines
tkt blocked            # show tasks stuck waiting on dependencies

Flags reference

Task Format

---
id: "01"
title: "Implement authentication"
status: open          # backlog | open | in_progress | done
blocked_by: []        # IDs that must be done first
priority: high        # optional: urgent > high > medium > low
---

# Implement authentication

## What to build
JWT-based auth with refresh token rotation...

## Acceptance criteria
- [ ] JWT tokens issued on login
- [ ] Refresh token rotation works

Tasks are just files. Edit them by hand anytime — tkt reads whatever's there.

Configuration

Project config in .tickets/config.toml (committed with your repo):

[push]
enabled = true            # false for local-only repos (no network calls)

[close]
require_resolution = false  # require a --note when closing
require_checked_acs = true  # require all acceptance criteria checked (default: true)
require_validation_criteria = false  # require validation_criteria field
require_validation_evidence = "warn"  # "true" | "warn" | "false"
allow_force = true          # false to disable --force escape hatch

[validate]
strict = false            # treat warnings as errors

[ready]
default_env = ""          # filter tasks by environment

[new]
default_priority = "medium"

Manage with tkt config --list or tkt config --set push.enabled=false.

User config (~/.config/tkt/config.toml) provides global defaults; project config overrides per-repo. See tkt config --show for resolved values with sources.

How It Works

• Tasks that depend on other tasks won't show up in tkt ready until those dependencies are done
• When you create or claim a task, tkt pushes immediately — if someone else pushed first, it retries with a new ID
• Edits only touch the specific field you changed, leaving everything else untouched
• All reads are local and fast (~50ms). Writes include a git push round-trip (~2s) — disable with push.enabled = false for local-only workflows

AI Agent Integration

tkt works well with AI coding agents. Add to your AGENTS.md:

## Tasks

tkt ready                                         # what to work on next
tkt claim <id>                                    # mark as in-progress
tkt close <id> --check-all --resolution "..."     # mark done
tkt validate --brief                              # check for problems

Solo workflow: tkt ready → pick one → tkt close <id> --check-all --resolution "...".

Multi-agent workflow: tkt ready → tkt claim <id> → work → tkt close <id>.

Development

If you've cloned this repo, you're a maintainer. Regular users install from crates.io or pre-built binaries.

# Build and deploy to PATH (run after pulling or making changes)
cargo build --release && cargo install --path . && bash tools/deploy-skills.sh

# Verify
tkt --version          # shows version + git hash, e.g. "tkt 0.1.0 (ea047fb)"

# Gate (run before every commit)
cargo fmt && cargo clippy --all-targets && cargo test

Telemetry

Optional, local-only telemetry (disabled by default). Nothing leaves your machine. See TELEMETRY.md.

tkt telemetry --enable   # opt in
tkt telemetry --status   # check what's stored
tkt telemetry --disable  # opt out

Contributing

Found a bug? File a report. Want a feature? Request it.

License

MIT