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