Task Kit CLI

Task Kit is a local-first, AI-first project state engine for software development.

Instead of replacing Jira, Linear, or GitHub issues, Task Kit provides a structured, lightweight hierarchy interface for representing the execution state of your project. It is designed to be equally easy to navigate for both humans and AI agents.

Key Features

• 🛠️ Methodology Agnostic: No hardcoded Epics, Sprints, or Stories. Task Kit provides generic nodes that can represent tasks, milestones, research topics, or whatever fits your workflow.
• 🌲 Tree Navigation: Model tasks as a deep tree hierarchy instead of flat lists or queues.
• 🤖 AI-First & Onboarding: Onboards AI agents by providing clean CLI tools and auto-generated instructions (.task/onboarding.md), reducing context usage and parsing errors.
• ⏱️ Agent Checkpoints: Save agent progress checkpoints (summary, activeFiles, nextSteps, dirtyState) so subsequent agents can resume interrupted tasks seamlessly.
• 📂 Local-First & Git-Friendly: Stores data inside .task/ in your repository. Supports version-controlled layouts or local-only untracked states.
• 🔒 File Locking & Migrations: Prevents race conditions with automatic file locking and ensures safe data upgrades with schema migrations.
• ⚡ Zero-Config Setup: Get started in just a few seconds with interactive presets.

Installation & Setup

Install the CLI tool globally via npm:

npm install -g @caio.silveira/taskkit

Or run it directly without installing using npx:

npx @caio.silveira/taskkit <command>

Quick Start

1. Initialize a workspace: Create a new Task Kit state inside your project directory.

   taskkit init --template scrum

2. Display task tree:

   taskkit tree

3. Add a task:

   taskkit create "Implement JWT Auth" --parent Backlog --desc "Add auth middleware" --tags backend,auth

4. Change task status:

   # Move task to Development folder
   taskkit move backlog/implement-jwt-auth development
   
   # Mark task completed
   taskkit complete development/implement-jwt-auth

5. Get recommendations: Get suggestions on what leaf tasks are ready to focus on:

   taskkit recommend

6. Save progress & resume (Agent Checkpointing): Save context when rate limits are low or to hand over tasks:

   # Save a progress checkpoint
   taskkit checkpoint backlog/implement-jwt-auth --summary "Auth setup done" --files "src/auth.ts" --next "Write tests"
   
   # View active progress checkpoint to resume
   taskkit resume backlog/implement-jwt-auth

7. Migrate data schema: Safe database migrations as the schema evolves:

   taskkit migrate