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

Homebrew (macOS/Linux)

brew tap farisphp/tap
brew install ctt

npm

npm install -g claude-task-tracker

From Source

git clone https://github.com/farisphp/claude-task-tracker.git
cd claude-task-tracker
npm install
npm run build
npm link

Quick Start

# 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 <title>	Add task (-d description, -b blockedBy, -r refs, -p planFile)
ctt list	List all tasks (-s filter by status)
ctt show <id>	Show task details
ctt next	Get next ready task (open + all blockers completed)
ctt start <id>	Mark as in progress
ctt complete <id>	Mark as completed (-o overview)
ctt block <id> --by <id>	Add blocking dependency
ctt unblock <id> --by <id>	Remove blocking dependency
ctt ref <id> --to <id>	Add soft reference
ctt unref <id> --to <id>	Remove soft reference
ctt context <id>	Show task + all dependency overviews
ctt overview <id> <text>	Update task overview
ctt plan <id> <path>	Set or update plan file reference
ctt delete <id>	Delete a task
ctt cleanup	Remove old completed tasks (-d days, default 7, --dry-run)

Output Formats

Default (Human-readable)

ctt list
# ○ t1 - Design API
# ○ t2 - Implement auth [blocked by: t1]
# ○ t3 - Write tests [blocked by: t2]

JSON (Structured)

ctt --json next

{
  "id": "t1",
  "title": "Design API",
  "status": "open",
  "blockedBy": [],
  "references": [],
  "overview": null
}

Compact (Token-efficient for LLMs)

ctt --compact list
# t1:Design API[O]
# t2:Implement auth[O] <t1
# t3:Write tests[O] <t2 ~t1

ctt --compact context t3
# t3:Write tests[O] <t2 ~t1
# --blockers--
# t2:Implement auth[O] <t1
# --refs--
# t1:Design API[C] >Created OpenAPI spec...

Compact format legend:

• [O] = open, [P] = progress, [C] = completed
• <t1,t2 = blocked by t1 and t2
• ~t1 = references t1
• >text = overview
• @path = plan file reference

Task States

Status	Symbol	Description
open	○ / O	Not started
progress	◐ / P	In progress
completed	● / C	Done

Agentic Workflow Example

# Agent picks up next task
TASK=$(ctt --compact next)
# t1:Design API[O]

# Agent starts working
ctt start t1

# Agent completes with context for future tasks
ctt complete t1 -o "Defined /users CRUD, /auth/login, /auth/refresh. Using JWT with 1h expiry."

# Agent picks up next task and gets context
ctt --compact context t2
# t2:Implement auth[O] <t1
# --blockers--
# t1:Design API[C] >Defined /users CRUD, /auth/login...

Storage

Tasks are stored in .tasks/tasks.json in the current directory. This file can be version-controlled.

License

MIT