Todo Write

Creates and manages a structured task list for tracking progress with status tracking, priority levels, and persistence.

Common Properties

Name - The custom name of the node.
Color - The custom color of the node.
Delay Before (sec) - Waits in seconds before executing the node.
Delay After (sec) - Waits in seconds after executing node.
Continue On Error - Automation will continue regardless of any error. The default value is false.

Inputs

Todos - array - Array of todo items (required). Each todo must have:
- content (string, required) - Description of the todo item
- status (string, optional) - Status: "pending", "in_progress", or "completed" (default: "pending")
- priority (string, optional) - Priority: "high", "medium", or "low" (default: "medium")
- id (string, optional) - Unique identifier (auto-generated if not provided)
- created (string, optional) - Creation timestamp (ISO 8601)
- updated (string, optional) - Last update timestamp (ISO 8601)
Persist Path - string - File path to persist todos as JSON (optional).

Options

Auto Generate IDs - bool - Automatically generate IDs for todos without them (default: true).
Validate Only - bool - Only validate todos without persisting (default: false).
Sort By - Sort todos by: Priority, Status, ID, or Content (default: Priority).
Max Todos - int - Maximum number of todos allowed (default: 100).

Outputs

Todos - array - Processed and validated todos array with all fields populated.
Todo Count - int - Total number of todos.
Status Counts - object - Count of todos by status:
- pending - Number of pending todos
- in_progress - Number of in-progress todos
- completed - Number of completed todos
Operation Info - object - Information about the operation:
- operation - Always "process_todos"
- validateOnly - Whether validation-only mode was used
- autoID - Whether IDs were auto-generated
- sortBy - Sort criteria used
- totalProcessed - Number of todos processed
- statusCounts - Status breakdown
- timestamp - Operation timestamp
- persistPath - Path where todos were saved (if applicable)
- persistSuccess - Whether persistence succeeded
- persistError - Error message if persistence failed

How It Works

The Todo Write node manages structured task lists. When executed, the node:

Validates the todos array format
Parses each todo item:
- Validates required content field
- Validates status (pending/in_progress/completed)
- Validates priority (high/medium/low)
- Extracts optional id and timestamps
Processes todos:
- Generates IDs for todos without them (if autoID enabled)
- Checks for duplicate IDs
- Sets created timestamp if not provided
- Updates updated timestamp
Sorts todos based on sort criteria
Calculates status counts
If persist path provided:
- Creates TodoList structure with metadata
- Writes to JSON file atomically
Returns processed todos and statistics

Requirements

Valid todos array with at least one item
Each todo must have non-empty content
Status values must be: pending, in_progress, or completed
Priority values must be: high, medium, or low
IDs must be unique within the list
Persist path must be absolute (if provided)
Maximum todos limit (default 100, max 1000)

Error Handling

The node will return specific errors in the following cases:

Missing todos - "Todos array is required"
Invalid format - "Invalid todos format: {{error}}"
Too many todos - "Too many todos: {{N}} (max: {{max}})"
Missing content - "Todo {{N}}: content is required and must be a non-empty string"
Invalid status - "Todo {{N}}: invalid status: {{status}} (must be pending, in_progress, or completed)"
Invalid priority - "Todo {{N}}: invalid priority: {{priority}} (must be high, medium, or low)"
Missing ID - "Todo {{N}}: ID is required when autoID is disabled"
Duplicate ID - "Duplicate todo ID: {{id}}"
Processing failed - "Failed to process todos: {{error}}"
Persist error - Included in Operation Info as persistError field

Usage Examples

Basic Todo List

Todos: [
  {
    "content": "Implement user authentication",
    "status": "in_progress",
    "priority": "high"
  },
  {
    "content": "Write unit tests",
    "status": "pending",
    "priority": "medium"
  },
  {
    "content": "Update documentation",
    "status": "completed",
    "priority": "low"
  }
]

With Custom IDs

Todos: [
  {
    "id": "task-001",
    "content": "Database migration",
    "status": "pending",
    "priority": "high"
  },
  {
    "id": "task-002",
    "content": "API optimization",
    "status": "in_progress",
    "priority": "medium"
  }
]

