# 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`](docs/spec-kitty-integration.md).
> - OpenSpec task mirroring and `tix init-agents` detection output are
> documented in [`docs/openspec-integration.md`](docs/openspec-integration.md).
> - The MCP surface, including `link_issue`, lives in [`docs/mcp.md`](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](docs/packaging.md) for the full
maintainer workflow (crates.io account, publishing, binary releases).
```bash
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:
```bash
cargo install --path .
```
Requires a Rust toolchain (edition 2024, MSRV 1.85). The only runtime
dependency is your favorite editor for `tix edit`.
## Quickstart
```bash
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
| `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`:
```markdown
---
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:
```toml
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](CHANGELOG.md).
## License
MIT OR Apache-2.0.