Skip to main content

---

title: Task Plan Sync Hook component_type: hook version: 1.0.0 audience: contributor status: active summary: Bidirectional sync between TodoWrite and Project Plan documents keywords:

  • sync
  • task-tracking
  • project-plan
  • todowrite
  • bidirectional tokens: ~3000 created: 2026-01-04 updated: 2026-01-04

Task Plan Sync - Keeps TodoWrite and Project Plan in Sync

This hook ensures that task status changes in TodoWrite are reflected in the project plan documents (PILOT-PARALLEL-EXECUTION-PLAN.md, tasklist.md) and vice versa.

Flow:

  1. TodoWrite marks [A.1.1] as completed
  2. Hook triggers on PostToolUse
  3. Finds A.1.1 in PILOT-PLAN.md
  4. Updates checkbox: [ ] → [x]
  5. Updates database task_tracking table
  6. Logs sync action

Configuration in .claude/settings.json: { "hooks": { "PostToolUse": [ { "matcher": "TodoWrite", "hooks": ["python3 hooks/task-plan-sync.py"] } ] } }

Usage: # As hook (automatic) # Triggered by TodoWrite tool

# Manual sync from plan to database
python3 hooks/task-plan-sync.py --sync-from-plan

# Show sync status
python3 hooks/task-plan-sync.py --status

File: task-plan-sync.py

Classes​

TaskPlanSync​

Bidirectional sync between TodoWrite and Project Plan.

Functions​

main()​

Main entry point.

get_db_connection()​

Get database connection if available.

find_plan_file()​

Find the first existing project plan file.

find_all_plan_files()​

Find ALL existing project plan files for sync.

parse_plan_tasks(plan_path)​

Parse tasks from project plan markdown.

update_plan_checkbox(plan_path, task_id, checked)​

Update a checkbox in the project plan.

sync_todo_to_plan(todos)​

Sync TodoWrite status to ALL project plan documents.

sync_to_database(todos)​

Sync todo status to database task_tracking table and cloud (A.9.3.2).

ensure_task_tracking_schema(conn)​

Ensure task_tracking table exists.

sync_from_plan()​

Sync project plan status to database (initial load).

get_sync_status()​

Get current sync status across all sources.

Usage​

python task-plan-sync.py