Minimal task tracker
npm install @nijaru/tkMinimal task tracker. Simple, fast, git-friendly.
- Plain JSON files in .tasks/
- No daemons, no merge conflicts, no viruses
Requires Bun runtime.
``bashInstall Bun first (if not installed)
curl -fsSL https://bun.sh/install | bash
Quick Start
`bash
$ 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 | Create task |
| tk ls / tk list | List tasks |
| tk ready | List active/open + unblocked tasks |
| tk show | Show task details |
| tk start | Start working (open → active) |
| tk done | Complete task |
| tk reopen | Reopen task |
| tk edit | Edit task |
| tk log | Add log entry |
| tk block | Add dependency (id blocked by blocker) |
| tk unblock | Remove dependency |
| tk rm / tk remove | Delete task |
| tk clean | Remove old done tasks (default: 14 days) |
| tk check | Check task integrity |
| tk config | Show/set configuration |
| tk completions | Output shell completions (bash, zsh, fish) |
| tk help [command] | Show help (or command-specific help) |Add Options
`bash
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
`bash
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
`bash
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
`bash
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
`bash
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):`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 workflowsPriority
| 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/lowStatus Flow
`
open → active → done
`Storage
`
.tasks/
config.json # Project config
tk-a7b3.json # Task files
api-x9k2.json
`Each task file:
`json
{
"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 - 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 versionEnvironment
-
NO_COLOR - Disable colored output (any non-empty value)Colors are also automatically disabled when output is piped.
Shell Completions
`bash
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
``