TodoWrite Sync

Bidirectional synchronization between CLEO and Claude Code TodoWrite

TodoWrite Sync

CLEO provides bidirectional sync with Claude Code’s built-in TodoWrite tool, enabling seamless workflow between persistent CLEO tasks and ephemeral session tasks.

Why Sync?

CLEO (Persistent)

• Full metadata and history
• Survives sessions
• Hierarchies and dependencies
• Verification gates

TodoWrite (Ephemeral)

• Claude Code native
• Session-scoped
• Simplified format
• Immediate visibility

Use CLEO for durable task management, TodoWrite for real-time session tracking.

Sync Workflow

Injecting Tasks

At session start, export CLEO tasks to TodoWrite format:

All Active Tasks

cleo sync --inject

Exports pending/active tasks in current session scope.

Focused Task Only

cleo sync --inject --focused-only

Exports only the currently focused task.

Preview

cleo sync --inject --dry-run

Shows what would be exported without writing.

Working with TodoWrite

During your Claude Code session, use TodoWrite normally:

# Claude Code maintains its todo list
# Updates status, adds notes, marks complete

Changes made in TodoWrite are tracked for extraction.

Extracting Updates

At session end, merge TodoWrite state back to CLEO:

Extract Changes

cleo sync --extract

Sync Status

Check current sync state:

cleo sync --status

Returns:

• Last inject timestamp
• Last extract timestamp
• Pending changes count
• Conflict warnings

Handling Conflicts

When CLEO and TodoWrite have conflicting changes:

Status Conflicts

If TodoWrite marks a task complete but CLEO has it as blocked:

• Default: TodoWrite status wins (more recent)
• Override: --preserve-cleo-status to keep CLEO status

Missing Tasks

If a CLEO task is missing from TodoWrite:

• Default: Task remains unchanged in CLEO
• Override: --sync-deletions to mark as cancelled

New Tasks

If TodoWrite has tasks not in CLEO:

• Default: Tasks are created in CLEO
• Override: --ignore-new to skip creation

Best Practices

1. Inject at Session Start

   Always run cleo sync --inject before starting work

2. Extract Before Ending

   Run cleo sync --extract before cleo session end

3. Use Dry-Run First

   Preview changes with --dry-run to avoid surprises

4. One Direction at a Time

   Don’t inject and extract simultaneously

Session Protocol Integration

The sync workflow integrates with session protocol:

# START Phase
cleo session start --scope epic:T001 --auto-focus
cleo sync --inject

# WORK Phase
# ... work with Claude Code and TodoWrite ...

# END Phase
cleo sync --extract
cleo session end --note "Synced TodoWrite changes"

Export vs Sync

Feature	cleo export	cleo sync
Direction	One-way out	Bidirectional
Format	Multiple (CSV, JSON, MD)	TodoWrite only
Use case	Backup/reporting	Session integration
Preserves	Full metadata	Essential fields

Related

Commands: sync

Complete sync command reference

Sessions Guide

Session management workflows