Praison AI

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.

python
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.

Diagram

Planning Flow

👤 User Request

🤖 Agent

📋 Break Into Steps

📝 Create Todos

⚡ Execute Tasks

✅ Complete Items

Quick Start

  1. Agent with Planning
    python
    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.")
  2. Interactive Planning Flow
    python
    # 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

Diagram
📋 Todos🤖 Agent👤 User📋 Todos🤖 Agent👤 User“Plan a blog launch”todo_add(“research topic”)todo_add(“draft post”)todo_add(“publish”)todo_list()3 pending todostodo_update(1, status=”completed”)“Done ✅ — moving to drafting”

Todo persistence works through JSON storage with automatic workspace integration:

Storage LocationWhen UsedPurpose
<workspace>/todos.jsonBot with workspaceSession-isolated todos
~/.praisonai/todos.jsonAgent without workspaceGlobal todo storage
Memory onlyStateless modeNo persistence

Configuration Options

Todo Management Functions

FunctionArgsDescription
todo_addtask, priority="medium", category="general"Create new todo item
todo_liststatus="all", category=NoneList todos with filtering
todo_updatetodo_id, status, task, priorityUpdate existing todo

Priority Levels

python
# 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

python
# 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.

Category Organization

python
# 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

python
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

python
# 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

python
# 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