tk

tk: A Git-Backed Issue Tracker

A minimal CLI ticket management system designed for AI agents. This is a Go port of wedow/ticket.

Quick Demo

Play the full demo: asciinema play https://raw.githubusercontent.com/radutopala/ticket/main/demo.cast

$ tk create "Fix login bug" -t bug -p 1 --tags auth,urgent
tic-a1b2

$ tk list
tic-a1b2 [P1][open] - Fix login bug

$ tk start a1b2
Claimed tic-a1b2 -> in_progress

$ tk add-note a1b2 "Root cause: session timeout"
Added note to tic-a1b2

$ tk close a1b2
Updated tic-a1b2 -> closed

Overview

tk stores issues as markdown files with YAML frontmatter in a .tickets/ directory, enabling easy content searching without bloating context windows. Based on Unix philosophy principles, it provides:

• Dependency tracking with cycle detection
• Atomic claims to prevent race conditions
• Partial ID matching for quick access
• Git-native version control for all ticket data

Installation

Homebrew (macOS/Linux)

brew install radutopala/tap/tk

Go Install

Requires Go 1.25+:

go install github.com/radutopala/ticket/cmd/tk@latest

From Source

git clone https://github.com/radutopala/ticket.git
cd ticket
make install

Both Go methods install tk to your $GOPATH/bin.

Build Locally

make build
./bin/tk --help

Requirements

• Go 1.25+ (for building)
• jq (optional, for the query command filtering)
• $EDITOR environment variable (for the edit command)

Agent Integration

Claude Code Setup

Add to your project's CLAUDE.md:

This project uses `tk` for ticket management. Run `tk` to see available commands.

Workflow:
- Use `tk ready` to find tickets ready to work on
- Use `tk start <id>` to claim a ticket before working on it
- Use `tk add-note <id> "progress update"` to document progress
- Use `tk close <id>` when complete

Optionally, add to .claude/settings.local.json to allow ticket commands:

{
  "permissions": {
    "allow": [
      "Bash(tk *)"
    ]
  }
}

Other AI Agents

Add to your AGENTS.md or system prompt:

This project uses a CLI ticket system. Run `tk` for help. Key commands:
- tk ready          List tickets ready to work on
- tk start <id>     Claim a ticket
- tk show <id>      View ticket details
- tk close <id>     Mark complete

Claude Code Plugin

Install tk as a Claude Code plugin for the /tk skill:

# Add the marketplace
/plugin marketplace add radutopala/ticket

# Install the plugin
/plugin install tk

Then use /tk to get a comprehensive command reference and workflow guide.

Command Reference

Core Operations

Command	Description
create [title]	Create a new ticket (outputs ID)
show <id>	Display ticket details
edit <id>	Open ticket in $EDITOR
start <id>	Mark as in_progress
close <id>	Mark as closed
reopen <id>	Revert to open status
status <id> <status>	Update status (open|in_progress|closed)

Create Options

tk create "My ticket title" \
  -d "Description text" \
  --design "Design notes" \
  --acceptance "Acceptance criteria" \
  -t feature \           # bug|feature|task|epic|chore (default: task)
  -p 1 \                 # Priority 0-4, 0=highest (default: 2)
  -a "John Doe" \        # Assignee (defaults to git user.name)
  --external-ref gh-123 \# External reference (e.g., JIRA-456)
  --parent tic-abc1 \    # Parent ticket ID
  --tags backend,urgent  # Comma-separated tags

Dependency Management

Command	Description
dep add <id> <dep-id>	Add dependency (id depends on dep-id)
dep remove <id> <dep-id>	Remove dependency
dep tree [id]	Display dependency hierarchy
dep tree --full	Show full tree for all tickets
dep check	Identify circular dependencies
undep <id> <dep-id>	Alias for dep remove

Linking

Command	Description
link <id> <id> [id...]	Create symmetric links between tickets
unlink <id> <target-id>	Remove link between tickets

Listing & Filtering

Command	Description
list / ls	List all tickets
ready	Open/in_progress tickets with resolved deps
blocked	Open/in_progress tickets with unresolved deps
closed	Recently closed tickets