tk — Agent Ticket Management CLI

tk tracks feature work as plain markdown files, one ticket per file, edited in place. It indexes, queues, and locates tickets; the filesystem is the editor.

The implementation is the source of truth.

macOS and Linux only. Windows is not supported — there is no flock or path substitute, and tk fails with a clear startup error on an unsupported OS rather than half-running. This is a deliberate v1 scope limit.

brew tap p3bot/tap
brew trust p3bot/tap
brew install p3bot/tap/tk

go install github.com/p3bot/tk/cmd/tk@latest

go build ./...
go build -o tk ./cmd/tk

Requires Go 1.26. Pure Go, no cgo. The external git binary is used only to derive a code-root / git-root; it is shelled out, never linked.

A scope is a directory of ticket markdown files plus its tk.cue (the scope's name, auto-commit mode, and schema). Scopes are registered per machine in the XDG config directory (${XDG_CONFIG_HOME:-~/.config}/tk/).

tk scope init <dir> (--name <name> | --auto-name) [--code-root <path>] [--auto-commit]
tk scope import <dir> [--code-root <path>]
tk scope rebind <dir> --name <name> [--code-root <path>]
tk scope forget <name>
tk scope list          # bare `tk scope` and `tk scopes` also run list

• init creates and registers a new scope, writing a minimal tk.cue and a .gitignore covering .tk.lock. Exactly one of --name / --auto-name is required. In a dedicated tk repo, pass --auto-commit (omitting it registers repo-driven).
• import registers an existing on-disk scope, files in place; its name and auto-commit mode come from the on-disk tk.cue.
• rebind rewrites a registered scope's paths after a move or clone.
• forget unregisters a scope (registry and lens entries only); it never touches the scope's files.
• list prints parse-stable TSV, one line per scope: name\tdir\troot\tmode, where mode is tk-driven, repo-driven, plain-files, or unknown.

• stdout is a path or closed TSV; diagnostics and closed tokens go to stderr.
• Exit 0 success; 2 for usage / bad CLI input; other failures are generic non-zero. There is no --json and no colour on stdout. NO_COLOR suppresses all ANSI.