A git-backed issue tracker for AI agents. Rooted in the Unix Philosophy, tk is inspired by Joe Armstrong's Minimal Viable Program with additional quality of life features for managing and querying against complex issue dependency graphs.
This is a Go port of the original bash implementation.
Tickets are markdown files with YAML frontmatter in .tickets/. This allows AI agents to easily search them for relevant content without dumping ten thousand character JSONL lines into their context window.
Using ticket IDs as file names also allows IDEs to quickly navigate to the ticket for you. For example, you might run git log in your terminal and see something like:
nw-5c46: add SSE connection management
VS Code allows you to Ctrl+Click or Cmd+Click the ID and jump directly to the file to read the details.
From source:
go install github.com/kardianos/ticket/cmd/tk@latestGo 1.24 or later.
Add this line to your CLAUDE.md or AGENTS.md:
This project uses a CLI ticket system for task management. Run `tk help` when you need to use it.
Claude Opus picks it up naturally from there. Other models may need additional guidance.
tk - minimal ticket system with dependency tracking
Usage: tk <command> [args]
Commands:
create [title] [options] Create ticket, prints ID
-d, --description Description text
--design Design notes
--acceptance Acceptance criteria
-t, --type Type (bug|feature|task|epic|chore) [default: task]
-p, --priority Priority 0-4, 0=highest [default: 2]
-a, --assignee Assignee [default: git user.name]
--external-ref External reference (e.g., gh-123, JIRA-456)
--parent Parent ticket ID
--tags Comma-separated tags (e.g., --tags ui,backend,urgent)
start <id> Set status to in_progress
close <id> Set status to closed
reopen <id> Set status to open
status <id> <status> Update status (open|in_progress|closed)
dep <id> <dep-id> Add dependency (id depends on dep-id)
dep tree [--full] <id> Show dependency tree (--full disables dedup)
dep cycle Find dependency cycles in open tickets
undep <id> <dep-id> Remove dependency
link <id> <id> [id...] Link tickets together (symmetric)
unlink <id> <target-id> Remove link between tickets
ls|list [--status=X] [-a X] [-T X] List tickets
ready [-a X] [-T X] List open/in-progress tickets with deps resolved
blocked [-a X] [-T X] List open/in-progress tickets with unresolved deps
closed [--limit=N] [-a X] [-T X] List recently closed tickets (default 20, by mtime)
show <id> Display ticket
edit <id> Open ticket in $EDITOR
add-note <id> [text] Append timestamped note (or pipe via stdin)
query [filter] Output tickets as JSON (filter: status=open, priority<2, or jq expr)
Searches parent directories for .tickets/ (override with TICKETS_DIR env var)
Supports partial ID matching (e.g., 'tk show 5c4' matches 'nw-5c46')The primary implementation and test suite are in Go:
go test ./...This runs 114 test cases in cmd/tk/main_test.go covering all commands.
The repository also contains:
ticket- Original bash implementation (~900 lines)features/- Python BDD tests using behave (112 scenarios)
MIT