Persist to File

Todos: [...]
Persist Path: /home/user/project/todos.json

Validation Only

Todos: [...]
Validate Only: true

Sorting Options

Sort by Priority

High priority todos first, then medium, then low.

Sort by Status

In-progress first, then pending, then completed.

Sort by ID

Alphabetical order by ID.

Sort by Content

Alphabetical order by content text.

Persistence Format

When persisted to file, the JSON structure includes:

{
  "todos": [
    {
      "id": "uuid-here",
      "content": "Task description",
      "status": "pending",
      "priority": "medium",
      "created": "2024-01-15T10:30:00Z",
      "updated": "2024-01-15T10:30:00Z"
    }
  ],
  "metadata": {
    "created": "2024-01-15T10:30:00Z",
    "updated": "2024-01-15T10:30:00Z",
    "version": "1.0",
    "totalCount": 1,
    "statusCounts": {
      "pending": 1,
      "in_progress": 0,
      "completed": 0
    }
  }
}

Usage Notes

IDs are automatically generated as UUIDs if not provided
Timestamps use ISO 8601 format
Persistence uses atomic writes (temp file + rename)
Parent directories are created if they don't exist
Sort order is stable (preserves input order for equal items)
Validation checks happen before any persistence
Status counts are always calculated even without persistence
Max todos limit prevents memory issues

Common Use Cases

Project Task Management

Track development tasks with priorities and status.

Workflow Automation

Generate and track automated workflow steps.

Progress Tracking

Monitor progress of long-running automation processes.

Issue Tracking

Create simple issue lists with status tracking.

Checklist Management

Manage procedural checklists with completion tracking.

Development Sprints

Track sprint tasks with priorities.

Best Practices

Use descriptive content for clear task identification
Set appropriate priorities to focus on important tasks
Update status regularly to track progress
Persist to file for durability across sessions
Use custom IDs for tasks that need stable references
Sort by status to see active tasks first
Validate first with validateOnly before persistence
Check status counts to monitor overall progress
Set reasonable max todos based on use case

Example Workflows

Daily Task List

1. Todo Write:
   - Create morning task list
   - Sort by priority
   - Persist to daily_todos.json

2. Throughout day:
   - Read persisted todos
   - Update status as tasks complete
   - Todo Write: save updates

3. End of day:
   - Read todos
   - Review status counts
   - Archive or rollover pending items

Automated Testing Checklist

1. Generate test todos:
   - Content: test descriptions
   - Status: pending
   - Priority: based on criticality

2. For each test:
   - Run test
   - Update status to in_progress
   - If passed: status = completed
   - If failed: status = pending, priority = high
   - Todo Write: update list

3. Final report:
   - Check status counts
   - Report completion rate

Project Planning

1. Todo Write:
   - Create project task list
   - Set priorities
   - Sort by priority
   - Persist to project_plan.json

2. Regular updates:
   - Read current todos
   - Update status based on progress
   - Add new tasks as discovered
   - Todo Write: save changes

3. Review:
   - Analyze status counts
   - Track velocity
   - Adjust priorities

Comparison with Other Nodes

Todo Write vs Write: Todo Write manages structured todos; Write saves plain text/data
Todo Write vs Read: Todo Write creates/updates todos; Read retrieves file content
Todo Write vs Notebook: Todo Write tracks tasks; Notebook tracks code and analysis

Common Properties​

Inputs​

Options​

Outputs​

How It Works​

Requirements​

Error Handling​

Usage Examples​

Basic Todo List​

With Custom IDs​

Persist to File​

Validation Only​

Sorting Options​

Sort by Priority​

Sort by Status​

Sort by ID​

Sort by Content​

Persistence Format​

Usage Notes​

Common Use Cases​

Project Task Management​

Workflow Automation​

Progress Tracking​

Issue Tracking​

Checklist Management​

Development Sprints​

Best Practices​

Example Workflows​

Daily Task List​

Automated Testing Checklist​

Project Planning​

Comparison with Other Nodes​