Claude Task Tracker (ctt)
A CLI task tracker with dependency management designed to extend memory for agentic code workflows like Claude Code.
Features
- Task Dependencies: Blocking dependencies that prevent task execution until completed
- Soft References: Non-blocking references between related tasks
- Task Overviews: Context summaries filled on completion for dependent tasks to reference
- Plan File References: Link tasks to external plan files with detailed implementation notes
- Ready Task Detection: next command finds tasks ready to work on (open + all blockers completed)
- Multiple Output Formats: Default, JSON, and compact (token-efficient for LLMs)
- Claude Code Integration: Auto-generates CLAUDE.md with usage instructions on init
Installation
$3
``bash
brew tap farisphp/tap
brew install ctt
`
$3
`bash
npm install -g claude-task-tracker
`
$3
`bash
git clone https://github.com/farisphp/claude-task-tracker.git
cd claude-task-tracker
npm install
npm run build
npm link
`
Quick Start
`bash
Initialize in your project (creates .tasks/tasks.json and CLAUDE.md)
ctt init
Add tasks with dependencies
ctt add "Design API schema" -d "Define REST endpoints"
ctt add "Implement auth" --blocked-by t1
ctt add "Write tests" --blocked-by t2 --ref t1
Add a task with a plan file
ctt add "Refactor database" -p .tasks/plans/db-refactor.md
Get next ready task
ctt next
Output: t1 - Design API schema
Start working
ctt start t1
Complete with overview (context for dependent tasks)
ctt complete t1 -o "Created OpenAPI spec with /users, /auth endpoints. JWT-based auth."
Get context for dependent task (includes blocker overviews)
ctt context t2
`
Commands
| Command | Description |
|---------|-------------|
|
ctt init
| Initialize .tasks/tasks.json
in current directory |
| ctt add
<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"> | Add task (</code>-d<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"> description, </code>-b<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"> blockedBy, </code>-r<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"> refs, </code>-p<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"> planFile) |<br />| </code>ctt list<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"> | List all tasks (</code>-s<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"> filter by status) |<br />| </code>ctt show <id><code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"> | Show task details |<br />| </code>ctt next<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"> | Get next ready task (open + all blockers completed) |<br />| </code>ctt start <id><code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"> | Mark as in progress |<br />| </code>ctt complete <id><code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"> | Mark as completed (</code>-o<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"> overview) |<br />| </code>ctt block <id> --by <id><code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"> | Add blocking dependency |<br />| </code>ctt unblock <id> --by <id><code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"> | Remove blocking dependency |<br />| </code>ctt ref <id> --to <id><code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"> | Add soft reference |<br />| </code>ctt unref <id> --to <id><code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"> | Remove soft reference |<br />| </code>ctt context <id><code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"> | Show task + all dependency overviews |<br />| </code>ctt overview <id> <text><code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"> | Update task overview |<br />| </code>ctt plan <id> <path><code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"> | Set or update plan file reference |<br />| </code>ctt delete <id><code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"> | Delete a task |<br />| </code>ctt cleanup<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"> | Remove old completed tasks (</code>-d<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"> days, default 7, </code>--dry-run<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono">) |</p><p class="my-3"><h2 class="text-xl font-semibold mt-5 mb-3">Output Formats</h2></p><p class="my-3"><h3 class="text-lg font-medium mt-4 mb-2">$3</h3><br /></code>`<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono">bash<br />ctt list<br /><h1 class="text-2xl font-bold mt-6 mb-4">○ t1 - Design API</h1><br /><h1 class="text-2xl font-bold mt-6 mb-4">○ t2 - Implement auth [blocked by: t1]</h1><br /><h1 class="text-2xl font-bold mt-6 mb-4">○ t3 - Write tests [blocked by: t2]</h1><br /></code>`<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"></p><p class="my-3"><h3 class="text-lg font-medium mt-4 mb-2">$3</h3><br /></code>`<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono">bash<br />ctt --json next<br /></code>`<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"><br /></code>`<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono">json<br />{<br /> "id": "t1",<br /> "title": "Design API",<br /> "status": "open",<br /> "blockedBy": [],<br /> "references": [],<br /> "overview": null<br />}<br /></code>`<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"></p><p class="my-3"><h3 class="text-lg font-medium mt-4 mb-2">$3</h3><br /></code>`<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono">bash<br />ctt --compact list<br /><h1 class="text-2xl font-bold mt-6 mb-4">t1:Design API[O]</h1><br /><h1 class="text-2xl font-bold mt-6 mb-4">t2:Implement auth[O] <t1</h1><br /><h1 class="text-2xl font-bold mt-6 mb-4">t3:Write tests[O] <t2 ~t1</h1></p><p class="my-3">ctt --compact context t3<br /><h1 class="text-2xl font-bold mt-6 mb-4">t3:Write tests[O] <t2 ~t1</h1><br /><h1 class="text-2xl font-bold mt-6 mb-4">--blockers--</h1><br /><h1 class="text-2xl font-bold mt-6 mb-4">t2:Implement auth[O] <t1</h1><br /><h1 class="text-2xl font-bold mt-6 mb-4">--refs--</h1><br /><h1 class="text-2xl font-bold mt-6 mb-4">t1:Design API[C] >Created OpenAPI spec...</h1><br /></code>`<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"></p><p class="my-3"><strong>Compact format legend:</strong><br />- </code>[O]<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"> = open, </code>[P]<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"> = progress, </code>[C]<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"> = completed<br />- </code><t1,t2<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"> = blocked by t1 and t2<br />- </code>~t1<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"> = references t1<br />- </code>>text<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"> = overview<br />- </code>@path<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"> = plan file reference</p><p class="my-3"><h2 class="text-xl font-semibold mt-5 mb-3">Task States</h2></p><p class="my-3">| Status | Symbol | Description |<br />|--------|--------|-------------|<br />| </code>open<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"> | ○ / O | Not started |<br />| </code>progress<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"> | ◐ / P | In progress |<br />| </code>completed<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"> | ● / C | Done |</p><p class="my-3"><h2 class="text-xl font-semibold mt-5 mb-3">Agentic Workflow Example</h2></p><p class="my-3"></code>`<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono">bash<br /><h1 class="text-2xl font-bold mt-6 mb-4">Agent picks up next task</h1><br />TASK=$(ctt --compact next)<br /><h1 class="text-2xl font-bold mt-6 mb-4">t1:Design API[O]</h1></p><p class="my-3"><h1 class="text-2xl font-bold mt-6 mb-4">Agent starts working</h1><br />ctt start t1</p><p class="my-3"><h1 class="text-2xl font-bold mt-6 mb-4">Agent completes with context for future tasks</h1><br />ctt complete t1 -o "Defined /users CRUD, /auth/login, /auth/refresh. Using JWT with 1h expiry."</p><p class="my-3"><h1 class="text-2xl font-bold mt-6 mb-4">Agent picks up next task and gets context</h1><br />ctt --compact context t2<br /><h1 class="text-2xl font-bold mt-6 mb-4">t2:Implement auth[O] <t1</h1><br /><h1 class="text-2xl font-bold mt-6 mb-4">--blockers--</h1><br /><h1 class="text-2xl font-bold mt-6 mb-4">t1:Design API[C] >Defined /users CRUD, /auth/login...</h1><br /></code>`<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"></p><p class="my-3"><h2 class="text-xl font-semibold mt-5 mb-3">Storage</h2></p><p class="my-3">Tasks are stored in </code>.tasks/tasks.json` in the current directory. This file can be version-controlled.</p><p class="my-3"><h2 class="text-xl font-semibold mt-5 mb-3">License</h2></p><p class="my-3">MIT<br /></p></div><div class="flex justify-center absolute inset-x-0 bottom-0 bg-gradient-to-t from-background via-background to-transparent pb-4 pt-16"><button data-slot="button" class="inline-flex items-center justify-center whitespace-nowrap text-sm font-medium transition-all disabled:pointer-events-none disabled:opacity-50 [&_svg]:pointer-events-none [&_svg:not([class*='size-'])]:size-4 shrink-0 [&_svg]:shrink-0 outline-none focus-visible:border-ring focus-visible:ring-ring/50 focus-visible:ring-[3px] aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 aria-invalid:border-destructive border bg-background shadow-xs hover:bg-accent hover:text-accent-foreground dark:bg-input/30 dark:border-input dark:hover:bg-input/50 h-8 rounded-md gap-1.5 px-3 has-[>svg]:px-2.5"><svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-chevron-down mr-1 h-4 w-4"><path d="m6 9 6 6 6-6"></path></svg>Show more</button></div></div></div><template id="P:3"></template><template id="P:4"></template></div></div></div><script>self.__next_f.push([1,"2a:[\"$\",\"div\",null,{\"data-slot\":\"card-content\",\"className\":\"px-6\",\"children\":[\"$\",\"div\",null,{\"className\":\"grid gap-1 sm:grid-cols-2 lg:grid-cols-3\",\"children\":[[\"$\",\"$L5\",\"@types/node\",{\"href\":\"/package/%40types%2Fnode\",\"className\":\"group flex items-center justify-between rounded-md px-2 py-1.5 text-sm transition-colors hover:bg-accent\",\"children\":[[\"$\",\"span\",null,{\"className\":\"flex items-center gap-1.5 truncate font-mono text-foreground\",\"children\":[[\"$\",\"svg\",null,{\"ref\":\"$undefined\",\"xmlns\":\"http://www.w3.org/2000/svg\",\"width\":24,\"height\":24,\"viewBox\":\"0 0 24 24\",\"fill\":\"none\",\"stroke\":\"currentColor\",\"strokeWidth\":2,\"strokeLinecap\":\"round\",\"strokeLinejoin\":\"round\",\"className\":\"lucide lucide-chevron-right h-3 w-3 text-muted-foreground opacity-0 transition-opacity group-hover:opacity-100\",\"children\":[[\"$\",\"path\",\"mthhwq\",{\"d\":\"m9 18 6-6-6-6\"}],\"$undefined\"]}],\"@types/node\"]}],[\"$\",\"span\",null,{\"className\":\"ml-2 shrink-0 font-mono text-xs text-muted-foreground\",\"children\":\"^20.10.0\"}]]}],[\"$\",\"$L5\",\"@yao-pkg/pkg\",{\"href\":\"/package/%40yao-pkg%2Fpkg\",\"className\":\"group flex items-center justify-between rounded-md px-2 py-1.5 text-sm transition-colors hover:bg-accent\",\"children\":[[\"$\",\"span\",null,{\"className\":\"flex items-center gap-1.5 truncate font-mono text-foreground\",\"children\":[[\"$\",\"svg\",null,{\"ref\":\"$undefined\",\"xmlns\":\"http://www.w3.org/2000/svg\",\"width\":24,\"height\":24,\"viewBox\":\"0 0 24 24\",\"fill\":\"none\",\"stroke\":\"currentColor\",\"strokeWidth\":2,\"strokeLinecap\":\"round\",\"strokeLinejoin\":\"round\",\"className\":\"lucide lucide-chevron-right h-3 w-3 text-muted-foreground opacity-0 transition-opacity group-hover:opacity-100\",\"children\":[[\"$\",\"path\",\"mthhwq\",{\"d\":\"m9 18 6-6-6-6\"}],\"$undefined\"]}],\"@yao-pkg/pkg\"]}],[\"$\",\"span\",null,{\"className\":\"ml-2 shrink-0 font-mono text-xs text-muted-foreground\",\"children\":\"^5.11.0\"}]]}],[\"$\",\"$L5\",\"tsup\",{\"href\":\"/package/tsup\",\"className\":\"group flex items-center justify-between rounded-md px-2 py-1.5 text-sm transition-colors hover:bg-accent\",\"children\":[[\"$\",\"span\",null,{\"className\":\"flex items-center gap-1.5 truncate font-mono text-foreground\",\"children\":[[\"$\",\"svg\",null,{\"ref\":\"$undefined\",\"xmlns\":\"http://www.w3.org/2000/svg\",\"width\":24,\"height\":24,\"viewBox\":\"0 0 24 24\",\"fill\":\"none\",\"stroke\":\"currentColor\",\"strokeWidth\":2,\"strokeLinecap\":\"round\",\"strokeLinejoin\":\"round\",\"className\":\"lucide lucide-chevron-right h-3 w-3 text-muted-foreground opacity-0 transition-opacity group-hover:opacity-100\",\"children\":[[\"$\",\"path\",\"mthhwq\",{\"d\":\"m9 18 6-6-6-6\"}],\"$undefined\"]}],\"tsup\"]}],[\"$\",\"span\",null,{\"className\":\"ml-2 shrink-0 font-mono text-xs text-muted-foreground\",\"children\":\"^8.0.1\"}]]}],[\"$\",\"$L5\",\"tsx\",{\"href\":\"/package/tsx\",\"className\":\"group flex items-center justify-between rounded-md px-2 py-1.5 text-sm transition-colors hover:bg-accent\",\"children\":[[\"$\",\"span\",null,{\"className\":\"flex items-center gap-1.5 truncate font-mono text-foreground\",\"children\":[[\"$\",\"svg\",null,{\"ref\":\"$undefined\",\"xmlns\":\"http://www.w3.org/2000/svg\",\"width\":24,\"height\":24,\"viewBox\":\"0 0 24 24\",\"fill\":\"none\",\"stroke\":\"currentColor\",\"strokeWidth\":2,\"strokeLinecap\":\"round\",\"strokeLinejoin\":\"round\",\"className\":\"lucide lucide-chevron-right h-3 w-3 text-muted-foreground opacity-0 transition-opacity group-hover:opacity-100\",\"children\":[[\"$\",\"path\",\"mthhwq\",{\"d\":\"m9 18 6-6-6-6\"}],\"$undefined\"]}],\"tsx\"]}],[\"$\",\"span\",null,{\"className\":\"ml-2 shrink-0 font-mono text-xs text-muted-foreground\",\"children\":\"^4.7.0\"}]]}],[\"$\",\"$L5\",\"typescript\",{\"href\":\"/package/typescript\",\"className\":\"group flex items-center justify-between rounded-md px-2 py-1.5 text-sm transition-colors hover:bg-accent\",\"children\":[[\"$\",\"span\",null,{\"className\":\"flex items-center gap-1.5 truncate font-mono text-foreground\",\"children\":[[\"$\",\"svg\",null,{\"ref\":\"$undefined\",\"xmlns\":\"http://www.w3.org/2000/svg\",\"width\":24,\"height\":24,\"viewBox\":\"0 0 24 24\",\"fill\":\"none\",\"stroke\":\"currentColor\",\"strokeWidth\":2,\"strokeLinecap\":\"round\",\"strokeLinejoin\":\"round\",\"className\":\"lucide lucide-chevron-right h-3 w-3 text-muted-foreground opacity-0 transition-opacity group-hover:opacity-100\",\"children\":[[\"$\",\"path\",\"mthhwq\",{\"d\":\"m9 18 6-6-6-6\"}],\"$undefined\"]}],\"typescript\"]}],\"$L2c\"]}]]}]}]\n"])</script><script>self.__next_f.push([1,"2c:[\"$\",\"span\",null,{\"className\":\"ml-2 shrink-0 font-mono text-xs text-muted-foreground\",\"children\":\"^5.3.0\"}]\n"])</script><div hidden id="S:3"><div data-state="inactive" data-orientation="horizontal" role="tabpanel" aria-labelledby="radix-_R_aav5ubrb_-trigger-dependencies" hidden="" id="radix-_R_aav5ubrb_-content-dependencies" tabindex="0" data-slot="tabs-content" class="flex-1 outline-none mt-6"></div></div><script>$RS=function(a,b){a=document.getElementById(a);b=document.getElementById(b);for(a.parentNode.removeChild(a);a.firstChild;)b.parentNode.insertBefore(a.firstChild,b);b.parentNode.removeChild(b)};$RS("S:3","P:3")</script><div hidden id="S:4"><div data-state="inactive" data-orientation="horizontal" role="tabpanel" aria-labelledby="radix-_R_aav5ubrb_-trigger-versions" hidden="" id="radix-_R_aav5ubrb_-content-versions" tabindex="0" data-slot="tabs-content" class="flex-1 outline-none mt-6"></div></div><script>$RS("S:4","P:4")</script><script>$RC("B:1","S:1")</script></body></html>