ticketry

A git-native ticket tracker where tickets are Markdown files with YAML frontmatter, committed alongside your code. A local SQLite index enables fast queries across branches without any server or external service.

Full documentation: docs/README.md

Features

• Tickets live in git — diffs, blame, history, and branching all work out of the box
• Branch-aware — tickets on feature/auth don't pollute main's list
• Fast local index — SQLite powers filtered queries and dependency graphs
• Kanban board and TUI built in
• Thread Mode — multi-agent conversations backed by git blame, not signatures
• MCP server — expose your ticket tracker to AI coding agents
• ticketry commits — trace which commits belong to a ticket, with a colour-coded git graph showing merged vs. unmerged work
• ticketry thread show — read agent-to-agent design conversations attributed by git author, directly in your terminal
• Fully offline — everything runs locally against your files and git. The only command that touches the network is ticketry update, and only when you run it yourself: there is no background version check or telemetry

Install

macOS / Linux:

curl -fsSL https://raw.githubusercontent.com/LoumTechnologies/ticketry/master/install.sh | bash

Windows (PowerShell):

irm https://raw.githubusercontent.com/LoumTechnologies/ticketry/master/install.ps1 | iex

From source (needs a Rust toolchain):

cargo install --git https://github.com/LoumTechnologies/ticketry ticketry-cli ticketry-mcp

Both ticketry (CLI) and ticketry-mcp (MCP server) are installed to ~/.local/bin by default (%LOCALAPPDATA%\Programs\ticketry on Windows). Every download is verified against the release's SHA256SUMS.

curl -fsSL https://raw.githubusercontent.com/LoumTechnologies/ticketry/master/install.sh | INSTALL_DIR=/usr/local/bin bash

Supported platforms: Linux (x86_64, aarch64), macOS (Intel, Apple Silicon), and Windows (x86_64; ARM64 runs it under emulation).

PATH note: if ~/.local/bin is not on your PATH, add it:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc  # or ~/.bashrc

Verify it worked:

ticketry --version

Updating

ticketry update           # install the latest release
ticketry update --check   # just report whether one is available

update replaces both ticketry and ticketry-mcp in place, verifying each download against the release's SHA256SUMS first — a failed check leaves your existing install untouched. --tag v0.2.0 pins a specific release (including downgrades) and --dry-run downloads and verifies without writing anything.

Ticketry never checks for updates on its own. It only talks to the network when you run ticketry update yourself, so the offline guarantee above still holds. If you installed with cargo install, re-run that instead.

AI coding agents in the cloud

A cloud coding session (Claude Code on the web, CI, any fresh container) clones your repo but not the binary, so ticketry list fails until something installs it. ticketry init offers to set up a Claude Code SessionStart hook that does it for you:

ticketry init                  # prompts when run interactively
ticketry init --session-hook   # install it without prompting
ticketry init --no-session-hook

It writes .claude/hooks/session-start.sh and registers it in .claude/settings.json — commit both so everyone's sessions pick it up. The hook installs ticketry, runs init and index, and persists PATH for the session. It only runs in remote sessions (CLAUDE_CODE_REMOTE), so it never touches the toolchain on your own machine, and it exits cleanly if the install fails rather than blocking session startup.

If .claude/ is gitignored, the hook can't reach anyone else's session — git cannot re-include a file inside an ignored directory. init warns when it detects this; narrow the rule to .claude/settings.local.json instead.

Agents that read AGENTS.md also get manual install instructions from the generated .instructions/ticketry.md, so the hook is a convenience, not a requirement.

Quick start

cd your-project
git init          # if not already a git repo
ticketry init

ticketry new "Add user authentication"
ticketry new "Email notification service"
ticketry list

Core commands

ticketry new "title"                       create a ticket
ticketry list                              list all tickets
ticketry list --status todo                filter by status
ticketry list next                         unblocked tickets only
ticketry list blocked                      tickets waiting on deps
ticketry board                             kanban view
ticketry show <slug-or-id>                 show a ticket
ticketry status <slug> in-progress         update status
ticketry commits <slug>                    trace commits for a ticket
ticketry thread <slug> show                read the conversation
ticketry thread <slug> history             view pre-refactor thread
ticketry update                            install the latest release

Append --help to any command for full flag reference.

ticketry commits

Traces every commit that mentions a ticket slug or UUID in its message, or touches the ticket file directly. The output overlays a git graph so you can see at a glance which work is merged and what's still on a feature branch.

• Blue * — commit is merged into the mainline
• Red * — commit is on an unmerged branch
• Ticket slugs are highlighted in the commit subject
• Unrelated commits between matches are collapsed to ... (N unrelated commits)
• Branch labels show how many commits haven't landed yet

ticketry commits task-1
ticketry commits task-1 task-3   # multiple tickets at once
ticketry commits task-1 --plain  # machine-readable output for scripts

ticketry thread

Thread Mode turns ticket bodies into a multi-voice conversation backed by git blame. Each participant edits the ticket file directly and commits with their identity. No signatures or special syntax — git blame is the attribution layer.

• Solid bar │ — another participant's words
• Dotted bar ┊ — your own words (dimmed)
• Timestamps and commit hashes anchor each utterance to a specific commit
• → needs your response flags when the assignee has unanswered messages

# View the conversation
ticketry thread task-2 show

# See how the thread evolved over time (pre-refactor snapshots)
ticketry thread task-2 history

# Participate: edit the ticket file, then commit with your identity
export GIT_AUTHOR_NAME="Opus (PM)"
export GIT_AUTHOR_EMAIL="opus@yourproject.com"
git add work/task-2.task.md
git commit -m "task-2: thread reply"

MCP server

ticketry-mcp exposes your ticket tracker to AI coding agents (Claude, Cursor, etc.) via the Model Context Protocol.

ticketry mcp-setup     # interactive setup for Claude Desktop / Claude Code

Or add manually to your claude_desktop_config.json:

{
  "mcpServers": {
    "ticketry": { "command": "/path/to/ticketry-mcp" }
  }
}

See docs/mcp-setup.md for full configuration details.

Ticket format

Tickets are plain Markdown files with YAML frontmatter. Any extra frontmatter fields survive round-trips and are queryable with -f key=value:

---
id: 3f2c1a4b-...
slug: task-7
status: in-progress
title: Add rate limiting
assignee: nate
priority: high
effort: 3
labels: [backend, security]
depends_on: [task-5]
---

Implement token-bucket rate limiting on the login endpoint.
Max 5 attempts per minute per IP, 429 response on breach.

ticketry list -f "effort<=3" -f "priority=high"
ticketry list -S -priority          # sort by priority descending
ticketry list -c slug,title,effort  # custom columns

License

BSD 2-Clause. See LICENSE.