tkts 0.1.0

MCP-friendly ticket tracking system with pluggable backends.

tkts

tkts is a comprehensive ticket tracking system with pluggable backends.

It can be backed by Jira, Trello, or other engines, and defaults to a stock on-disk engine. The interface is available over a Python API or an MCP.

Getting Started

1. Install from PyPI: python -m pip install tkts
   • Dev install from this repo: python -m pip install -e .
2. List tickets: tkts (or tkts list)
3. Create a ticket: tkts new "Replace printer toner"
4. Edit a ticket: tkts edit <ticket-id>

By default, tickets are stored in $HOME/.tkts. You can override the root with TKTS_ROOT or a .tkts/config file in your working directory.

CLI

tkts is also available as a command-line program. It accepts verbs, which decide what action is taken.

If a phrase of words is provided that doesn't match a verb, it is interpreted as a todo item and added to the intake list.

verbs

The first argument will be tested as a tkts "verb" and be used choose the action.

todo (or list) is the default verb. It will return your present list of tickets even if no verb is provided. new will take the remainder of the text and create a tkt with that Subject. Use --status to attach a status header (e.g., tkts new "Fix CI flake" --status in-progress). edit will allow interactive editing of the tkt. For the default storage engine, this may shell out to $EDITOR. update will apply structured updates to a ticket (status, subject, body, comments). done marks a ticket complete (sets status to done). show prints a ticket by id (prefixes are accepted if unambiguous). tail prints recent change log entries for a ticket. plan will open a PRD file for refinement until actionable, with --exec to walk tasks. exec runs the agent command with the standard PRD prompt (defaults to codex exec --sandbox workspace-write). tui (or ncurses) launches the ncurses terminal UI. mcp launches an MCP server for Agents to interact with. the --read-only option will prevent writes.

Example: tkts exec (or tkts exec other-agent --flag).

TUI (ncurses)

Launch the terminal UI:

• tkts tui
• tkts tui --watch (auto-refresh every 5s)
• tkts tui --watch 2.5 (auto-refresh every 2.5s)

Key highlights:

• j/k or arrows move selection, Enter opens detail.
• c creates a ticket, e edits the selected ticket.
• / search, f filter, s sort, t group by primary tag.
• w toggles watch mode (auto-refresh), W sets the watch interval.
• Space toggles selection and b applies a bulk status.
• ? shows help.

Environment toggles:

• TKTS_TUI_MONO=1 disables colors for monochrome terminals.

Engines

Selecting a backend

tkts chooses which backend (engine) to use in this order:

1. TKTS_BACKEND environment variable.
2. .tkts/config entry backend=... or tkts_backend=... (searched from your current directory upward).
3. Defaults to local (file-based).

For the file-based backend, you can also override the storage root:

• TKTS_ROOT environment variable, or .tkts/config root=... / tkts_root=....
• Defaults to ~/.tkts.

Examples:

• One-off override: TKTS_BACKEND=trello tkts list

• Project config: create .tkts/config in your repo:

  backend=local
  root=./.tkts-data
  

tkts engine

The default tkts engine is a file-based storage system. It defaults to a root of $HOME/.tkts, but can be configured by in-directory .tkts/config files or the TKTS_ROOT environment variable.

Ticket files are stored in a format that is parsable as the Internet Message Format. It can define Subject, Assignee, and other fields as headers (like in RFC 5322). The body can be used to detail the ticket, including support of multiple documents.

Trello backend

Select Trello as the backend:

• TKTS_BACKEND=trello

Required environment variables:

• TRELLO_API_KEY
• TRELLO_API_TOKEN
• TRELLO_BOARD_ID (board id or shortLink)

Status mapping (MVP):

• Ticket status maps to the Trello list name (case-insensitive).
• By default, lists are expected to be named exactly: todo, in-progress, in-review, blocked, done.
• Override list names with TRELLO_STATUS_TO_LIST (e.g. todo:To Do,in-progress:Doing).

Behavior flags (MVP defaults):

• TRELLO_INCLUDE_DONE=false excludes done cards from tkts list.
• TRELLO_CREATE_MISSING_LABELS=false fails if a requested tag/label doesn’t exist on the board.
• TRELLO_ASSIGNEE_FIELD=username controls whether assignee is Trello username, fullName, or id.
• TRELLO_EDIT_OPENS_BROWSER=false keeps tkts edit as a no-op unless enabled.
• TKTS_TRELLO_LIST filters tkts list to a single Trello list by name.

Examples:

• List: tkts list
• Show: tkts show <shortLink-or-prefix>
• Create: tkts new "Subject" --body "..." --tags feature:trello,area:backend
• Move status: tkts update <id> --status in-progress
• Update labels: tkts update <id> --tags feature:trello,area:docs
• Mark done: tkts done <id>
• Define backend: export TKTS_BACKEND=trello
• List by Trello list name: TKTS_BACKEND=trello TKTS_TRELLO_LIST="Backlog" tkts list

Status

Tickets can include a Status header. Status values are validated on create, with these recommended values:

• todo: use when a ticket is ready to be picked up.
• in-progress: use when work is actively underway.
• in-review: use when work is ready for review.
• blocked: use when a ticket requires human feedback or external input before progressing.
• done: use when a ticket is complete.

Updates

• 2025-09-19: Added a Getting Started section with install + basic CLI usage.
• 2025-09-19: Added multi-document support in ticket parsing/serialization using text/plain MIME parts.
• 2026-04-07: Added model round-trip tests and fixed multi-document attachment handling.