Task CLI

A simple, fast task tracker for Windows with native toast notifications and Task Scheduler integration.

Built with TypeScript. Zero background processes. Reminders run natively via Windows Task Scheduler.

Installation

npm install -g @adekpp/task-cli

Or run without installing:

npx @adekpp/task-cli list

Quick Start

# Add a task
task-cli add "Buy groceries"

# Add a task with a reminder (fires in 1 hour)
task-cli add "Call dentist" --notify 1h

# List tasks
task-cli list

# Mark a task as done
task-cli done

# Delete tasks (multi-select with space, confirm with enter)
task-cli delete

# Clear all tasks (requires confirmation)
task-cli clear

Commands

| Command | Alias | Description | |---------|-------|-------------| | task-cli add <description> | | Add a new task | | task-cli add <desc> --notify <time> | | Add task with scheduled reminder | | task-cli list [--status todo\|done] | ls | List tasks with pagination | | task-cli update | edit | Update a task's description | | task-cli delete | rm | Delete tasks (multi-select) | | task-cli done | | Mark tasks as done (multi-select) | | task-cli todo | | Revert tasks to todo (multi-select) | | task-cli notify | | Show summary as Windows notification | | task-cli clear | | Clear all tasks (requires confirmation) | | task-cli setup-skill | | Install Claude Code /task skill |

Claude Code Integration

Task CLI ships with a skill for Claude Code. After installing, run:

task-cli setup-skill

This installs the /task skill globally. You can then manage tasks in natural language:

> add a task to review the PR in 30 minutes
> show me what's left to do
> remind me to deploy in 2 hours

The skill is also bundled in the repo at .claude/skills/task/ for project-level use.

Reminders

Schedule a Windows toast notification when adding a task:

task-cli add "Team standup" --notify 30m
task-cli add "Deploy release" --notify 2h15m
task-cli add "Quick check" --notify 1h30m10s

Duration format: <hours>h<minutes>m<seconds>s - all parts are optional.

| Example | Fires after | |---------|-------------| | 10m | 10 minutes | | 1h | 1 hour | | 1h30m | 1 hour 30 minutes | | 2h15m30s | 2 hours 15 minutes 30 seconds |

Reminders are registered as one-shot tasks in Windows Task Scheduler - no background process, no polling. They survive reboots and fire even if the terminal is closed.

Marking a task as done or deleting it automatically cancels the pending reminder.

Pagination

Lists are paginated (15 tasks per page by default):

task-cli list                    # page 1
task-cli list --page 3           # jump to page 3
task-cli list --per-page 10      # 10 tasks per page

In interactive mode, use arrow keys to navigate:

• ← Previous page
• → Next page
• q / Esc Quit

Data Storage

Tasks are stored in %APPDATA%/task-cli/db.json. The notification icon is auto-generated at %APPDATA%/task-cli/icon.png on first use.

Development

# Install dependencies
bun install

# Run directly
bun run index.ts list

# Build for distribution
npm run build

# Link globally for testing
npm link

Project Structure

task-cli/
  index.ts                 Entry point + welcome screen
  types.d.ts               TypeScript type definitions
  src/
    db.ts                  JSON file database
    paths.ts               Centralized path helpers
    fs.ts                  File system + process helpers
    ui.ts                  Interactive task picker
    duration.ts            Duration parser (1h30m -> ms)
    toast.ts               Windows toast notifications
    scheduler.ts           Windows Task Scheduler integration
    icon.ts                Auto-generated notification icon
    commands/
      add.ts               Add task (+ optional reminder)
      list.ts              List with pagination + arrow nav
      update.ts            Update description (reschedules reminder)
      delete.ts            Multi-select delete
      done.ts              Mark done (cancels reminder)
      todo.ts              Revert to todo
      notify.ts            Send summary notification
      clear.ts             Clear all tasks
      setup-skill.ts       Install Claude Code skill
  .claude/
    skills/task/SKILL.md   Claude Code skill definition
  scripts/
    build.ts               esbuild bundler
    postinstall.js         Post-install Claude Code hint

Requirements

• Node.js >= 18
• Windows 10/11 (toast notifications + Task Scheduler)
• PowerShell (ships with Windows)

License

MIT

Author

Adrian Pietryga - github.com/adekpp