tkt

Track work as markdown files in git. Dependency-aware frontier, atomic push-to-claim, race detection — no server required.

What It Does

tkt manages .tickets/ files with YAML frontmatter inside any git repo. It computes what's ready to work on (the "frontier"), claims tickets atomically via git push, and detects when two people grab the same work.

.tickets/
├── 01-auth-system.md        # status: done
├── 02-api-endpoints.md      # status: open, blocked_by: [01]
└── 03-deploy-pipeline.md    # status: open, blocked_by: [02]

Quick Start

Prerequisites: git on PATH, inside a git repository.

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

# Create the tickets directory
mkdir .tickets && git add .tickets && git commit -m "init tickets"

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

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

# Claim it (marks in_progress, pushes to remote)
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

# 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

# From source
cargo install --path .

Single binary, no runtime dependencies beyond git.

Usage

Frontier — what's ready

tkt ready              # human output
tkt ready --json       # JSON Lines (one object per ticket)

Shows open tickets whose dependencies are all done, filtered by CREW_ENV if set, sorted by priority then ID.

Create tickets

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 allocated atomically — tkt scans local and remote filenames, pushes immediately, and retries on collision.

Lifecycle

tkt claim 03           # open → in_progress (pushed)
tkt close 03 --note "Deployed" --ac 1,2   # → done, checks AC boxes 1 and 2

Note: claim is optional. close works directly on open tickets — useful for single-agent workflows where the push round-trip adds latency without value. Use claim in shared repos to signal WIP and detect races.

Edit and maintain

tkt edit 02 --title "New title" --blocked-by 01,03 --priority high
tkt renumber 05 02     # reassign ID (birth-window only)
tkt validate           # check for cycles, dangling deps, contract violations
tkt validate --strict  # promote warnings to errors
tkt sync-plan --check  # compare ticket status vs docs/plan.md table
tkt query              # dump full corpus as JSON Lines
tkt query --status open --priority high  # filtered view
tkt blocked            # show tickets with unsatisfied deps

Common flags

Ticket Format

---
id: "01"
title: "Implement authentication"
status: open          # backlog | open | in_progress | done
blocked_by: []        # ids that must be done first
priority: high        # optional: jumps frontier order
env: corp             # optional: corp | personal | either
spec: auth-spec       # optional: links to a spec name
---

# Implement authentication

## What to build
...

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

Files are the database. Hand-edit any time — tkt reads what's there.

Design

• Push-to-claim — a pushed commit is a claim; race detection on push rejection
• Remote-aware — scans origin/main via git ls-tree before allocating IDs
• Surgical edits — changes one field without disturbing the rest of the file
• Single binary — shells out to git for full SSH/HTTPS auth compatibility
• Worktree-aware — works from git worktrees (.tickets/ is part of the checked-out tree)

Expected latency

Read commands (ready, query, validate) complete in ~50-100ms. Mutation commands (new, claim, close, edit) take ~2s because they include a git fetch + push round-trip — this is the cost of atomic remote operations and push-to-claim semantics. For local-only workflows, set push.enabled = false in .tickets/config.toml to skip network I/O.

Spike branches

When closing a ticket from a spike/* branch, tkt auto-appends "Spike branch: spike/name" to the resolution. This documents which experimental branch validated the work.

Configuration

Project-level config lives in .tickets/config.toml (committed, shared by contributors):

[push]
enabled = true            # set false for local-only repos (skips fetch/push)

[close]
require_resolution = false  # require --note/--resolution on close
require_checked_acs = false # require all AC boxes checked on close

[validate]
strict = false            # treat warnings as errors by default

[ready]
default_env = ""          # pre-filter frontier (corp/personal)

[new]
default_priority = "medium"  # default priority for new tickets

User-level config at ~/.config/tkt/config.toml stores debug preferences. Manage both with tkt config --list (show all) or tkt config --set push.enabled=false.

Agent Integration

For AI coding agents (kiro-cli, codex, etc.), add this to your project's AGENTS.md:

## Tickets

tkt ready                                         # what to work on next
tkt claim <id>                                    # mark as in_progress (shared repos)
tkt close <id> --check-all --resolution "..."     # mark done
tkt validate --brief                              # check for issues
tkt capabilities                                  # machine-readable feature manifest

Single-agent workflow

tkt ready → close <id> --check-all --resolution "..."

Shared-repo workflow

tkt ready → claim <id> → [work] → close <id> --check-all --resolution "..."

If a claim push is rejected, someone else got there first — pick the next frontier ticket.

Note: claim is optional. close works directly on open tickets — useful for single-agent workflows where the push round-trip adds latency without value. Use claim in shared repos to signal WIP and detect races.

Set CREW_ENV=corp or CREW_ENV=personal to filter the frontier by ticket env field. tkt capabilities outputs a JSON manifest for agent tool discovery.

Development

cargo build            # debug build
cargo test             # all tests
cargo clippy           # must be 0 warnings
cargo fmt --check      # must produce no diff

Telemetry

tkt includes optional, local-only telemetry (disabled by default). No data leaves your machine. See TELEMETRY.md for full details on what's collected, where it's stored, and how to opt in/out.

tkt telemetry --enable   # opt in
tkt telemetry --status   # see what's stored
tkt telemetry --show     # print recent events
tkt telemetry --disable  # opt out
tkt telemetry --clear    # delete all local data

Debug mode

For real-time diagnostics without persisting anything:

TKT_DEBUG=1 tkt ready        # human-readable trace to stderr
TKT_DEBUG=json tkt ready     # JSONL trace to stderr

Contributing

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

Inspired By

tk — proved markdown files + frontmatter is the right model for lightweight work tracking. tkt adds dependency-graph frontier computation, push-to-claim race detection, and surgical frontmatter edits.

License

MIT