Install

Available for macOS and Linux, on ARM64 and x86-64.

Install

curl -fsSL https://gettsk.sh/install.sh | sh

Or use Homebrew:

brew install smarzban/tap/tsk

Reopen your terminal if prompted, or run the printed export command.

If Herdr is already installed, the curl installer asks whether to run tsk setup herdr when a terminal is available. When global agent skill roots are detected, it also asks once whether to install or update the tsk skill for those agents. The installer closes with one Done. line — Done. Run tsk in a project directory to open the board, plus , or press prefix+t in Herdr after an accepted Herdr setup — and one row per step that did not run: Herdr plugin: tsk setup herdr when Herdr setup was declined, skipped under CI or no TTY, or failed, and Agent skills: tsk setup when the skill ask was declined or skipped. With TSK_INSTALL_DIR set, the installer skips both asks and prints Custom install directory: setup was not run. When you are ready: with the full binary path in both rows. Homebrew stays noninteractive and prints the tsk setup herdr and tsk setup agents commands as a caveat.

Add to Herdr

Install Herdr first. Setup requires Herdr 0.9 or newer: an older herdr on PATH is refused with herdr X.Y.Z found; tsk needs 0.9.0 or newer before anything is written, so update Herdr and run tsk setup herdr again.

tsk setup herdr
herdr server reload-config

Shortcut	Action
prefix+t	Open or focus the board in this workspace
prefix+a	Quick capture

Use your configured Herdr prefix. An existing board in this workspace is focused across tabs without resetting its view. If none exists here, a new board opens; other workspaces keep their boards. Herdr keyboard guide.

Agent skill

tsk setup
tsk setup pi

On a TTY, bare tsk setup detects installed agents and asks once to install or update the skill. Use omp, claude, cursor, grok, codex, or opencode instead of pi for a single named target. Setup installs the CLI skill in that agent’s user-level skills directory; OMP uses its active profile.

Detection, version updates, and overwrite options.

First task

Open the board and press +, type a title, then Enter. Or use the CLI:

tsk add -t "your task title"

Give your agent the task number to work on it. Board guide.

For standalone use, run tsk directly in your terminal.

Upgrade

Run tsk update to upgrade an installer-managed copy. It downloads the same checksum-verifying installer used for the first install, and runs it only once the download completed, printing the version it replaces and the one it installs. It always follows the latest published release (a TSK_VERSION in your shell is ignored) and refuses to move backwards if the running copy is newer than that release. A Homebrew copy stays under Homebrew’s control: tsk update prints brew update && brew upgrade tsk instead.

Installed with	Upgrade
Installer	`tsk update`
Homebrew	`brew update && brew upgrade tsk`
Source	Pull changes and rebuild

After the binary is replaced, tsk update refreshes what is already set up:

A registered Herdr plugin (both plugin commands bound, on any keys) is re-registered without asking and reported as Herdr plugin refreshed. Reload Herdr’s config afterwards. If Herdr is on PATH but not set up, it asks as on a first install.
Installed agent skills at an older version are updated. On a terminal it asks once (tsk skill installed for claude (v1.2.0), codex (v1.2.0); update to v1.3.0? [Y/n], Enter means yes); without one it updates unattended. It then lists the agents it updated. Skills that are already current print nothing. An update never installs a skill for an agent that did not have one; if no skill is installed anywhere, it offers the first-install ask for the detected agents.
A refresh that fails leaves the binary in place, prints tsk setup’s reason, and prints the matching tsk setup row. Updating onto a release older than this behaviour prints the plain tsk setup rows instead.

Close and reopen running boards to use the new binary.

The board shows a notice when a newer release is available. Update-check settings.

Uninstall

Installed with	Remove
Installer	Delete `tsk` from its installation directory
Homebrew	`brew uninstall tsk`

Task data remains in place.

To remove Herdr integration, run herdr plugin unlink herdr-tsk, remove the two shortcut bindings, and reload Herdr’s config.

To undo installer PATH changes, remove the # tsk PATH comment and its following case line from the startup files named during installation.

Installer details

The installer verifies the release’s SHA-256 checksum and installs to ~/.local/bin. It does not require sudo or change task data.

Setting	Purpose
`TSK_INSTALL_DIR`	Choose an absolute installation directory (no colons or newlines); the post-install setup asks are skipped
`TSK_VERSION=vX.Y.Z`	Install a specific stable release
`--help`	Show help without downloading

Requires curl, tar, sed, and sha256sum or shasum.

PATH

If the install directory is missing from PATH, the installer adds it to:

Shell	Startup files
Zsh	`$ZDOTDIR/.zshrc`, or `~/.zshrc`
Bash	`~/.bashrc` and the first existing login profile; defaults to `~/.profile`

The installer does not source these files. Symlinked, non-regular, or unwritable files are skipped with manual instructions. Other shells require manual PATH setup. Successful edits remain if another file cannot be updated.

Herdr prompt

When herdr is on PATH after the binary is installed, the installer may ask to run plugin setup:

Interactive terminal (stdin TTY, or /dev/tty under curl | sh) using the default ~/.local/bin destination: asks [y/N]. Yes runs the newly installed tsk setup herdr. An overridden TSK_INSTALL_DIR never executes the newly published binary; the closing block prints the tsk setup herdr and tsk setup commands with the full binary path instead.
CI set, or no usable TTY: skips the ask so the install never hangs.
Herdr absent: no Herdr prompt.

The install always ends with one closing block:

Setup accepted: Done. Run tsk in a project directory to open the board, or press prefix+t in Herdr.
Declined, CI/no-TTY skip, or setup failure: Done. Run tsk in a project directory to open the board. followed by a Herdr plugin: tsk setup herdr row.
Agents detected but the skill batch declined or skipped: a Agent skills: tsk setup row.
Herdr absent: the Done. line only (no Herdr row).

Setup failures do not undo the install. Homebrew does not run this prompt; use the formula caveat or run tsk setup herdr yourself.

Herdr setup with an installed binary

Setup registers bundled plugin files using the installed executable. No source checkout is needed.

Shortcut conflicts ask for confirmation. Declining keeps the existing binding, and the output says so.
A noninteractive conflict stops before writing.
Config changes create a backup beside the config, config.toml.tsk-backup-<YYYYMMDD-HHMMSS> in UTC; a second setup within the same second appends -1, -2, …
Rerunning setup updates the registration without duplicating bindings.
Use the stable command on PATH, not a versioned Homebrew Cellar path.

Installation alone does not update an existing plugin registration unless you answer yes to the curl installer’s Herdr prompt. Setup recovery and configuration.

Manual archives

Download the archive for your platform and SHA256SUMS from the same release.

Platform	Archive target
macOS Apple silicon	`aarch64-apple-darwin`
macOS Intel	`x86_64-apple-darwin`
Linux ARM64	`aarch64-unknown-linux-musl`
Linux x86-64	`x86_64-unknown-linux-musl`

Archives are named tsk-vX.Y.Z-<target>.tar.gz. Verify with shasum -a 256 on macOS or sha256sum on Linux. Compare the full digest with SHA256SUMS, then extract tsk into a directory on PATH.

Source build

Requires Rust 1.96.0:

git clone https://github.com/smarzban/tsk.git
cd tsk
cargo build --release
export PATH="$PWD/target/release:$PATH"

For plugin development from a checkout, Herdr 0.9.0+ supports herdr plugin link "$PWD". Rebuild after pulling changes.

Contributing · Storage and configuration