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.
• 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

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

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

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.1.0. See CHANGELOG.md.

License

MIT OR Apache-2.0.