Mach

A terminal-first task manager for people who live in the shell and work with agents.

Categories, reusable labels, due dates, subtasks, inline images, and a CLI that scripts or agents can drive.

Install

# 1. checksum-verified release binary → ~/.local/bin
curl -fsSL https://raw.githubusercontent.com/Q1CHENL/mach/main/install.sh | sh

# 2. crates.io → ~/.cargo/bin  (Rust 1.90+)
cargo install --locked mach-tui

# 3. local clone
git clone https://github.com/Q1CHENL/mach.git && cd mach && cargo install --locked --path .

Crate name mach-tui, binary mach.

CLI

mach with no args opens the TUI. Subcommands cover add / list / edit / done / delete / categories / labels / subtasks and more, with flags for due dates, importance, categories, labels, description markup, and --json for scripts.

mach --help

Agents work well against the same CLI — stable flags, unique ID prefixes, and JSON output when you need it.

Labels are global and reusable. Create them explicitly, assign multiple labels to a task, and repeat --label to require every named label when listing:

mach labels add bug --color red
mach labels add backend
mach labels edit backend --color green
mach add "Fix retry handling" --label bug --label backend
mach list --label bug --label backend --open
mach edit TASK_ID --remove-label bug --add-label release

Colors are stored as portable logical names: red, orange, yellow, lime, green, teal, cyan, blue, indigo, purple, pink, or brown. When --color is omitted, Mach picks the least-used color. In the TUI, open /labels; the New/Edit editor lets you choose a color before saving.

Export every task, category, label and referenced image to one portable archive, then safely merge it into another mach data directory:

mach export tasks.mach
mach --dir ~/restored-mach import tasks.mach

The TUI uses /export to create a timestamped .mach archive in the current directory and /import <FILE> to restore a specified archive. The CLI also accepts mach export [FILE]; without a file it uses the current directory. Export never overwrites an existing file. Re-importing identical records is a no-op. An ID, category-name, label-name or attachment metadata conflict aborts the whole merge before tasks, categories or attachment records change.

The TUI checks in the background, including while it stays open. A successful check schedules the next one 24 hours later. Failed checks retry after an hour by default and honor server-provided backoff. Run /update to download, verify its SHA-256 checksum, and install the latest release, or use mach update --install from the shell. Self-update follows release-installer ownership: it updates ~/.local/bin/mach or a custom destination previously recorded by the release installer. Cargo and other package-manager installs must be updated through their manager; set MACH_INSTALL_DIR only when you intentionally want to replace one with a release binary.

Data

Lives in ~/.mach: tasks, categories, labels and settings in SQLite (mach.db), with managed images under images/. The CLI and TUI safely share the same store, and changes appear in the running app.

Existing JSON data is imported automatically on first launch and left untouched. Back up the whole directory while mach is closed.

Portable .mach archives contain versioned JSON data plus the exact managed image bytes referenced by those tasks. Import verifies the archive structure, image format, size and SHA-256 before committing. App preferences and the separate update schedule are not part of a task archive.

Another folder: --dir PATH or MACH_DIR.

Update scheduling and discovered releases are shared separately in ~/.mach/update.db, so changing the task data directory does not duplicate or suppress application updates.

License

MIT