Tasks

- ⚡ Ultra-efficient design: Minimal tool count (5 tools) to reduce AI confusion
- 🎯 Budget-optimized: Batch operations, smart defaults and auto-operations minimize LLM API calls
- 🚀 Multi-format support: Markdown (.md), JSON (.json), and YAML (.yml) task files
- 🔍 Powerful search: Case-insensitive text/status filtering with OR logic, and ID-based lookup
- 📊 Smart organization: Status-based filtering with customizable workflow states
- 🎯 Position-based indexing: Easy task ordering with 0-based insertion
- 📁 Multi-source support: Manage multiple task files simultaneously
- 🔄 Real-time updates: Changes persist automatically to your chosen format
- 🤖 Auto WIP management: Automatically manages work-in-progress task limits
- 🚫 Duplicate prevention: Automatically prevents duplicate tasks
- 🛡️ Type-safe: Full TypeScript support with Zod validation
- 🔒 Ultra-safe: AI has no way to rewrite or delete your tasks (unless you enable it), only add and move them

When PREFIX_TOOLS=true (default), all tools are prefixed with tasks_:

| Tool | Description | Parameters |
|------|-------------|------------|
| tasks_setup | Initialize a task file (creates if missing, supports .md, .json, .yml) | source_path, workspace? |
| tasks_search | Search tasks with filtering | source_id, statuses?, terms?, ids? |
| tasks_add | Add new tasks to a status | source_id, texts[], status, index? |
| tasks_update | Update tasks by ID | source_id, ids[], status, index? |
| tasks_summary | Get task counts and work-in-progress | source_id |

ID Format: Both source_id (from file path) and task id (from task text) are 4-character alphanumeric strings (e.g., "xK8p", "m3Qw").

Setup a task file:

tasks_setup({

  workspace: "/path/to/project",

  source_path: "tasks.md"  // relative to workspace or absolute

  // source_path: "tasks.json"

  // source_path: "tasks.yml"

})

// Returns: {"source":{"id":"xK8p","path":"/path/to/project/tasks.md"},"Backlog":0,"To Do":0,"In Progress":0,"Done":0,"inProgress":[]}

// Source ID (4-char alphanumeric) is used for all subsequent operations

Add tasks:

tasks_add({

  source_id: "xK8p", // From setup response

  texts: ["Implement authentication", "Write tests"],

  status: "To Do",

  index: 0  // Add at top (optional)

})

// Returns: {"source":{"id":"xK8p","path":"/absolute/path/to/tasks.md"},"Backlog":0,"To Do":2,"In Progress":0,"Done":0,"inProgress":[],"tasks":[{"id":"m3Qw","text":"Implement authentication","status":"To Do","index":0},{"id":"p9Lx","text":"Write tests","status":"To Do","index":1}]}

Search and filter:

tasks_search({

  source_id: "xK8p",        // From setup response

  terms: ["auth", "deploy"],          // Search terms (text or status, OR logic)

  statuses: ["To Do"],      // Filter by status

  ids: ["m3Qw", "p9Lx"]     // Filter by specific task IDs

})

// Returns: [{"id":"m3Qw","text":"Implement authentication","status":"To Do","index":0}]

Update tasks status:

tasks_update({

  source_id: "xK8p",        // From setup response

  ids: ["m3Qw", "p9Lx"],    // Task IDs from add/search responses

  status: "Done"            // Use "Deleted" to remove

})

// Returns: {"source":{"id":"xK8p","path":"/absolute/path/to/tasks.md"},"Backlog":0,"To Do":0,"In Progress":0,"Done":2,"inProgress":[],"tasks":[{"id":"m3Qw","text":"Implement authentication","status":"Done","index":0},{"id":"p9Lx","text":"Write tests","status":"Done","index":1}]}

Get overview:

tasks_summary({

  source_id: "xK8p"         // From setup response

})

// Returns: {"source":{"id":"xK8p","path":"/absolute/path/to/tasks.md"},"Backlog":0,"To Do":0,"In Progress":1,"Done":2,"inProgress":[{"id":"r7Km","text":"Fix critical bug","status":"In Progress","index":0}]}