ai-todo

AI Todo - Task Management for AI Agents

Via the ai-todo CLI, manage tasks, track progress, and maintain work logs. Connect to ai-todo (https://ai-todo.stringzhao.life) to achieve persistent task management across sessions.

Prerequisites

Before running any command, first check the authentication status:

cat ~/.config/ai-todo/credentials.json 2>/dev/null

If not authenticated, run ai-todo login. If not installed, run npm install -g ai-todo-cli。

Command Discovery

Commands are dynamically loaded from the server,hardcoding is strictly prohibited. Before using a command for the first time, use --help to discover parameters:

ai-todo --help                    # 查看所有可用命令
ai-todo <command> --help          # 查看具体命令的参数

Key conventions:

• Default output JSON，tasks:tree outputs plain text
• Parameter format --key <value>(snake_case, e.g. --parent_id）
• Namespaces:tasks:* task operations,spaces:* space operations
• Exit codes: 0=success, 1=error, 2=not authenticated

Core workflow

Step 1: Understand the task structure (mandatory before every operation)

ai-todo tasks:tree

Outputs tree-form text, 📌 marks project spaces, and indentation shows parent-child relationships. Used to:

• Find the project space or parent task to which a new task should belong
• Avoid creating duplicate tasks
• Understand the existing task breakdown

Key principle: Tasks must be placed under the correct project and parent task; do not create them arbitrarily at the top level.

View tasks

ai-todo tasks:tree                    # 全局任务树
ai-todo tasks:list --filter today     # 今天的任务
ai-todo tasks:list --filter assigned  # 分配给我的任务

Create tasks

When the user describes a work plan or you identify items that can be broken down:

1. First tasks:tree find the correct place of belonging
2. Create a parent task (or reuse an existing one)
3. Use --parent_id to create subtasks
4. Set priorities reasonably (P0=blocker, P1=core, P2=non-critical)

ai-todo tasks:create --title "实现支付功能" --priority P1
ai-todo tasks:create --title "对接微信支付" --parent_id <父任务ID> --tags backend

Update progress and complete tasks

Choose the appropriate operation according to the work stage:

• Start work：tasks:update --id <ID> --progress 20
• Staged progress：tasks:update --id <ID> --progress 60 + tasks:add-log --id <ID> --content "完成了XX"
• Work completed：tasks:complete --id <ID>(automatically completes subtasks)
• Just record：tasks:add-log --id <ID> --content "做了XX"

When the user explicitly says "completed", directly use tasks:complete; if it is staged progress, use tasks:update to increment progress.

Post-action (after git commit/push/deploy)

1. tasks:tree Find the related task
2. Related task exists → update progress + add a log + if completed, tasks:complete
3. No related task → suggest creating one to record the completed work
4. Lightweight operation, a single log summary is enough

Pre-action (planning stage)

When the user discusses feature planning, technical solutions, or sprint scheduling:

1. Extract actionable items from the discussion
2. Create a task hierarchy (parent task + subtasks)
3. Set priorities according to dependencies

Cross-skill collaboration

• After git-tools completes: record progress to the related task
• After vercel:deploy completes: record the deployment and complete the related task
• After brainstorming ends: convert the conclusions into a task hierarchy