Todo - PraisonAI

The todo command and --todo flag help you manage task lists and automatically generate todos from agent responses.

Install requirement: praisonai todo requires pip install praisonai (the full wrapper). On a standalone pip install praisonai-code install every todo subcommand exits 1 with todo requires the full wrapper. Install the full wrapper: pip install praisonai — a single-line hint, no Rich traceback (PR #2854).

Quick Start

# List all todos
praisonai todo list

# Generate todo from task
praisonai "Plan the project" --todo

# Add a todo manually
praisonai todo add "Implement feature X"

Commands

Add Todo

praisonai todo add "Implement user authentication"

# Set a priority (as of PraisonAI PR #4946, -p/--priority is honoured)
praisonai todo add "Ship the release" --priority high
praisonai todo add "Tidy up docs" -p low

Expected Output:

✅ Added: Implement user authentication

📋 Todo List:
--------------------------------------------------
  1. ⬜ 🟡 Implement user authentication
--------------------------------------------------
  0/1 completed

Flag	Short	Values	Default	Description
`--priority`	`-p`	`low`, `medium`, `high`	`medium`	Priority for the new todo. `high` → 🔴, `medium` → 🟡, `low` → 🟢. Unknown values are rejected.

List Todos

praisonai todo list

Expected Output:

📋 Todo List:
--------------------------------------------------
  1. ⬜ 🔴 Fix critical bug in payment system
  2. ⬜ 🟡 Implement user authentication
  3. ⬜ 🟡 Write API documentation
  4. ✅ 🟢 Set up CI/CD pipeline
  5. ⬜ 🟢 Add unit tests
--------------------------------------------------
  1/5 completed

Legend: 🔴 High  🟡 Medium  🟢 Low
        ⬜ Pending  ✅ Completed

Complete Todo

praisonai todo complete 2

Expected Output:

✅ Completed: Implement user authentication

📋 Todo List:
--------------------------------------------------
  1. ⬜ 🔴 Fix critical bug in payment system
  2. ✅ 🟡 Implement user authentication
  3. ⬜ 🟡 Write API documentation
  4. ✅ 🟢 Set up CI/CD pipeline
  5. ⬜ 🟢 Add unit tests
--------------------------------------------------
  2/5 completed

Delete Todo

praisonai todo delete 3

Expected Output:

🗑️  Deleted: Write API documentation

📋 Todo List:
--------------------------------------------------
  1. ⬜ 🔴 Fix critical bug in payment system
  2. ✅ 🟡 Implement user authentication
  3. ✅ 🟢 Set up CI/CD pipeline
  4. ⬜ 🟢 Add unit tests
--------------------------------------------------
  2/4 completed

Clear Todos

praisonai todo clear

Expected Output:

⚠️  Clear all todos? (y/N): y

🗑️  All todos cleared.

Help

praisonai todo help

Expected Output:

Todo Commands:

  praisonai todo add <task>       - Add a new todo item
  praisonai todo list             - List all todos
  praisonai todo complete <id>    - Mark todo as complete
  praisonai todo delete <id>      - Delete a todo
  praisonai todo clear            - Clear all todos
  praisonai todo help             - Show this help

Using --todo Flag:
  praisonai "task" --todo         - Generate todos from response

Using —todo Flag

Generate Todos from Task

praisonai "Plan the implementation of a REST API" --todo

Expected Output:

╭─ Agent Info ─────────────────────────────────────────────────────────────────╮
│  👤 Agent: DirectAgent                                                       │
│  Role: Assistant                                                             │
│  📋 Todo Generation: Enabled                                                │
╰──────────────────────────────────────────────────────────────────────────────╯

╭────────────────────────────────── Response ──────────────────────────────────╮
│ Here's a plan for implementing the REST API:                                 │
│                                                                              │
│ 1. Design the API schema and endpoints                                       │
│ 2. Set up the project structure                                              │
│ 3. Implement authentication middleware                                       │
│ 4. Create CRUD endpoints for resources                                       │
│ 5. Add input validation                                                      │
│ 6. Implement error handling                                                  │
│ 7. Write unit tests                                                          │
│ 8. Add API documentation                                                     │
╰──────────────────────────────────────────────────────────────────────────────╯

📋 Generated Todos:
--------------------------------------------------
  1. ⬜ 🟡 Design the API schema and endpoints
  2. ⬜ 🟡 Set up the project structure
  3. ⬜ 🟡 Implement authentication middleware
  4. ⬜ 🟡 Create CRUD endpoints for resources
  5. ⬜ 🟡 Add input validation
  6. ⬜ 🟡 Implement error handling
  7. ⬜ 🟢 Write unit tests
  8. ⬜ 🟢 Add API documentation
--------------------------------------------------
  0/8 completed

✅ 8 todos generated from response

Combine with Planning

praisonai "Plan a machine learning project" --todo --planning

Expected Output:

📋 PLANNING PHASE
Creating implementation plan...

[Planning output...]

📋 Generated Todos from Plan:
--------------------------------------------------
  1. ⬜ 🔴 Define problem statement and success metrics
  2. ⬜ 🔴 Collect and prepare training data
  3. ⬜ 🟡 Perform exploratory data analysis
  4. ⬜ 🟡 Feature engineering
  5. ⬜ 🟡 Model selection and training
  6. ⬜ 🟡 Hyperparameter tuning
  7. ⬜ 🟢 Model evaluation
  8. ⬜ 🟢 Deploy model to production
--------------------------------------------------
  0/8 completed

Use Cases

Project Planning

praisonai "Plan the development of a mobile app" --todo

Sprint Planning

praisonai "Break down the user story: As a user, I want to reset my password" --todo

Learning Path

praisonai "Create a learning plan for Kubernetes" --todo

Bug Triage

praisonai "Analyze this error and suggest fixes" --todo --fast-context ./src

Todo Storage

Todos are stored in the home-level workspace ~/.praison/todos.json:

{
  "todos": [
    {
      "id": 1,
      "task": "Implement user authentication",
      "priority": "medium",
      "completed": false,
      "created": "2024-12-16T15:30:00Z"
    }
  ]
}

The todo workspace (~/.praison/) is a home-level location and was not changed by PraisonAI PR #4946 — it does not trigger the project-marker path drift. However, project-level CLI state — thinking, compaction, output-style, file-history, the queue DB, and knowledge vector stores — now lives under ./.praisonai/ (canonical). See Project data directory.

Priority Levels

Priority	Icon	Description
High	🔴	Critical tasks, blockers
Medium	🟡	Standard priority
Low	🟢	Nice-to-have, can wait

Best Practices

Use --todo with --planning for comprehensive project breakdowns with actionable tasks.

Regular Review

Use praisonai todo list regularly to track progress

Clear Completed

Periodically clear completed todos to keep list manageable

Combine with Planning

Use --planning --todo for detailed task breakdowns

Project-Specific

Consider using different workspaces for different projects

Workflow Example

# 1. Generate todos from project plan
praisonai "Plan the API implementation" --todo --planning

# 2. View todos
praisonai todo list

# 3. Work on first task
praisonai "Help me design the API schema" --fast-context ./src

# 4. Mark as complete
praisonai todo complete 1

# 5. Continue with next task
praisonai todo list

Via MCP

The praisonai-mcp host exposes four MCP tools — praisonai.todo.list, praisonai.todo.add, praisonai.todo.complete, praisonai.todo.delete — that read and write the runtime todo store (<workspace>/todos.json, else ~/.praisonai/todos.json). A todo added from Claude Desktop is visible to an agent run on the same machine, and vice versa. See MCP Todo Tools for the tool table, record shape, and store resolution.

​Quick Start

​Commands

​Add Todo

​List Todos

​Complete Todo

​Delete Todo

​Clear Todos

​Help

​Using —todo Flag

​Generate Todos from Task

​Combine with Planning

​Use Cases

​Project Planning

​Sprint Planning

​Learning Path

​Bug Triage

​Todo Storage

​Priority Levels

​Best Practices

Regular Review

Clear Completed

Combine with Planning

Project-Specific

​Workflow Example

​Via MCP

​Related

Quick Start

Commands

Add Todo

List Todos

Complete Todo

Delete Todo

Clear Todos

Help

Using —todo Flag

Generate Todos from Task

Combine with Planning

Use Cases

Project Planning

Sprint Planning

Learning Path

Bug Triage

Todo Storage

Priority Levels

Best Practices

Workflow Example

Via MCP

Related