tisket

A plaintext, git-tracked issue tracker. Each issue is a markdown file with YAML frontmatter. The files live in .tisket/ inside your git repo. Tisket needs no external service and no API tokens. It works offline. Coding agents read and write issues as ordinary file operations instead of calls to a hosted API.

Install

cargo install --locked tisket
brew install cjohnhanson/tap/tisket
uv tool install tisket
npm install -g tisket

cargo install builds from source. It needs Rust 1.88 and a C compiler. The other three carry a prebuilt binary for macOS and Linux, x86-64 and arm64, published by a tagged release.

To build the unreleased main branch:

cargo install --locked --git https://github.com/cjohnhanson/tisket

Or run it without installing:

uvx tisket issue list
npx tisket issue list

A release also carries prebuilt archives and a .deb, on the releases page. Each archive holds the binary and the man page. Install a .deb with dpkg -i: it is a file, not a repository, so apt-get install does not reach it.

Check the install with tisket --version.

Usage

tisket init                           # set up .tisket/ in a git repo
tisket issue create "Fix the thing"   # create an issue
tisket issue list                     # list open issues
tisket issue list -s todo             # filter by status
tisket issue show ab12                # show the issue details
tisket issue edit ab12 --add-label urgent
tisket issue close ab12               # move the file to .closed/
tisket search "TLS|certificates"      # search every issue with a regex
tisket store list                     # show this tracker and the trackers it declares
tisket serve [--bind ADDR]            # serve this tracker over MCP
tisket docs [topic]                   # show the bundled documentation

How it works

Each issue is one file. The filename has a 4-character random prefix and a slug from the title. The file holds YAML frontmatter for the metadata and a markdown body. Tisket moves a closed issue to .closed/.

.tisket/
  default/                           # project directory
    ab12-fix-the-widget.md           # open issue
    .closed/
      cd34-old-resolved-thing.md     # closed issue

An issue moves through a status lifecycle: discovery → todo → in_progress → done (or cancelled). An issue can also be blocked or paused.

Scratch notes

Each issue can have a ## Scratch Notes section below the issue body. An agent appends its working notes there: investigation logs, approaches that failed, and partial findings. The problem description above stays unchanged.

tisket scratch ab12 append "Confirmed: bounds check missing on line 42"
tisket scratch ab12 read

Git-aware divergence detection

When you list or show an issue, tisket also reads that issue file from every other branch. It compares the files field by field. If another branch has a different status, assignee, or priority, tisket marks the issue with a *. It also names each branch that differs. You see the conflict before a merge overwrites one version.

Serving over MCP

tisket serve offers the same tracker to a Model Context Protocol client. The library answers both interfaces, so the server returns what the CLI returns.

tisket serve                        # speak MCP on stdin and stdout
tisket serve --bind 127.0.0.1:7432  # serve over HTTP at /mcp on that address
tisket serve --access read-write    # also allow appending to working notes

The server is read-only by default. With --access read-write it adds one write: appending to an issue's scratch notes. A caller cannot create an issue, change a status, or edit a body through the server. A served tracker has no authentication: bind it to 127.0.0.1, or put a proxy that authenticates in front of it.

Documentation

• What is Tisket? — design, file format, status lifecycle
• Getting Started — first issue walkthrough
• Workflow — daily issue management past the basics
• CLI Reference — complete command documentation

tisket docs prints the same pages from the installed binary.

Related

Tisket belongs to a group of plaintext, git-tracked, agent-readable tools.

• zettel — zettelkasten notes for a repository
• almanac — agent skill index, over pluggable sources
• gaff — context-lifecycle handler for coding agents
• missouri — end-to-end tests as directed graphs of filesystem states
• mdstore — the frontmattered markdown library tisket stores issues with

License

MIT.