tix

A ticket board that lives in a folder. Tickets are Markdown files with YAML frontmatter, the schema is one tix.yaml, and there is no server, database or login. Built to be driven by people and AI agents alike.

my-board/
  tix.yaml                                  # statuses and fields
  tickets/01K5AQ9Z3R7M8N2P4Q6S8T0V1W/
    ticket.md                               # frontmatter + brief

Install

macOS / Linux

curl -fsSL https://raw.githubusercontent.com/alexbruf/tix/main/install.sh | sh

Installs the latest release to ~/.local/bin/tix. Set TIX_INSTALL_DIR to choose another folder.

Windows: download tix-x86_64-pc-windows-msvc.zip (or tix-aarch64-pc-windows-msvc.zip on ARM) from Releases, unzip, and put tix.exe on your PATH.

Prebuilt binaries on every release:

| Platform | x86-64 | ARM64 | |---|---|---| | macOS | tix-x86_64-apple-darwin.tar.gz | tix-aarch64-apple-darwin.tar.gz | | Linux (static musl) | tix-x86_64-unknown-linux-musl.tar.gz | tix-aarch64-unknown-linux-musl.tar.gz | | Windows | tix-x86_64-pc-windows-msvc.zip | tix-aarch64-pc-windows-msvc.zip | | Any WASI runtime | tix.wasm | |

SHA256SUMS lists checksums for all of them.

With Node 18+ (no install; same commands, runs the WebAssembly build)

npx @viewengine/tix --help

With Rust

cargo install --git https://github.com/alexbruf/tix tix-cli

WASI: tix.wasm from Releases runs anywhere with a WASI runtime:

wasmtime run --dir=. tix.wasm board

Check it works:

tix --version

Quick start

mkdir my-board && cd my-board
tix init
tix new --title "Q4 comparison article" --client acme --type article
tix ls
tix mv 01K5 in_progress               # any unique id prefix of 4+ characters
tix attach 01K5 https://docs.google.com/document/d/abc --label draft
tix board

Every command has detailed help with argument formats, output, JSON shapes and examples:

tix --help
tix new --help        # inside a board: lists its fields and allowed values

Use with AI agents

tix is designed to be scripted: --no-prompt never waits on stdin, --json prints one JSON document, errors go to stderr, and exit codes are stable (0 ok, 1 validation, 2 usage, 3 I/O).

MCP server: the tix binary is also a local MCP server. Every command becomes a tool (tix_new, tix_ls, tix_set, ...) that returns the command's JSON or an error naming the broken rule.

claude mcp add tix -- tix mcp                       # Claude Code, installed binary
claude mcp add tix -- npx -y @viewengine/tix mcp    # Claude Code, via npm (Node 18+)

Other clients (Claude Desktop, Cursor, ...):

{ "mcpServers": { "tix": { "command": "npx", "args": ["-y", "@viewengine/tix", "mcp", "--workspace", "/path/to/board"] } } }

Tools take an optional workspace path; --workspace sets the default (otherwise the server's working directory). See tix mcp --help.

Claude Code skill: teaches agents how to use tix well (CLI or MCP).

mkdir -p ~/.claude/skills/tix
curl -fsSL https://raw.githubusercontent.com/alexbruf/tix/main/skills/tix/SKILL.md -o ~/.claude/skills/tix/SKILL.md

Commands

| Command | What it does | |---|---| | tix init | Create tix.yaml and tickets/ in the current folder | | tix new | Create a ticket; fields become --<field> flags | | tix ls [KEY:VALUE ...] | List tickets, filtered by status:, group: or any field | | tix show ID | Print a ticket's fields, deliverables and brief | | tix mv ID STATUS | Change status | | tix set ID KEY=VALUE ... | Change title, status or fields in one write | | tix attach ID REF / tix detach ID REF_OR_LABEL | Link or unlink deliverables (URLs, paths; never copied) | | tix board [--group] | Kanban-style columns | | tix check | Validate the schema and every ticket | | tix path ID | Print the ticket folder path |

The schema

tix init writes this default. Edit it freely, then run tix check; tickets that no longer fit are still shown, marked !.

version: 1
statuses:
  - name: backlog
    group: backlog
  - name: in_progress
    group: in_progress
  - name: done
    group: completed
fields:
  - name: client
    type: string
    required: true
  - name: type
    type: enum
    values: [article, landing_page, linkedin, other]
    required: true
  - name: owner
    type: string
  - name: due
    type: date

Field types: string, enum (with values), date (YYYY-MM-DD), list. Every status belongs to a group: backlog, in_progress or completed.

How it's built

• crates/tix-core: the ticket logic (validation, writes, filtering, sorting, board layout), formally verified with Verus. Validation is proved equivalent to the spec; every write is proved to keep tickets valid and change only what it names.
• crates/tix-io: argument parsing, YAML and Markdown, tables, and all commands, behind a five-method storage trait.
• crates/tix-cli: the tix binary (native or wasm32-wasip1).
• tix mcp: one MCP server implementation in tix-io, served by both the native binary and the npm package.
• crates/tix-wasm + bin/tix.js: the same core as a WebAssembly npm package for Node 18+.

Requirements are in tix.sdoc; design decisions are logged in PLAN.md; contributor notes in CLAUDE.md.

Development

Requires Rust (pinned in rust-toolchain.toml), Verus 0.2026.09.13.671956e, wasm-pack, and Node 20+.

npm run ci                                   # verus verify, cargo test, wasm build, node tests
cargo install --path crates/tix-cli          # local tix binary

Releases: push a v* tag and the release workflow attaches binaries for macOS, Linux and Windows (x86-64 and ARM64) and WASI. The same tag publishes @viewengine/tix to npm through trusted publishing (no token); the tag must match package.json's version.

License

MIT