Metadata-Version: 2.3
Name: tkts
Version: 0.1.0
Summary: MCP-friendly ticket tracking system with pluggable backends.
Keywords: tickets,issue-tracker,mcp,cli
Author: trevor grayson
Author-email: trevor grayson <trevor@trevorgrayson.com>
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Operating System :: OS Independent
Requires-Dist: mcp>=0.1.0 ; extra == 'mcp'
Requires-Python: >=3.10
Provides-Extra: mcp
Description-Content-Type: text/markdown

# 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.
