Proactive Tasks

A task management system that transforms reactive assistants into proactive partners who work autonomously on shared goals.

Core Concept

Instead of waiting for your human to tell you what to do, this skill lets you:

• Track goals and break them into actionable tasks
• Work on tasks during heartbeats
• Message your human with updates and ask for input when blocked
• Make steady progress on long-term objectives

Quick Start

Creating Goals

When your human mentions a goal or project:

python3 scripts/task_manager.py add-goal "Build voice assistant hardware" \
  --priority high \
  --context "Replace Alexa with custom solution using local models"

Breaking Down into Tasks

python3 scripts/task_manager.py add-task "Build voice assistant hardware" \
  "Research voice-to-text models" \
  --priority high

python3 scripts/task_manager.py add-task "Build voice assistant hardware" \
  "Compare Raspberry Pi vs other hardware options" \
  --depends-on "Research voice-to-text models"

During Heartbeats

Check what to work on next:

python3 scripts/task_manager.py next-task

This returns the highest-priority task you can work on (no unmet dependencies, not blocked).

Completing Tasks

python3 scripts/task_manager.py complete-task <task-id> \
  --notes "Researched Whisper, Coqui, vosk. Whisper.cpp looks best for Pi."

Messaging Your Human

When you complete something important or get blocked:

python3 scripts/task_manager.py mark-needs-input <task-id> \
  --reason "Need budget approval for hardware purchase"

Then message your human with the update/question.

Task States

Heartbeat Integration

To enable autonomous proactive work, you need to set up a heartbeat system. This tells you to periodically check for tasks and work on them.

Quick setup: See HEARTBEAT_SETUP.md for complete step-by-step instructions.

TL;DR:

1. Create a cron job that sends you a heartbeat message every 30 minutes
2. Add proactive-tasks checks to your HEARTBEAT.md
3. You'll automatically check for tasks and work on them without waiting for prompts

Heartbeat Message Template

Your cron job should send this message every 30 minutes:

💓 Heartbeat check: Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.

Add to HEARTBEAT.md

Add this to your workspace HEARTBEAT.md:

## Proactive Tasks (Every heartbeat) 🚀

Check if there's work to do on our goals:

- [ ] Run `python3 skills/proactive-tasks/scripts/task_manager.py next-task`
- [ ] If a task is returned, work on it for up to 10-15 minutes
- [ ] Update task status when done, blocked, or needs input
- [ ] Message your human with meaningful updates (completions, blockers, discoveries)
- [ ] Don't spam - only message for significant milestones or when stuck

**Goal:** Make autonomous progress on our shared objectives without waiting for prompts.

What Happens

Every 30 minutes:
├─ Heartbeat fires
├─ You read HEARTBEAT.md
├─ Check for next task
├─ If task found → work on it, update status, message human if needed
└─ If nothing → reply "HEARTBEAT_OK" (silent)

The transformation: You go from reactive (waiting for prompts) to proactive (making steady autonomous progress).

Best Practices

When to Create Goals

• Long-term projects (building something, learning a topic)
• Recurring responsibilities (monitor X, maintain Y)
• Exploratory work (research Z, evaluate options for W)

When to Create Tasks

Break goals into tasks that are:

• Specific: "Research Whisper models" not "Look into AI stuff"
• Achievable in one sitting: 15-60 minutes of focused work
• Clear completion criteria: You know when it's done

When to Message Your Human

✅ Do message when:

• You complete a meaningful milestone
• You need input/decision to proceed
• You discover something important
• A task will take longer than expected

❌ Don't spam with:

• Every tiny sub-task completion
• Routine progress updates
• Things they didn't ask about (unless relevant)

Managing Scope Creep

If a task turns out to be bigger than expected:

1. Mark current task as in_progress
2. Add new sub-tasks for the pieces you discovered
3. Update dependencies
4. Continue with manageable chunks

File Structure

All data stored in data/tasks.json:

{
  "goals": [
    {
      "id": "goal_001",
      "title": "Build voice assistant hardware",
      "priority": "high",
      "context": "Replace Alexa with custom solution",
      "created_at": "2026-02-05T05:25:00Z",
      "status": "active"
    }
  ],
  "tasks": [
    {
      "id": "task_001",
      "goal_id": "goal_001",
      "title": "Research voice-to-text models",
      "priority": "high",
      "status": "completed",
      "created_at": "2026-02-05T05:26:00Z",
      "completed_at": "2026-02-05T06:15:00Z",
      "notes": "Researched Whisper, Coqui, vosk. Whisper.cpp best for Pi."
    }
  ]
}

CLI Reference

See CLI_REFERENCE.md for complete command documentation.

Example Workflow

Day 1:

Human: "Let's build a custom voice assistant to replace Alexa"
Agent: *Creates goal, breaks into initial research tasks*

During heartbeat:

$ python3 scripts/task_manager.py next-task
→ task_001: Research voice-to-text models (priority: high)

# Agent works on it, completes research
$ python3 scripts/task_manager.py complete-task task_001 --notes "..."

Agent messages human:

"Hey! I finished researching voice models. Whisper.cpp looks perfect for Raspberry Pi - runs locally, good accuracy, low latency. Want me to compare hardware options next?"

Day 2:

Human: "Yeah, compare Pi 5 vs alternatives"
Agent: *Adds task, works on it during next heartbeat*

This cycle continues - the agent makes steady autonomous progress while keeping the human in the loop for decisions and updates.

---

Built by Toki for proactive AI partnership 🚀