claude-task-tracker 1.0.0

package/README.md

@@ -0,0 +1,151 @@
+# 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
+- **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
+
+```bash
+# Clone and install
+cd claude-task-tracker
+npm install
+npm run build
+
+# Link globally to use 'ctt' anywhere
+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
+
+# 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) |
+| `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 delete <id>` | Delete a task |
+| `ctt cleanup` | Remove old completed tasks (`-d` days, default 7, `--dry-run`) |
+
+## Output Formats
+
+### Default (Human-readable)
+```bash
+ctt list
+# ○ t1 - Design API
+# ○ t2 - Implement auth [blocked by: t1]
+# ○ t3 - Write tests [blocked by: t2]
+```
+
+### JSON (Structured)
+```bash
+ctt --json next
+```
+```json
+{
+  "id": "t1",
+  "title": "Design API",
+  "status": "open",
+  "blockedBy": [],
+  "references": [],
+  "overview": null
+}
+```
+
+### Compact (Token-efficient for LLMs)
+```bash
+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
+
+## Task States
+
+| Status | Symbol | Description |
+|--------|--------|-------------|
+| `open` | ○ / O | Not started |
+| `progress` | ◐ / P | In progress |
+| `completed` | ● / C | Done |
+
+## Agentic Workflow Example
+
+```bash
+# 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

package/dist/index.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/index.js

@@ -0,0 +1,738 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { existsSync as existsSync2, readFileSync as readFileSync2, writeFileSync as writeFileSync2, appendFileSync } from "fs";
+import { join as join2 } from "path";
+import { Command } from "commander";
+
+// src/store/taskStore.ts
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { dirname, join } from "path";
+
+// src/models/task.ts
+function createTask(id, title, options = {}) {
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  return {
+    id,
+    title,
+    description: options.description,
+    status: "open",
+    blockedBy: options.blockedBy ?? [],
+    references: options.references ?? [],
+    overview: void 0,
+    createdAt: now,
+    updatedAt: now
+  };
+}
+function createEmptyStore() {
+  return {
+    version: "1.0.0",
+    nextId: 1,
+    tasks: []
+  };
+}
+
+// src/store/taskStore.ts
+var TASKS_DIR = ".tasks";
+var TASKS_FILE = "tasks.json";
+function getTasksPath(cwd = process.cwd()) {
+  return join(cwd, TASKS_DIR, TASKS_FILE);
+}
+function loadStore(cwd = process.cwd()) {
+  const path = getTasksPath(cwd);
+  if (!existsSync(path)) {
+    throw new Error('Task store not initialized. Run "ctt init" first.');
+  }
+  const data = readFileSync(path, "utf-8");
+  return JSON.parse(data);
+}
+function saveStore(store, cwd = process.cwd()) {
+  const path = getTasksPath(cwd);
+  const dir = dirname(path);
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+  writeFileSync(path, JSON.stringify(store, null, 2));
+}
+function initStore(cwd = process.cwd()) {
+  const path = getTasksPath(cwd);
+  if (existsSync(path)) {
+    throw new Error("Task store already exists.");
+  }
+  saveStore(createEmptyStore(), cwd);
+}
+function generateId(store) {
+  return `t${store.nextId}`;
+}
+function addTask(store, title, options = {}) {
+  const id = generateId(store);
+  const task = createTask(id, title, options);
+  store.tasks.push(task);
+  store.nextId++;
+  return task;
+}
+function getTask(store, id) {
+  return store.tasks.find((t) => t.id === id);
+}
+function updateTask(store, id, updates) {
+  const task = getTask(store, id);
+  if (!task) {
+    throw new Error(`Task ${id} not found.`);
+  }
+  Object.assign(task, updates, { updatedAt: (/* @__PURE__ */ new Date()).toISOString() });
+  return task;
+}
+function isTaskReady(store, task) {
+  if (task.status !== "open") {
+    return false;
+  }
+  for (const blockerId of task.blockedBy) {
+    const blocker = getTask(store, blockerId);
+    if (!blocker || blocker.status !== "completed") {
+      return false;
+    }
+  }
+  return true;
+}
+function getNextTask(store) {
+  return store.tasks.find((task) => isTaskReady(store, task));
+}
+function getBlockingTasks(store, task) {
+  return task.blockedBy.map((id) => getTask(store, id)).filter((t) => t !== void 0);
+}
+function getReferencedTasks(store, task) {
+  return task.references.map((id) => getTask(store, id)).filter((t) => t !== void 0);
+}
+
+// src/utils/display.ts
+var STATUS_ICONS = {
+  open: "\u25CB",
+  progress: "\u25D0",
+  completed: "\u25CF"
+};
+function formatStatus(status) {
+  return `${STATUS_ICONS[status] || "?"} ${status}`;
+}
+function formatTaskShort(task) {
+  const icon = STATUS_ICONS[task.status] || "?";
+  const blockers = task.blockedBy.length > 0 ? ` [blocked by: ${task.blockedBy.join(", ")}]` : "";
+  return `${icon} ${task.id} - ${task.title}${blockers}`;
+}
+function formatTaskDetail(task, store) {
+  const lines = [];
+  lines.push(`ID:          ${task.id}`);
+  lines.push(`Title:       ${task.title}`);
+  lines.push(`Status:      ${formatStatus(task.status)}`);
+  if (task.description) {
+    lines.push(`Description: ${task.description}`);
+  }
+  if (task.blockedBy.length > 0) {
+    lines.push(`Blocked by:  ${task.blockedBy.join(", ")}`);
+  }
+  if (task.references.length > 0) {
+    lines.push(`References:  ${task.references.join(", ")}`);
+  }
+  if (task.overview) {
+    lines.push(`Overview:    ${task.overview}`);
+  }
+  lines.push(`Created:     ${task.createdAt}`);
+  lines.push(`Updated:     ${task.updatedAt}`);
+  return lines.join("\n");
+}
+function formatContext(task, store) {
+  const lines = [];
+  lines.push("=== Current Task ===");
+  lines.push(formatTaskDetail(task, store));
+  const blockers = getBlockingTasks(store, task);
+  if (blockers.length > 0) {
+    lines.push("\n=== Blocking Dependencies ===");
+    for (const blocker of blockers) {
+      lines.push(`
+[${blocker.id}] ${blocker.title}`);
+      lines.push(`Status: ${formatStatus(blocker.status)}`);
+      if (blocker.overview) {
+        lines.push(`Overview: ${blocker.overview}`);
+      }
+    }
+  }
+  const refs = getReferencedTasks(store, task);
+  if (refs.length > 0) {
+    lines.push("\n=== Referenced Tasks ===");
+    for (const ref of refs) {
+      lines.push(`
+[${ref.id}] ${ref.title}`);
+      lines.push(`Status: ${formatStatus(ref.status)}`);
+      if (ref.overview) {
+        lines.push(`Overview: ${ref.overview}`);
+      }
+    }
+  }
+  return lines.join("\n");
+}
+function formatTaskJson(task) {
+  return JSON.stringify(task, null, 2);
+}
+function formatContextJson(task, store) {
+  const blockers = getBlockingTasks(store, task);
+  const refs = getReferencedTasks(store, task);
+  return JSON.stringify({
+    task,
+    blockingDependencies: blockers,
+    references: refs
+  }, null, 2);
+}
+var STATUS_SHORT = {
+  open: "O",
+  progress: "P",
+  completed: "C"
+};
+function formatTaskCompact(task) {
+  const parts = [`${task.id}:${task.title}[${STATUS_SHORT[task.status] || "?"}]`];
+  if (task.blockedBy.length > 0) {
+    parts.push(`<${task.blockedBy.join(",")}`);
+  }
+  if (task.references.length > 0) {
+    parts.push(`~${task.references.join(",")}`);
+  }
+  if (task.overview) {
+    parts.push(`>${task.overview}`);
+  }
+  return parts.join(" ");
+}
+function formatTasksCompact(tasks) {
+  return tasks.map(formatTaskCompact).join("\n");
+}
+function formatContextCompact(task, store) {
+  const lines = [];
+  lines.push(formatTaskCompact(task));
+  if (task.description) {
+    lines.push(`desc:${task.description}`);
+  }
+  const blockers = getBlockingTasks(store, task);
+  if (blockers.length > 0) {
+    lines.push("--blockers--");
+    for (const b of blockers) {
+      lines.push(formatTaskCompact(b));
+    }
+  }
+  const refs = getReferencedTasks(store, task);
+  if (refs.length > 0) {
+    lines.push("--refs--");
+    for (const r of refs) {
+      lines.push(formatTaskCompact(r));
+    }
+  }
+  return lines.join("\n");
+}
+
+// src/index.ts
+var program = new Command();
+program.name("ctt").description("CLI task tracker with dependency management for agentic code workflows").version("1.0.0");
+program.option("--json", "Output in JSON format");
+program.option("--compact", "Output in compact format (token-efficient for LLMs)");
+function getOutputFormat() {
+  const opts = program.opts();
+  if (opts.compact) return "compact";
+  if (opts.json) return "json";
+  return "default";
+}
+var CTT_CLAUDE_INSTRUCTIONS = `
+## Task Tracking with ctt
+
+This project uses \`ctt\` (Claude Task Tracker) for task management with dependencies.
+
+### Workflow
+1. Get the next ready task: \`ctt --compact next\`
+2. Start working on it: \`ctt start <id>\`
+3. When done, complete with overview: \`ctt complete <id> -o "summary of what was done"\`
+4. Get context for a task (includes dependency overviews): \`ctt --compact context <id>\`
+
+### Key Commands
+- \`ctt --compact list\` - List all tasks
+- \`ctt --compact next\` - Get next ready task (open + all blockers completed)
+- \`ctt --compact context <id>\` - Get task with dependency overviews
+- \`ctt add "title" -b <blocker-id>\` - Add task blocked by another
+- \`ctt complete <id> -o "overview"\` - Complete with context for dependent tasks
+
+### Compact Format
+- \`[O]\`/\`[P]\`/\`[C]\` = open/progress/completed
+- \`<t1,t2\` = blocked by tasks
+- \`~t1\` = references task
+- \`>text\` = overview
+`;
+function setupClaudeMd(cwd = process.cwd()) {
+  const claudeMdPath = join2(cwd, "CLAUDE.md");
+  const marker = "## Task Tracking with ctt";
+  if (!existsSync2(claudeMdPath)) {
+    writeFileSync2(claudeMdPath, CTT_CLAUDE_INSTRUCTIONS.trim() + "\n");
+    return { created: true, appended: false };
+  }
+  const content = readFileSync2(claudeMdPath, "utf-8");
+  if (content.includes(marker)) {
+    return { created: false, appended: false };
+  }
+  appendFileSync(claudeMdPath, "\n" + CTT_CLAUDE_INSTRUCTIONS);
+  return { created: false, appended: true };
+}
+program.command("init").description("Initialize task store and setup CLAUDE.md").action(() => {
+  try {
+    initStore();
+    console.log("Initialized task store in .tasks/tasks.json");
+    const { created, appended } = setupClaudeMd();
+    if (created) {
+      console.log("Created CLAUDE.md with ctt instructions");
+    } else if (appended) {
+      console.log("Appended ctt instructions to CLAUDE.md");
+    } else {
+      console.log("CLAUDE.md already has ctt instructions");
+    }
+  } catch (err) {
+    console.error(err.message);
+    process.exit(1);
+  }
+});
+program.command("add <title>").description("Add a new task").option("-d, --description <desc>", "Task description").option("-b, --blocked-by <ids>", "Comma-separated IDs of blocking tasks").option("-r, --ref <ids>", "Comma-separated IDs of referenced tasks").action((title, options) => {
+  try {
+    const store = loadStore();
+    const blockedBy = options.blockedBy ? options.blockedBy.split(",").map((s) => s.trim()) : [];
+    const references = options.ref ? options.ref.split(",").map((s) => s.trim()) : [];
+    for (const id of [...blockedBy, ...references]) {
+      if (!getTask(store, id)) {
+        console.error(`Task ${id} not found.`);
+        process.exit(1);
+      }
+    }
+    const task = addTask(store, title, {
+      description: options.description,
+      blockedBy,
+      references
+    });
+    saveStore(store);
+    const fmt = getOutputFormat();
+    if (fmt === "json") {
+      console.log(formatTaskJson(task));
+    } else if (fmt === "compact") {
+      console.log(formatTaskCompact(task));
+    } else {
+      console.log(`Created task: ${formatTaskShort(task)}`);
+    }
+  } catch (err) {
+    console.error(err.message);
+    process.exit(1);
+  }
+});
+program.command("list").description("List all tasks").option("-s, --status <status>", "Filter by status (open, progress, completed)").action((options) => {
+  try {
+    const store = loadStore();
+    let tasks = store.tasks;
+    if (options.status) {
+      tasks = tasks.filter((t) => t.status === options.status);
+    }
+    const fmt = getOutputFormat();
+    if (fmt === "json") {
+      console.log(JSON.stringify(tasks, null, 2));
+    } else if (fmt === "compact") {
+      if (tasks.length === 0) {
+        console.log("none");
+      } else {
+        console.log(formatTasksCompact(tasks));
+      }
+    } else {
+      if (tasks.length === 0) {
+        console.log("No tasks found.");
+      } else {
+        for (const task of tasks) {
+          console.log(formatTaskShort(task));
+        }
+      }
+    }
+  } catch (err) {
+    console.error(err.message);
+    process.exit(1);
+  }
+});
+program.command("show <id>").description("Show task details").action((id) => {
+  try {
+    const store = loadStore();
+    const task = getTask(store, id);
+    if (!task) {
+      console.error(`Task ${id} not found.`);
+      process.exit(1);
+    }
+    const fmt = getOutputFormat();
+    if (fmt === "json") {
+      console.log(formatTaskJson(task));
+    } else if (fmt === "compact") {
+      console.log(formatTaskCompact(task));
+    } else {
+      console.log(formatTaskDetail(task, store));
+    }
+  } catch (err) {
+    console.error(err.message);
+    process.exit(1);
+  }
+});
+program.command("next").description("Get the next ready task (open with all blockers completed)").action(() => {
+  try {
+    const store = loadStore();
+    const task = getNextTask(store);
+    const fmt = getOutputFormat();
+    if (!task) {
+      if (fmt === "json") {
+        console.log(JSON.stringify(null));
+      } else if (fmt === "compact") {
+        console.log("none");
+      } else {
+        console.log("No ready tasks available.");
+      }
+      return;
+    }
+    if (fmt === "json") {
+      console.log(formatTaskJson(task));
+    } else if (fmt === "compact") {
+      console.log(formatTaskCompact(task));
+    } else {
+      console.log(formatTaskShort(task));
+    }
+  } catch (err) {
+    console.error(err.message);
+    process.exit(1);
+  }
+});
+program.command("start <id>").description("Mark a task as in progress").action((id) => {
+  try {
+    const store = loadStore();
+    const task = getTask(store, id);
+    if (!task) {
+      console.error(`Task ${id} not found.`);
+      process.exit(1);
+    }
+    if (task.status === "completed") {
+      console.error(`Task ${id} is already completed.`);
+      process.exit(1);
+    }
+    updateTask(store, id, { status: "progress" });
+    saveStore(store);
+    const fmt = getOutputFormat();
+    const updated = getTask(store, id);
+    if (fmt === "json") {
+      console.log(formatTaskJson(updated));
+    } else if (fmt === "compact") {
+      console.log(formatTaskCompact(updated));
+    } else {
+      console.log(`Started: ${formatTaskShort(updated)}`);
+    }
+  } catch (err) {
+    console.error(err.message);
+    process.exit(1);
+  }
+});
+program.command("complete <id>").description("Mark a task as completed").option("-o, --overview <text>", "Overview/summary of what was accomplished").action((id, options) => {
+  try {
+    const store = loadStore();
+    const task = getTask(store, id);
+    if (!task) {
+      console.error(`Task ${id} not found.`);
+      process.exit(1);
+    }
+    if (task.status === "completed") {
+      console.error(`Task ${id} is already completed.`);
+      process.exit(1);
+    }
+    const updates = { status: "completed" };
+    if (options.overview) {
+      updates.overview = options.overview;
+    }
+    updateTask(store, id, updates);
+    saveStore(store);
+    const fmt = getOutputFormat();
+    const updated = getTask(store, id);
+    if (fmt === "json") {
+      console.log(formatTaskJson(updated));
+    } else if (fmt === "compact") {
+      console.log(formatTaskCompact(updated));
+    } else {
+      console.log(`Completed: ${formatTaskShort(updated)}`);
+      if (!options.overview) {
+        console.log("Tip: Use -o to add an overview for dependent tasks.");
+      }
+    }
+  } catch (err) {
+    console.error(err.message);
+    process.exit(1);
+  }
+});
+program.command("block <id>").description("Add a blocking dependency").requiredOption("--by <blocker-id>", "ID of the blocking task").action((id, options) => {
+  try {
+    const store = loadStore();
+    const task = getTask(store, id);
+    if (!task) {
+      console.error(`Task ${id} not found.`);
+      process.exit(1);
+    }
+    const blocker = getTask(store, options.by);
+    if (!blocker) {
+      console.error(`Blocker task ${options.by} not found.`);
+      process.exit(1);
+    }
+    if (task.blockedBy.includes(options.by)) {
+      console.error(`Task ${id} is already blocked by ${options.by}.`);
+      process.exit(1);
+    }
+    if (blocker.blockedBy.includes(id)) {
+      console.error(`Circular dependency: ${options.by} is already blocked by ${id}.`);
+      process.exit(1);
+    }
+    task.blockedBy.push(options.by);
+    updateTask(store, id, { blockedBy: task.blockedBy });
+    saveStore(store);
+    if (program.opts().json) {
+      console.log(formatTaskJson(getTask(store, id)));
+    } else {
+      console.log(`Added blocker: ${id} is now blocked by ${options.by}`);
+    }
+  } catch (err) {
+    console.error(err.message);
+    process.exit(1);
+  }
+});
+program.command("unblock <id>").description("Remove a blocking dependency").requiredOption("--by <blocker-id>", "ID of the blocking task to remove").action((id, options) => {
+  try {
+    const store = loadStore();
+    const task = getTask(store, id);
+    if (!task) {
+      console.error(`Task ${id} not found.`);
+      process.exit(1);
+    }
+    const idx = task.blockedBy.indexOf(options.by);
+    if (idx === -1) {
+      console.error(`Task ${id} is not blocked by ${options.by}.`);
+      process.exit(1);
+    }
+    task.blockedBy.splice(idx, 1);
+    updateTask(store, id, { blockedBy: task.blockedBy });
+    saveStore(store);
+    if (program.opts().json) {
+      console.log(formatTaskJson(getTask(store, id)));
+    } else {
+      console.log(`Removed blocker: ${id} is no longer blocked by ${options.by}`);
+    }
+  } catch (err) {
+    console.error(err.message);
+    process.exit(1);
+  }
+});
+program.command("ref <id>").description("Add a soft reference to another task").requiredOption("--to <ref-id>", "ID of the task to reference").action((id, options) => {
+  try {
+    const store = loadStore();
+    const task = getTask(store, id);
+    if (!task) {
+      console.error(`Task ${id} not found.`);
+      process.exit(1);
+    }
+    const refTask = getTask(store, options.to);
+    if (!refTask) {
+      console.error(`Reference task ${options.to} not found.`);
+      process.exit(1);
+    }
+    if (task.references.includes(options.to)) {
+      console.error(`Task ${id} already references ${options.to}.`);
+      process.exit(1);
+    }
+    task.references.push(options.to);
+    updateTask(store, id, { references: task.references });
+    saveStore(store);
+    if (program.opts().json) {
+      console.log(formatTaskJson(getTask(store, id)));
+    } else {
+      console.log(`Added reference: ${id} now references ${options.to}`);
+    }
+  } catch (err) {
+    console.error(err.message);
+    process.exit(1);
+  }
+});
+program.command("unref <id>").description("Remove a soft reference").requiredOption("--to <ref-id>", "ID of the reference to remove").action((id, options) => {
+  try {
+    const store = loadStore();
+    const task = getTask(store, id);
+    if (!task) {
+      console.error(`Task ${id} not found.`);
+      process.exit(1);
+    }
+    const idx = task.references.indexOf(options.to);
+    if (idx === -1) {
+      console.error(`Task ${id} does not reference ${options.to}.`);
+      process.exit(1);
+    }
+    task.references.splice(idx, 1);
+    updateTask(store, id, { references: task.references });
+    saveStore(store);
+    if (program.opts().json) {
+      console.log(formatTaskJson(getTask(store, id)));
+    } else {
+      console.log(`Removed reference: ${id} no longer references ${options.to}`);
+    }
+  } catch (err) {
+    console.error(err.message);
+    process.exit(1);
+  }
+});
+program.command("overview <id> <text>").description("Set or update task overview").action((id, text) => {
+  try {
+    const store = loadStore();
+    const task = getTask(store, id);
+    if (!task) {
+      console.error(`Task ${id} not found.`);
+      process.exit(1);
+    }
+    updateTask(store, id, { overview: text });
+    saveStore(store);
+    if (program.opts().json) {
+      console.log(formatTaskJson(getTask(store, id)));
+    } else {
+      console.log(`Updated overview for ${id}`);
+    }
+  } catch (err) {
+    console.error(err.message);
+    process.exit(1);
+  }
+});
+program.command("context <id>").description("Show task with all dependency overviews for quick context lookup").action((id) => {
+  try {
+    const store = loadStore();
+    const task = getTask(store, id);
+    if (!task) {
+      console.error(`Task ${id} not found.`);
+      process.exit(1);
+    }
+    const fmt = getOutputFormat();
+    if (fmt === "json") {
+      console.log(formatContextJson(task, store));
+    } else if (fmt === "compact") {
+      console.log(formatContextCompact(task, store));
+    } else {
+      console.log(formatContext(task, store));
+    }
+  } catch (err) {
+    console.error(err.message);
+    process.exit(1);
+  }
+});
+program.command("delete <id>").description("Delete a task").action((id) => {
+  try {
+    const store = loadStore();
+    const task = getTask(store, id);
+    if (!task) {
+      console.error(`Task ${id} not found.`);
+      process.exit(1);
+    }
+    const dependents = store.tasks.filter(
+      (t) => t.blockedBy.includes(id) || t.references.includes(id)
+    );
+    if (dependents.length > 0) {
+      console.error(
+        `Cannot delete ${id}: it is referenced by ${dependents.map((t) => t.id).join(", ")}`
+      );
+      process.exit(1);
+    }
+    store.tasks = store.tasks.filter((t) => t.id !== id);
+    saveStore(store);
+    if (program.opts().json) {
+      console.log(JSON.stringify({ deleted: id }));
+    } else {
+      console.log(`Deleted task ${id}`);
+    }
+  } catch (err) {
+    console.error(err.message);
+    process.exit(1);
+  }
+});
+program.command("cleanup").description("Remove completed tasks older than specified days").option("-d, --days <days>", "Minimum age in days for completed tasks to be removed", "7").option("--dry-run", "Show what would be removed without actually removing").action((options) => {
+  try {
+    const store = loadStore();
+    const days = parseInt(options.days, 10);
+    if (isNaN(days) || days < 0) {
+      console.error("Invalid days value. Must be a non-negative number.");
+      process.exit(1);
+    }
+    const cutoffDate = /* @__PURE__ */ new Date();
+    cutoffDate.setDate(cutoffDate.getDate() - days);
+    const candidates = store.tasks.filter((t) => {
+      if (t.status !== "completed") return false;
+      const updatedAt = new Date(t.updatedAt);
+      return updatedAt < cutoffDate;
+    });
+    const toRemove = [];
+    const skipped = [];
+    for (const task of candidates) {
+      const dependents = store.tasks.filter(
+        (t) => t.status !== "completed" && (t.blockedBy.includes(task.id) || t.references.includes(task.id))
+      );
+      if (dependents.length > 0) {
+        skipped.push({
+          task,
+          reason: `referenced by: ${dependents.map((d) => d.id).join(", ")}`
+        });
+      } else {
+        toRemove.push(task);
+      }
+    }
+    const fmt = getOutputFormat();
+    if (options.dryRun) {
+      if (fmt === "json") {
+        console.log(JSON.stringify({ wouldRemove: toRemove, skipped }, null, 2));
+      } else if (fmt === "compact") {
+        if (toRemove.length === 0) {
+          console.log("none to remove");
+        } else {
+          console.log("would remove:");
+          console.log(formatTasksCompact(toRemove));
+        }
+        if (skipped.length > 0) {
+          console.log("skipped:");
+          for (const { task, reason } of skipped) {
+            console.log(`${task.id}:${task.title} (${reason})`);
+          }
+        }
+      } else {
+        if (toRemove.length === 0) {
+          console.log("No tasks to remove.");
+        } else {
+          console.log("Would remove:");
+          for (const task of toRemove) {
+            console.log(`  ${formatTaskShort(task)}`);
+          }
+        }
+        if (skipped.length > 0) {
+          console.log("\nSkipped (still referenced):");
+          for (const { task, reason } of skipped) {
+            console.log(`  ${task.id} - ${task.title} (${reason})`);
+          }
+        }
+      }
+      return;
+    }
+    const removedIds = toRemove.map((t) => t.id);
+    store.tasks = store.tasks.filter((t) => !removedIds.includes(t.id));
+    saveStore(store);
+    if (fmt === "json") {
+      console.log(JSON.stringify({ removed: removedIds, skipped }, null, 2));
+    } else if (fmt === "compact") {
+      console.log(`removed:${removedIds.length > 0 ? removedIds.join(",") : "none"}`);
+    } else {
+      if (removedIds.length === 0) {
+        console.log("No tasks removed.");
+      } else {
+        console.log(`Removed ${removedIds.length} task(s): ${removedIds.join(", ")}`);
+      }
+      if (skipped.length > 0) {
+        console.log(`Skipped ${skipped.length} task(s) (still referenced by open tasks)`);
+      }
+    }
+  } catch (err) {
+    console.error(err.message);
+    process.exit(1);
+  }
+});
+program.parse();

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "claude-task-tracker",
+  "version": "1.0.0",
+  "description": "CLI task tracker with dependency management for agentic code workflows",
+  "type": "module",
+  "bin": {
+    "ctt": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "build:binary": "npm run build && pkg dist/index.js --targets node20-macos-arm64,node20-macos-x64,node20-linux-x64,node20-win-x64 --output bin/ctt",
+    "dev": "tsx src/index.ts",
+    "start": "node dist/index.js",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "cli",
+    "task-tracker",
+    "agentic",
+    "claude",
+    "claude-code",
+    "ai",
+    "llm",
+    "task-management",
+    "dependencies"
+  ],
+  "author": "farisphp",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/farisphp/claude-task-tracker.git"
+  },
+  "bugs": {
+    "url": "https://github.com/farisphp/claude-task-tracker/issues"
+  },
+  "homepage": "https://github.com/farisphp/claude-task-tracker#readme",
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "@types/node": "^20.10.0",
+    "@yao-pkg/pkg": "^5.11.0",
+    "tsup": "^8.0.1",
+    "tsx": "^4.7.0",
+    "typescript": "^5.3.0"
+  },
+  "dependencies": {
+    "commander": "^12.0.0"
+  }
+}