A lightweight, git-backed ticket tracker that stores tickets as Markdown files in your repository. No external services, no databases—just files that version with your code.
# Cargo
cargo install --path .
# Nix
nix profile install github:benburk/ticket#tktk init # Create .tickets/ directory
echo "# Fix login bug" | tk create # Create a ticket from stdin
tk list # See all tickets
tk -C ../another-repo ready # Read another repo without cd
tk ready # See what's ready to work on
tk close tk-a1b2 # Close a ticket- Git-native storage — Each ticket is a Markdown file in
.tickets/, making diffs readable and merges easy - Dependency tracking — Model blocking relationships with
tk depand see what's actionable withtk ready - Tags — Organize tickets with
--tags backend,urgentand filter with--tag backend - Unix-friendly — Ticket-returning commands support
--jsonfor piping tojqand other tools - Offline-first — No server, no sync, no account; tickets live in your repo
- Prefix matching — Reference
tk-a1b2c3d4as justtk-a1when unambiguous
tk [OPTIONS] <COMMAND>
Commands:
init Initialize ticket tracking in current directory
create Create a new ticket from stdin (expects "# Title" on first line)
list List tickets
show Show a ticket
edit Replace ticket title + body from stdin (expects "# Title" on first line)
status Change ticket status
close Close a ticket
reopen Reopen a ticket
dep Add a blocking dependency
undep Remove a blocking dependency
ready List tickets ready to work on (open, no unresolved deps)
blocked List blocked tickets (open, has unresolved deps)
dep-cycle Detect dependency cycles
tree Show dependency tree (all tickets if no ID given)
note Add a timestamped note to a ticket
query Query tickets as JSON (pipe to jq)
help Print this message or the help of the given subcommand(s)
Options:
-C, --directory <PATH> Run as if started in this directory
--json Output in JSON format
-h, --help Print help
-V, --version Print version
Run tk <command> --help for command-specific options. Read commands fail when .tickets/ is absent; only tk init creates it. tk --json show <id> includes the Markdown body and every timestamp.
---
id: tk-a1b2
status: open
created: 2024-01-15T10:30:00Z
deps:
- tk-c3d4
tags:
- backend
---
# Implement user authentication
Add JWT-based auth with refresh tokens.
[2024-01-15 10:45 alice] Started research on JWT libraries
[2024-01-15 14:30 alice] Going with jsonwebtoken crateThe package exports the same parser and store used by tk:
use ticket::Store;
let store = Store::open("/path/to/repo");
let tickets = store.load_all()?;
let ticket = store.create("Fix login".into(), String::new(), vec!["auth".into()])?;
store.close(ticket.id())?;The library owns ticket files and dependency rules. It does not run Git or manage branches, worktrees, agents, or CI.
See PHILOSOPHY.md for the design rationale and recommended git workflow.
