Metadata-Version: 2.3
Name: tkts
Version: 0.1.1
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

CLI & MCP-friendly ticket tracking system to orchestrate both humans and agents. Pluggable backends
for your favorite ticketing system, or use the uncompromising local cache.

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.

## AGENTS.md

!!!BEWARE!!! If AGENTS.md is in your project's root, or you include it -- your project will complete itself.  This iterative Agent direction, instructs updates into the tkts mcp, and agents iterate until the work is done.

## CLI

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

You will be a more effective engineer with a work tracking system.  Agents will get a lot of work done more quickly, with work which is broken down into tkts.  You may modify, or `tkts --watch` work get done in real time.


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.
