Introducing Ticket: A Git‑Backed Issue Tracker for AI Agents

Ticket is a Git‑backed issue tracker built specifically for the workflow of AI agents and developers who rely heavily on version control. Inspired by Joe Armstrong’s “Minimal Viable Program” post, Ticket augments the core concept with advanced quality‑of‑life features for creating, querying, and visualizing complex issue dependency graphs. --- ## Why Ticket? The original Beads tracker that many projects used was functional but required a constantly running background daemon and a SQLite database that had to be kept in sync across environments. Ticket removes those constraints by treating tickets as idempotent, human‑readable Markdown files. Each ticket is stored in the .tickets directory, with a deterministic file name generated from a ticket ID (e.g., nw‑5c46.md). The front‑matter contains all metadata (title, type, priority, status, etc.), while the body can be edited in any text editor. This format lets AI agents scrape relevant information directly from the file system without loading huge JSONL archives into their context windows. The design also aligns with development ergonomics: - **IDE navigation**: In VS Code, a Ctrl/⌘‑click on a ticket ID in the terminal’s git log jumps directly to the Markdown file. - **Partial ID matching**: Commands automatically resolve short ID fragments (e.g., `tk show 5c4` → nw‑5c46). - **Portable CLI**: Ticket is a plain Bash script that only needs coreutils, jq for JSON queries, and ripgrep (or grep) for fast file searching. --- ## Installation ``` # macOS / Linux (Homebrew) brew tap wedow/tools brew install ticket # Arch Linux (AUR) yay -S ticket # From source – updates are delivered via git pull git clone https://github.com/wedow/ticket.git cd ticket && ln -s "$PWD/ticket" ~/.local/bin/tk ``` --- ## Agent Integration Add the following line to your `CLAUDE.md` or `AGENTS.md` to expose the CLI to the model: ``` This project uses a CLI ticket system for task management. Run `tk help` when you need to use it. ``` Claude Opus will pick up the instruction automatically; other models may need explicit guidance. --- ## Core Features Ticket provides a comprehensive set of commands for end‑to‑end ticket lifecycle management: ``` Usage: tk [args] Commands: create [title] [options] Create a ticket, print its ID -d, --description Optional description text --design Design notes --acceptance Acceptance criteria -t, --type Ticket type (bug|feature|task|epic|chore) [default: task] -p, --priority Priority 0‑4, 0 is highest [default: 2] -a, --assignee Assignee (default: git user.name) --external-ref External reference (e.g., gh‑123, JIRA‑456) --parent Parent ticket ID start Set status to in_progress close Set status to closed reopen Set status to open status Update status (open|in_progress|closed) dep Add a dependency dep tree [--full] Show dependency tree (dedup by default) undep Remove a dependency link [id...] Create symmetric links between tickets unlink Remove a link ls [--status=X] List tickets ready List tickets ready for work blocked List tickets blocked by dependencies closed [--limit=N] List recently closed tickets (default 20) show Display full ticket edit Open in $EDITOR add-note [text] Append timestamped note query [jq‑filter] Output tickets as JSON (filtered by jq) migrate-beads Import from an existing Beads JSONL file ``` All commands resolve ticket IDs using a simple pattern match; the `dep` and `link` operations automatically maintain consistency across files. --- ## Migrating From Beads Ticket ships with a `migrate-beads` command that reads the `issues.jsonl` file produced by Beads and produces an equivalent set of Markdown tickets: ```bash $ tk migrate-beads # review the new files $ git status # verify state matches expectations $ tk ready $ tk blocked # compare against the old Beads system $ bd ready $ bd blocked # if all is well, remove Beads $ git rm -rf .beads $ git add .tickets $ git commit -m "ditch beads" ``` For an exhaustive clean‑up—including removal of leftover scripts—see [[banteg's uninstall script]]. --- ## Technical Footnote Ticket is a Bash script that relies only on POSIX coreutils, making it deployable on any system with Bash installed. The `query` command depends on `jq` for JSON output; the search functionality prefers `rg` (ripgrep) for speed but gracefully falls back to `grep` if ripgrep is unavailable. --- ## License Ticket is released under the MIT license. All source code and documentation are freely distributable. --- By leveraging Git as the ultimate source of truth, Ticket allows teams to merge issue tracking into the tools they already use daily, creating a seamless bridge between human and AI workflows.