Installation

Install tsk globally from npm. The package name is tskrun, but the CLI command is tsk.

Or run it directly without installing:

Requires Node.js 18 or later. No other dependencies.

Agent Skill

Install the tsk agent skill to let AI coding agents manage tasks for you.

Once installed, your AI agent can create, move, and manage tasks using tsk commands automatically.

Quick Start

Initialize a project, add tasks, move them through statuses.

Tasks live in the .tsk/ directory inside your project. Commit them alongside your code.

Commands

tsk init

Initialize a new tsk project in the current directory. Creates a .tsk/ directory with config.yml and task storage. Fails if .tsk/ already exists.

tsk init [options]

tsk add <title>

Create a new task. Returns the created task ID.

tsk add "Task title" [options]

tsk list

List tasks with filtering, sorting, and grouping. Also available as tsk ls.

tsk list [options]
tsk ls [options]

tsk view <id>

View full details of a task, including its activity log. Accepts numeric IDs or prefixed IDs.

tsk view 1
tsk view TSK-1

tsk move <id...> <status>

Move one or more tasks to a new status. The last argument is always the target status. Supports batch moves.

tsk move 1 in_progress            # single task
tsk move 1 2 3 done               # batch move
tsk move 1 2 3 done --by agent    # with attribution

tsk edit <id>

Update fields on an existing task.

tsk edit 1 [options]

tsk note <id> <message>

Add a note to a task. Notes appear in the task's activity log.

tsk note 1 "Found a bug in the parser"
tsk note 1 "Blocked on API changes" --by claude

tsk log

Show the activity log across all tasks, sorted newest first.

tsk log [options]

tsk archive [id]

Archive a single task or all completed tasks. Archived tasks are hidden from tsk list by default.

tsk archive 1            # archive task 1
tsk archive --done       # archive all done tasks
tsk archive 1 --undo     # unarchive task 1

tsk rm <id>

Permanently remove a task. This cannot be undone.

tsk rm 1

tsk summary

Show a project summary with task counts by status.

tsk summary
tsk summary --json

JSON output shape:

{
  "total": 5,
  "statuses": {
    "todo": 2,
    "in_progress": 1,
    "review": 1,
    "done": 1
  }
}

tsk web

Launch a local web dashboard for your task board. Opens in your default browser.

tsk web [options]

The dashboard provides a read-only board view served at http://localhost:3456 with a JSON API at /api/data.

Output Formats

tsk auto-detects whether stdout is a TTY and adjusts its output accordingly.

These global flags work with any command. This makes tsk easy to compose with other tools:

# pipe to jq
tsk list --json | jq '.[] | select(.priority == "p0")'

# grab just the ID of a new task
NEW_ID=$(tsk add "Fix bug" --quiet)

# export as YAML
tsk list --yaml > tasks.yml

Task Model

Every task has the following fields.

IDs

Task IDs are sequential integers. Commands accept both the bare number and the prefixed form. With the default prefix TSK, task 1 can be referenced as 1 or TSK-1. The prefix is set during tsk init and stored in .tsk/config.yml.

Statuses

The default status workflow:

Priorities

Four priority levels, from highest to lowest:

Priority is optional. Tasks without a priority are unranked.

Tags

Tags are free-form string labels. Pass multiple tags as a comma-separated list:

tsk add "API endpoint" --tag backend,api,v2

Filter by tag with tsk list --tag backend.

Parent Tasks

Tasks can reference a parent to create subtask hierarchies:

tsk add "Implement auth" --parent 1

Filter subtasks with tsk list --parent 1.

Activity Tracking

Every mutation is recorded in the task's activity array as an append-only log. Entries include a timestamp, action type, author, and optional detail.

The --by flag

All mutation commands (add, move, edit, note, archive) accept --by <name> to attribute the change. Defaults to $USER from the environment.

tsk move 1 done --by claude
tsk note 1 "Shipped to production" --by deploy-bot

This is useful for distinguishing human vs. automated changes, or tracking which team member made each update.

Notes

Use tsk note to add freeform commentary to a task. Notes are stored as note entries in the activity log and appear when viewing the task with tsk view.

Activity Log

Use tsk log to see recent activity across all tasks. Each entry shows the timestamp, task ID, action, author, and detail.

Example activity entries inside a task file:

activity:
  - timestamp: "2026-01-15T10:30:00.000Z"
    action: created
    by: vikas
  - timestamp: "2026-01-15T12:00:00.000Z"
    action: moved
    by: claude
    detail: "todo → in_progress"
  - timestamp: "2026-01-15T14:20:00.000Z"
    action: note
    by: claude
    detail: "Started implementation, found edge case"

Storage

All data lives in the .tsk/ directory at your project root. There are two storage backends.

Multi-file (default)

Each task is a separate YAML file. This produces clean git diffs and avoids merge conflicts when multiple people work on different tasks.

Single-file

All tasks in one file. Simpler for small projects or scripting use cases.

Choose the storage type during tsk init:

tsk init --storage multi-file   # default
tsk init --storage single-file

Both backends use atomic writes (temporary file + rename) to prevent data corruption.

Config file

The .tsk/config.yml file stores project-level settings: the ID prefix, storage type, status definitions, templates, and the auto-increment counter.

Web Dashboard

Run tsk web to launch a local web dashboard that displays your task board in a browser.

• Serves on port 3456 by default (override with --port)
• Opens your default browser automatically
• Read-only board view of all non-archived tasks
• JSON API available at /api/data
• No external dependencies -- self-contained HTML served by a Node HTTP server

Exit Codes

tsk uses structured exit codes for scripting and CI integration.