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

The command is tisket, whichever package you install.

Archives of precompiled binaries are available for macOS and Linux. The Linux binaries are static executables. Each archive holds the binary, its man pages, the README and the licence. There is no Windows build.

Package manager	Package	Command
Homebrew	cjohnhanson/tap/tisket	brew install cjohnhanson/tap/tisket
Cargo	tisket	cargo install --locked tisket
uv	tisket	uv tool install tisket
npm	tisket	npm install -g tisket

On Debian or Ubuntu, download the .deb from the releases page and install it:

wget https://github.com/cjohnhanson/tisket/releases/download/v0.2.4/tisket_0.2.4-1_amd64.deb
sudo dpkg -i tisket_0.2.4-1_amd64.deb

To run it once without installing anything:

uvx tisket issue list
npx tisket issue list

Building

tisket is written in Rust, so you need a Rust installation to compile it. tisket compiles with Rust 1.88 or newer. A C compiler is needed as well, which aws-lc-sys uses for its cryptography.

To build tisket:

git clone https://github.com/cjohnhanson/tisket
cd tisket
cargo build --release
./target/release/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.