Todo Planning

Let agents plan multi-step tasks with a persistent todo list

Todo planning enables agents to break complex tasks into manageable steps, track progress, and maintain persistent task lists across sessions.

from praisonaiagents import Agent

agent = Agent(
    name="Planner",
    instructions="Break tasks into todos, then execute them one by one.",
    tools=["todo_add", "todo_list", "todo_update"],
)
agent.start("Plan a blog launch — research, draft, publish.")

The user gives a multi-step goal; the agent breaks it into todos, tracks progress, and executes items in order.

​

Quick Start

1. Agent with Planning

   from praisonaiagents import Agent
   
   agent = Agent(
       name="Planner",
       instructions="Break tasks into todos, then execute them one by one.",
       tools=["todo_add", "todo_list", "todo_update"]
   )
   
   agent.start("Plan a blog launch — research, draft, publish.")
   

   todo_add, todo_list, todo_update resolve by name. Use tools=["todo_add", "todo_list", "todo_update"] in Python/YAML, --tools todo_add,todo_list,todo_update from the CLI, or grab them together with the coding workflow via toolsets=["coding"].

2. Interactive Planning Flow

   # User: "Plan a blog launch"
   # Agent automatically:
   # 1. Calls todo_add("research blog topic", priority="high")  
   # 2. Calls todo_add("draft blog post", priority="medium")
   # 3. Calls todo_add("publish to website", priority="medium")
   # 4. Calls todo_list() to review plan
   # 5. Updates todos as tasks complete
   

---

​

How It Works

Todo persistence works through JSON storage with automatic workspace integration:

Storage Location	When Used	Purpose
<workspace>/todos.json	Bot with workspace	Session-isolated todos
~/.praisonai/todos.json	Agent without workspace	Global todo storage
Memory only	Stateless mode	No persistence

If you persist plans or todo lists with PlanStorage, any name you pass — even one an LLM chose — stays inside the storage directory. Ordinary names keep their exact filename; only path separators, reserved characters, and a leading . are percent-encoded. See Safe Storage Names.

---

​

Configuration Options

​

Todo Management Functions

Function	Args	Description
todo_add	task, priority="medium", category="general"	Create new todo item
todo_list	status="all", category=None	List todos with filtering
todo_update	todo_id, status, task, priority	Update existing todo

​

Priority Levels

# Priority affects planning order but not execution
todo_add("critical bug fix", priority="high")      # First priority
todo_add("update docs", priority="medium")          # Standard priority  
todo_add("cleanup code", priority="low")            # Background task

​

Status Values

# Todo lifecycle management
todo_update(1, status="pending")       # Default state
todo_update(2, status="in_progress")   # Actively working on it (exactly one at a time)
todo_update(3, status="completed")     # Task finished
todo_update(4, status="cancelled")     # Task abandoned

Setting a todo to in_progress demotes any other in_progress item back to pending, so exactly one item is active at a time.

Subscribe to the TODO_UPDATED stream event to render a live checklist that ticks off in real time. See Live Todo Streaming.

​

Category Organization

# Organize todos by type
todo_add("research framework", category="development")
todo_add("schedule meeting", category="coordination") 
todo_add("write tests", category="quality")

# Filter by category
todo_list(category="development")  # Development tasks only

---

​

Common Patterns

​

Multi-Step Project Planning

agent = Agent(
    name="Project Manager",
    instructions="""
    For complex projects:
    1. Break into logical phases using todo_add
    2. Set appropriate priorities (high/medium/low)
    3. Use categories for organization
    4. Update status as work progresses
    """,
    tools=["todo_add", "todo_list", "todo_update"]
)

# User: "Plan a website redesign project"
# Agent creates:
# todo_add("analyze current site", priority="high", category="research")
# todo_add("design mockups", priority="high", category="design")
# todo_add("develop frontend", priority="medium", category="development")
# todo_add("user testing", priority="medium", category="testing")
# todo_add("deploy to production", priority="low", category="deployment")

​

Progress Tracking

# Agent updates todos as work completes
todo_update(1, status="completed")  # Research finished
todo_list(status="pending")         # Show remaining work
todo_add("implement user feedback", priority="high")  # Add new task

​

Category-Based Workflow

# Focus on specific work types
todo_list(category="development")   # Development tasks
todo_list(category="research")      # Research tasks  
todo_list(status="completed")       # Review finished work

---

​

Best Practices

Granular Task Breakdown

Create specific, actionable todo items rather than vague goals. “Write user authentication tests” is better than “test the app”.

Priority-Driven Planning

Use priority levels to guide task ordering. High-priority items should address critical blockers or dependencies.

Category Organization

Group related todos by category to maintain clear project structure and enable focused work sessions.

Progress Discipline

Update todo status promptly as work completes. This maintains accurate project visibility and planning momentum.

---

​

Related

Live Todo Streaming

Render a live checklist that ticks off in real time via TODO_UPDATED

Self-Improving Skills

How todo planning combines with skill creation

Workspace

Todo storage within workspace boundaries

Toolsets

Get todos + file edits + code search + shell in one line with toolsets=["coding"]

Safe Storage Names

Named todo lists stay inside the storage directory