tk

Minimal task tracker. Simple, fast, git-friendly.

• Plain JSON files in .tasks/
• No daemons, no merge conflicts, no viruses

Install

Requires Bun runtime.

# Install Bun first (if not installed)
curl -fsSL https://bun.sh/install | bash

# Then install tk globally
bun add -g @nijaru/tk

Quick Start

$ cd myapp
$ tk init                               # project auto-derived from directory
Initialized: .tasks

$ tk add "Implement auth" -p 1
myapp-a7b3

$ tk add "Write tests" -p 2
myapp-x9k2

$ tk block x9k2 a7b3                # tests blocked by auth (just use ref)

$ tk ready                          # what can I work on?
ID          | PRIO | STATUS       | TITLE
-----------------------------------------------------------------
myapp-a7b3  | p1   | open         | Implement auth

$ tk start a7b3                     # just the ref works everywhere
Started: myapp-a7b3

$ tk log a7b3 "Using JWT approach"
Logged: myapp-a7b3

$ tk done a7b3
Completed: myapp-a7b3

$ tk ready                          # tests now unblocked
ID          | PRIO | STATUS       | TITLE
-----------------------------------------------------------------
myapp-x9k2  | p2   | open         | Write tests

Commands

| Command | Description | | --------------------------- | ------------------------------------------ | | tk init | Initialize (project name from directory) | | tk add <title> | Create task | | tk ls / tk list | List tasks | | tk ready | List active/open + unblocked tasks | | tk show <id> | Show task details | | tk start <id> | Start working (open → active) | | tk done <id> | Complete task | | tk reopen <id> | Reopen task | | tk edit <id> | Edit task | | tk log <id> "<msg>" | Add log entry | | tk block <id> <blocker> | Add dependency (id blocked by blocker) | | tk unblock <id> <blocker> | Remove dependency | | tk rm / tk remove <id> | Delete task | | tk clean | Remove old done tasks (default: 14 days) | | tk check | Check task integrity | | tk config | Show/set configuration | | tk completions <shell> | Output shell completions (bash, zsh, fish) | | tk help [command] | Show help (or command-specific help) |

Add Options

tk add "Title" -p 2                  # Priority (0-4)
tk add "Title" -P api                # Project prefix
tk add "Title" -d "Description"      # Description
tk add "Title" -l bug,urgent         # Labels (CSV)
tk add "Title" -A nick,alice         # Assignees (CSV, @me for git user)
tk add "Title" --parent a7b3         # Parent task (ref works)
tk add "Title" --estimate 3          # Estimate (user-defined units)
tk add "Title" --due 2026-01-15      # Due date (YYYY-MM-DD)
tk add "Title" --due +7d             # Relative due date (+Nh/+Nd/+Nw/+Nm)

List Options

tk ls                          # List tasks (limit 20)
tk ls -a                       # Show all (no limit)
tk ls -s active                # Filter by status
tk ls -p 1                     # Filter by priority
tk ls -P api                   # Filter by project
tk ls -l bug                   # Filter by label
tk ls --assignee nick          # Filter by assignee
tk ls --parent a7b3            # Filter by parent (ref works)
tk ls --roots                  # Top-level tasks only
tk ls --overdue                # Overdue tasks only
tk ls -n 10                    # Limit results

Edit Options

tk edit a7b3 -t "New title"    # Update title
tk edit a7b3 -p 1              # Update priority
tk edit a7b3 -l +urgent        # Add label
tk edit a7b3 -l -bug           # Remove label (use --labels=-bug)
tk edit a7b3 --due -           # Clear due date
tk edit a7b3 --parent -        # Clear parent

Clean Options

tk clean                       # Remove done tasks older than config (default: 14 days)
tk clean --older-than 30       # Custom threshold (days)
tk clean --force               # Force clean even if disabled in config

Config

tk config                                       # Show all config
tk config project                               # Show default project
tk config project api                           # Set default project
tk config project lsmvec --rename cloudlsmvec   # Rename cloudlsmvec-* → lsmvec-*
tk config alias                                 # List aliases
tk config alias web src/web                     # Add alias
tk config alias --rm web                        # Remove alias

Config file (.tasks/config.json):

{
  "version": 1,
  "project": "myapp",
  "clean_after": 14,
  "defaults": { "priority": 3, "labels": [], "assignees": [] },
  "aliases": {}
}

• clean_after: Days to keep done tasks (default: 14). Set to false to disable cleaning.

Task IDs

Format: project-ref (e.g., myapp-a7b3, api-x9k2, web-3m8p)

• Just use the ref - a7b3 works everywhere, no need to type myapp-a7b3
• Project prefix auto-derived from directory name on init (or use -P flag)
• Random 4-char alphanumeric ref (a-z, 0-9)
• Prefix matching: a7 resolves to myapp-a7b3 if unambiguous
• Random IDs prevent merge conflicts in team workflows

Priority

| Value | Name | Description | | ----- | ------ | ---------------- | | 0 | none | No priority set | | 1 | urgent | Drop everything | | 2 | high | Important | | 3 | medium | Normal (default) | | 4 | low | Nice to have |

Accepts: 0-4, p0-p4, or none/urgent/high/medium/low

Status Flow

open → active → done

Storage

.tasks/
  config.json     # Project config
  tk-a7b3.json    # Task files
  api-x9k2.json

Each task file:

{
  "project": "tk",
  "ref": "a7b3",
  "title": "Implement auth",
  "description": "Use JWT approach",
  "status": "open",
  "priority": 3,
  "labels": ["bug"],
  "assignees": ["nick"],
  "parent": null,
  "blocked_by": [],
  "estimate": 3,
  "due_date": "2026-01-15",
  "logs": [{ "ts": "2026-01-05T10:00:00Z", "msg": "Started research" }],
  "created_at": "2026-01-05T09:00:00Z",
  "updated_at": "2026-01-05T10:00:00Z",
  "completed_at": null,
  "external": {}
}

Global Options

• -C <dir> - Run in different directory (tk -C ../other-repo ls)
• --json - Output as JSON (works anywhere: tk ls --json or tk --json ls)
• -h, --help - Show help (tk add --help or tk help add for command help)
• -V, --version - Show version

Environment

• NO_COLOR - Disable colored output (any non-empty value)

Colors are also automatically disabled when output is piped.

Shell Completions

# Bash (add to ~/.bashrc)
eval "$(tk completions bash)"

# Zsh (add to ~/.zshrc)
eval "$(tk completions zsh)"

# Fish (add to ~/.config/fish/config.fish)
tk completions fish | source

License

MIT