mintick

README

mintick

Tiny scheduled-task tool. An LLM-friendly CLI over native init units (systemd-user on Linux, launchd on macOS). Single static Go binary, no runtime deps. The same binary is also a fir extension.

What it is

• One native unit per install — a 60s timer that runs mintick tick.
• Job definitions are one file per job in $XDG_CONFIG_HOME/mintick/jobs/.
• Filename is the job id. Disable by moving to jobs/disabled/.
• Each tick: read jobs, launch every due one as a detached mintick _runjob subprocess (per-job flock, output to a log file, run-state recorded).

Install

Prebuilt binary (Linux/macOS/FreeBSD):

curl -fsSL https://raw.githubusercontent.com/kfet/mintick/main/install.sh | sh

Or from source (Go 1.24+):

go install github.com/kfet/mintick@latest    # or: git clone && make install

Then set it up:

mintick install                      # writes + enables the native unit (60s timer)
mintick add hello "*/5 * * * *" "echo hi from mintick"
mintick list

Commands

mintick add <id> <schedule> <command> [--cwd P] [--env "K=V"] [--allow-overlap] [--force]
mintick list [--json]
mintick get <id> [--json]
mintick remove <id>
mintick enable <id>
mintick disable <id>          # moves to jobs/disabled/, no delete
mintick run <id> [--json]     # sync test exec, no state update
mintick logs <id> [-n N]
mintick tick                  # (run by the unit)
mintick install [--force]     # version-aware: noop on same, upgrade older, refuse newer
mintick uninstall
mintick doctor [--json]
mintick ext                   # run as a fir extension (stdio JSON-RPC)

Flags work in any position (get j --json and get --json j both work).

Schedule syntax

Standard 5-field cron, restricted subset:

• Fields: minute hour day-of-month month day-of-week (DOW: 0=Sun..6=Sat).
• Each field: *, N, N-M, */N, A-B/N, A,B,C.
• No names (MON, JAN), no @hourly/@daily, no L/W/#.
• DOM and DOW cannot both be restricted — set one to *. The validator rejects combinations (sidesteps Vixie cron's OR semantics).

fir extension

The same binary speaks the fir extension protocol via mintick ext (using the firext Go SDK). Install as a sub-directory extension:

mkdir -p ~/.config/fir/extensions/mintick
cp $(command -v mintick) ~/.config/fir/extensions/mintick/mintick
printf '#!/usr/bin/env bash\nexec "$(dirname "$0")/mintick" ext\n' \
  > ~/.config/fir/extensions/mintick/main.sh
chmod +x ~/.config/fir/extensions/mintick/main.sh

fir then exposes mintick_add, mintick_list, mintick_get, mintick_remove, mintick_enable, mintick_disable, mintick_logs, mintick_doctor tools, a /mintick slash command, and surfaces recent job failures on session start.

Layout (XDG)

$XDG_CONFIG_HOME/mintick/jobs/<id>.job          # job config (key=value)
$XDG_CONFIG_HOME/mintick/jobs/disabled/<id>.job # paused
$XDG_STATE_HOME/mintick/state/<id>.json         # last_run, last_exit, ...
$XDG_STATE_HOME/mintick/logs/<id>.log           # per-job stdout/stderr
$XDG_STATE_HOME/mintick/locks/<id>.lock         # flock targets
$XDG_STATE_HOME/mintick/tick.log                # dispatcher log

Build & test

go build ./...
go test ./...

History

A Python implementation preceded this Go rewrite; it's preserved at the python-v0.1.0 git tag. The Go version eliminates the Python runtime/pipx dependency — a single static binary that is the CLI, the dispatcher, and the fir extension.

License

MIT.

Documentation

Overview

Command mintick is a tiny scheduled-task tool: an LLM-friendly CLI over native init units (systemd-user on Linux, launchd on macOS). The same binary is also a fir extension (run `mintick ext`).