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, each passing real gate checks (cargo test, clippy -D warnings, cargo fmt) before merge. The mission trail lives in kitty-specs/issue-tracker-tui-01M27PTN/; the integration surfaces are documented in docs/spec-kitty-integration.md, docs/openspec-integration.md and docs/mcp.md. tix init-agents 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 list --columns title,status # choose and order displayed columns
tix                             # open the kanban TUI

CLI

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

tix init-agents detects .kittify/, openspec/ and .specify/ 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; tix new starts the same session with the create-issue form already open. The complete, configurable key reference is docs/key-bindings.md; the list here is only a default overview.

Six top-level modes share one shell with a vertical navigation tree on the left (clickable limbs per board, cycle, milestone and template). A mode's function key switches to it only when the active mode does not bind that key itself, so F2 inside a form is still the picker.

Board highlights: arrows and h/j/k navigate, PgUp/PgDn page a column, Enter opens an issue, n/F1 creates, Shift+C clones, u toggles the sub-issue tree, e edits in $EDITOR, v views read-only, d deletes, m manages cycles and milestones, / searches the live board, ? opens searchable help, q/Esc quits. In the issue detail view, n/E/d add, re-kind and remove typed relationships, and Shift+P sets, changes or clears the parent — all through the same service the CLI and MCP use, so a relationship created in the TUI is byte-identical to one created with tix link.

The TUI is mouse-aware (click, double-click, drag, right-click, scroll, hover) and never sacrifices keyboard operation. Editor round trips are conflict-safe: a file changed by another writer is never clobbered by a stray keypress — see the edit-conflict and edit-repair modals.

Storage format

Issues are files under docs/issues/… with YAML frontmatter and a Markdown body. tix re-renders the frontmatter in its own style on write (custom keys are preserved, ## History verbatim), and the layout, related_issues, and custom frontmatter keys are all configurable. See storage format.

Relationships and parents

Four typed relationship kinds (blocks, blocked_by, duplicates, related) replace the retired links: key; only blocks drives the blocked-move guard. An issue has at most one parent — a decomposition tree, not an ordering edge. See relationships and parent issues.

Batch editing

tix bulk edit|link|unlink over a selection: preview is the default, --apply writes, and each item reports its own outcome with no rollback. See batch editing.

Archiving

tix archive/tix restore dot-prefix an issue's filename to hide it from the default views without deleting it; the number is never recycled. See archiving.

Workflow status categories

Map board columns onto the global six-word vocabulary (backlog … canceled). Declaring a category_map opts the board into the transition policy; an unmapped column falls back to unstarted. See workflow status categories.

Triage inbox

An opt-in inbox, declared by a [triage] section in tix.toml, holds unreviewed work before it joins the normal workflow. Every decision is one History event, and the CLI, the TUI (F2) and MCP read one snapshot through the same service. See triage and the design reference docs/triage.md.

External sync

tix export/import targets GitLab (through glab) and Linear (through linear-cli), plus a local tix import --target speckit. Repeated runs are idempotent. See external sync.

Configuration

tix.toml holds the issues directory, [export] targets, keybindings and legacy tables; boards live in docs/boards/<name>.md. The full key reference is in configuration, the TUI editing surface in config mode, and the metadata stores in navigation.

Documentation

Beyond the guides linked above, docs/for-users/ also holds navigation (mode shell and metadata stores), new issue, cycles and config mode, plus key bindings and MCP.

Version

Current version: 0.7.0. See CHANGELOG.md.

License

MIT OR Apache-2.0.