Task Runner

Manage tasks and projects across sessions with persistent tracking.

Quick Start

Add a task

bash

task_runner.py add "<description>" [project] [priority]

List all tasks

bash

task_runner.py list

List tasks for a specific project

bash

task_runner.py list "<project>"

Complete a task

bash

task_runner.py complete <task_id>

Change task priority

bash

task_runner.py priority <task_id> <low|medium|high>

Export project to markdown

bash

task_runner.py export "<project>" "<output_file>"

Features

•Persistent storage - Tasks survive session restarts (stored in ~/.openclaw/workspace/tasks_db.json)
•Project organization - Group tasks by project for better organization
•Priority levels - low, medium (default), high
•Status tracking - pending vs completed with timestamps
•Flexible filtering - View all tasks or filter by project
•Markdown export - Export projects to clean markdown for sharing

Security

Path Validation (v1.0.1+)

The export function validates output paths to prevent malicious writes:

•✅ Allowed: ~/.openclaw/workspace/, /tmp/, and home directory
•❌ Blocked: System paths (/etc/, /usr/, /var/, etc.)
•❌ Blocked: Sensitive dotfiles (~/.bashrc, ~/.ssh, etc.)

This prevents prompt injection attacks that could attempt to write to system files for privilege escalation.

Task Storage

The task storage is JSON-based and only writes to ~/.openclaw/workspace/tasks_db.json.

Usage Patterns

For multi-session projects

bash

# Add experiment tasks
task_runner.py add "Setup development environment" "project-x" "high"
task_runner.py add "Write initial tests" "project-x" "medium"
task_runner.py add "Document API endpoints" "project-x" "low"

# List project progress
task_runner.py list "project-x"

# Complete tasks as you go
task_runner.py complete 1
task_runner.py complete 2

For autonomous agent workflows

Track your own tasks across sessions:

bash

# Plan experiments
task_runner.py add "Build and publish skill" "income-experiments" "high"
task_runner.py add "Test content pipeline" "income-experiments" "medium"

# Update priorities based on learning
task_runner.py priority 2 "high"

# Export progress reports
task_runner.py export "income-experiments" "./progress-report.md"

For sprint planning

bash

# Plan week's work
task_runner.py.py add "Build feature X" "sprint-5" "high"
task_runner.py.py add "Fix bug Y" "sprint-5" "high"
task_runner.py.py add "Update documentation" "sprint-5" "medium"

# Review progress
task_runner.py list "sprint-5"

# Export for standup
task_runner.py export "sprint-5" "./standup.md"

Task Priorities

Priority	Emoji	When to Use
high	🔴	Blocking issues, urgent, must do now
medium	🟡	Normal work, do soon
low	🟢	Nice to have, backlog items

Output Format

Task listing shows:

•Status icon (✅ completed, ⏳ pending)
•Project name
•Task ID number
•Priority emoji
•Creation date
•Task description
•Completion date (if completed)

Export Format

Markdown export includes:

•Project title with task counts
•Pending tasks section
•Completed tasks section (most recent first)
•Task IDs, priorities, and timestamps

Examples

Managing a coding project

bash

# Setup
task_runner.py add "Clone repository" "my-project" "high"
task_runner.py add "Install dependencies" "my-project" "high"
task_runner.py add "Set up database" "my-project" "medium"

# Track progress
task_runner.py list "my-project"
task_runner.py complete 1
task_runner.py complete 2

# Export for documentation
task_runner.py export "my-project" "./my-project-tasks.md"

Tracking autonomous agent experiments

bash

# Plan experiments
task_runner.py add "Experiment 1: Publish skills" "autonomous-income" "high"
task_runner.py add "Experiment 2: Content automation" "autonomous-income" "medium"
task_runner.py add "Experiment 3: Service MVP" "autonomous-income" "low"

# Work through them
task_runner.py list "autonomous-income"
task_runner.py complete 1

# Adjust based on learning
task_runner.py add "Experiment 2a: Research tools without API keys" "autonomous-income" "high"
task_runner.py priority 2 "low"

Daily task management

bash

# Plan the day
task_runner.py add "Review pull requests" "daily" "high"
task_runner.py add "Write documentation" "daily" "medium"
task_runner.py add "Respond to emails" "daily" "low"

# End-of-day review
task_runner.py list

# Archive completed work
task_runner.py export "daily" "./$(date +%Y-%m-%d)-tasks.md"

Best Practices

•Use meaningful project names - income-experiments not ideas
•Set priorities consistently - helps with focus
•Mark tasks complete promptly - keeps list clean
•Export before major changes - backup progress
•Review and clean up - archive old projects regularly

Integration with Other Skills

Combine with research-assistant for complete project management:

•Use research-assistant for notes and knowledge
•Use task-runner for actionable tasks
•Export both to create comprehensive project docs