The 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.
tk was written as a full replacement for beads. It shares many similar commands but without the need for keeping a SQLite file in sync or a rogue background daemon mangling your changes. It ships with a migrate-beads command to make this a smooth transition.
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.
Homebrew (macOS/Linux):
brew tap wedow/tools brew install ticket
Arch Linux (AUR):
yay -S ticket # or paru, etc.From source (auto-updates on git pull):
git clone https://github.com/wedow/ticket.git cd ticket && ln -s "$PWD/ticket" ~/.local/bin/tk
Or just copy ticket to somewhere in your PATH.
tk is a portable bash script requiring only coreutils, so it works out of the box on any POSIX system with bash installed. The query command requires jq. Uses rg (ripgrep) if available, falls back to grep.
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 add-note <id> [text] Append timestamped note (or pipe via stdin) super <cmd> [args] Bypass plugins, run built-in command directly Bundled plugins (ticket-extras): edit <id> Open ticket in $EDITOR ls|list [--status=X] [-a X] [-T X] List tickets query [jq-filter] Output tickets as JSON, optionally filtered (requires jq) migrate-beads Import tickets from .beads/issues.jsonl (requires jq) Searches parent directories for .tickets/ (override with TICKETS_DIR env var) Supports partial ID matching (e.g., 'tk show 5c4' matches 'nw-5c46')
Executables named tk-<cmd> or ticket-<cmd> in your PATH are invoked automatically. This allows you to add custom commands or override built-in ones.
# Create a simple plugin cat > ~/.local/bin/tk-hello <<'EOF' #!/bin/bash # tk-plugin: Say hello echo "Hello from plugin!" EOF chmod +x ~/.local/bin/tk-hello # Now it's available tk hello # runs tk-hello tk help # lists it under "Plugins"
Plugin descriptions (shown in tk help):
- Scripts: comment
# tk-plugin: descriptionin first 10 lines - Binaries:
--tk-describeflag outputstk-plugin: description
Plugin environment variables:
TICKETS_DIR- path to the .tickets directory (may be empty)TK_SCRIPT- absolute path to the tk script
Calling built-ins from plugins:
#!/bin/bash # tk-plugin: Custom create with extras id=$("$TK_SCRIPT" super create "$@") echo "Created $id, doing extra stuff..."
Use tk super <cmd> to bypass plugins and run the built-in directly.
The tests are written in the Behavior-Driven Development library behave and require Python.
If you have uv installed simply:
make testtk migrate-beads # review new files if you like git status # check state matches expectations tk ready tk blocked # compare against bd ready bd blocked # all good, let's go git rm -rf .beads git add .tickets git commit -am "ditch beads"
For a thorough system-wide Beads cleanup, see banteg's uninstall script.
MIT