tix-tracker 0.3.0

A terminal issue tracker: markdown + YAML frontmatter issues with a kanban TUI and CLI
Documentation

tix — a terminal issue tracker

tix is a kanban-style issue tracker that lives entirely in your repository: issues are plain Markdown + YAML frontmatter files. There is no database, no server, and no proprietary format — you get a terminal UI (TUI), a full CLI, and optional GitLab/Linear sync in one Rust binary.

Heavily AI assisted. This project was designed, specified, and built end-to-end with AI agents under a spec-kitty-SPEC style governed workflow (spec → plan → tasks → implement → review → merge). All 6 work packages, 27 functional requirements, and 33 subtasks were implemented and reviewed by AI agents (implementer-ivan, reviewer-renata) steered by a human operator.

  • The human owns the repo and the decisions; the agents wrote the code.
  • Every feature went through a review cycle with real gate checks (cargo test, clippy -D warnings, cargo fmt) before merge.
  • The full mission trail lives in kitty-specs/issue-tracker-tui-01M27PTN/ (spec, plan, tasks, acceptance matrix, review report, retrospective) if you want an audit-grade record of how the software was produced.
  • How Spec Kitty and tix interoperate (.kittify/, missions, merge drivers, task mirroring) is documented in docs/spec-kitty-integration.md.
  • OpenSpec task mirroring and tix init-agents detection output are documented in docs/openspec-integration.md.
  • The MCP surface, including link_issue, lives in docs/mcp.md.
  • tix init-agents itself writes an AI-agent usage section into AGENTS.md, so other agents can operate this tracker autonomously.

Install

The crate is published to crates.io as tix-tracker (the binary is still called tix). See docs/packaging.md for the full maintainer workflow (crates.io account, publishing, binary releases).

cargo install tix-tracker    # build from source via crates.io

# or, with prebuilt binaries (fast, no Rust toolchain needed):
cargo install cargo-binstall --locked   # one-time, if you don't have it
cargo binstall tix-tracker

Local development installs (same binary) work too:

cargo install --path .

Requires a Rust toolchain (edition 2024, MSRV 1.85). The only runtime dependency is your favorite editor for tix edit.

Quickstart

tix init                        # create the default tix.toml (columns, issues_dir)
tix create --title "First issue" --priority high --labels docs
tix status                      # board summary: column -> count
tix list                        # all issues in a table
tix                             # open the kanban TUI

CLI

Command What it does
tix init Create a default tix.toml
tix create New issue (title/body/status/priority/assignee/labels/estimate/links/files)
tix list Table of issues, optional --status filter
tix view <issue> Full issue (frontmatter + body)
tix status Board summary: count per column + total
tix edit <issue> Edit fields via flags, or full file via $EDITOR (--links, --files)
tix move <issue> <column> Move between columns; done records a commit hash
tix link <a> <b> Link two issues symmetrically
tix delete <issue> --yes Remove an issue file
tix export --target gitlab|linear Push local issues to a remote tracker
tix import --target gitlab|linear Pull open issues from a remote tracker
tix init-agents Write/refresh the AI usage section in AGENTS.md

An issue can be referenced by its number, a unique filename fragment, or a unique title fragment.

tix init-agents detects .kittify/ and openspec/ independently and writes the corresponding tracking blocks into AGENTS.md. When it sees them, it also prints the matching detection lines to stdout so scripts can tell which blocks were emitted.

TUI

Launch with tix (no arguments) from the repository root:

  • Arrows / h/l — move between columns, j/k — select issues
  • Enter — view the full issue, n — new issue form
  • e — edit the issue in your $EDITOR
  • d — delete (with confirmation)
  • q / Esc — quit

In dialogs (f filter criteria, n new-issue form, s settings) the Tab / Shift+Tab or ↑ / ↓ keys move between fields/rows.

External sync

tix export/import talks to GitLab through the glab CLI and to Linear through linear-cli. If the tool is missing, tix fails with a clear, actionable error. Repeated exports are idempotent: issues are matched by their gitlab_id / linear_id, and conflicts resolve in favor of the newer updated timestamp.

Storage format

Every issue is a file like docs/issues/2026-09-11-my-title.md:

---
number: 1
title: My issue
status: todo
priority: high
labels: bug, docs
assignee: @alice
created: 2026-09-11
updated: 2026-09-11
---
The body is plain markdown — screenshots and diagrams work as usual.

Human-readable, human-edit-able, git-friendly. No data is locked away.

Configuration

tix.toml (at the repository root) defines the board columns, the issues directory, and optional [export] targets:

columns = ["todo", "in progress", "done", "mismatch"]
issues_dir = "docs/issues"

[export]
tokens = { gitlab = "/path/to/token" }
project = { gitlab = "", linear = "" }

Tokens are never serialized back out after configuration.

Version

Current version: 0.3.0. See CHANGELOG.md.

License

MIT OR Apache-2.0.