Todo Tracker

Manage follow-up items and remind users at appropriate times via heartbeat checks.

Security Scan

The skill is internally consistent with its description: it stores todos in a local JSON file, includes a local cleanup script to remove completed items after 24h, requests no credentials or external installs, and its runtime instructions only touch expected agent config and memory files.

Purpose & Capability

The name/description (todo reminders, heartbeat-driven checks) matches the included files and behavior. There are no unrelated required binaries, env vars, or external services. The provided cleanup script and templates are appropriate for a self-managed todo skill.

Instruction Scope

SKILL.md instructs the agent to copy templates to memory/todo.json, register heartbeat and trigger keywords, and follow clear rules for marking items. The instructions reference only workspace files (memory/todo.json, HEARTBEAT.md, AGENTS.md) and do not ask the agent to read or exfiltrate unrelated files or secrets.

Install Mechanism

No install spec is provided (instruction-only) and the only code file is a small local Python script. Nothing is downloaded from external URLs or installed from remote package registries.

Credentials

The skill requires no environment variables, credentials, or config paths. The only persistent state is a JSON file in the agent workspace, which matches the skill's purpose.

Persistence & Privilege

The skill does not request 'always: true' and uses normal autonomous invocation via heartbeat triggers (the platform default). It does not attempt to modify other skills or system-wide settings programmatically.

Assessment

This skill appears coherent and limited to local todo management, but before installing: 1) verify the workspace layout on your agent matches the script's TODO_FILE path (the cleaner uses a relative path up from scripts to workspace/memory/todo.json); 2) run the cleaner in --dry-run first to confirm it targets the intended file; 3) ensure your agent will set completed_at / cancelled_at and reminded flags as required (the cleanup depends on completed_at); 4) review HEARTBEAT.md and AGENTS.md changes you are asked to make to confirm you want automatic heartbeat-driven reminders; and 5) if provenance matters, check the referenced GitHub repo/owner (SKILL.md/footer lists a GitHub URL) since the top-level metadata listed the source as unknown. If any of these checks fail or the workspace layout differs, treat installation as potentially disruptive until corrected.

Setup

On first use, copy templates/todo.json to memory/todo.json. Update HEARTBEAT.md and AGENTS.md with trigger rules. See setup.md for details.

When to Use

User mentions reminders, follow-ups, or todos. Agent proactively checks pending items during heartbeat cycles.

Quick Reference

Topic	File
Installation steps	setup.md
Data structure	data-structure.md
Usage examples	examples.md
Cleanup script	scripts/todo-cleaner.py

Core Rules

🚨 HARD CONSTRAINTS (Must Follow)

When marking a todo as completed or cancelled, you MUST set the corresponding timestamp field:

• status=completed → MUST set completed_at to current time (ISO 8601 with timezone)
• status=cancelled → MUST set cancelled_at to current time (ISO 8601 with timezone)

Example:

{
  "status": "completed",
  "completed_at": "2026-04-16T13:40:00+08:00"  // ← REQUIRED!
}

Failure to set these fields will cause cleanup script to skip the item, leaving completed tasks in todo.json indefinitely.

Why this matters: The cleanup script (scripts/todo-cleaner.py) checks completed_at to determine if an item is older than 24 hours. Without this field, completed items will never be deleted.

---

1. Store Items in memory/todo.json

Single source of truth. Each item has: id, description, follow_up_time, status, priority, context.

2. Check During Heartbeat

Every heartbeat (30 min), check status=pending items. If follow_up_time reached, remind user (regardless of reminded flag — pending items should be reminded repeatedly until completed).

3. Clean Up Completed Items

Items with status=completed or status=cancelled are deleted after 24 hours.

Cleanup Script: Run scripts/todo-cleaner.py to auto-delete old completed items.

# Dry run (preview)
python3 ~/.openclaw/workspace/skills/todo-tracker/scripts/todo-cleaner.py --dry-run

# Execute cleanup
python3 ~/.openclaw/workspace/skills/todo-tracker/scripts/todo-cleaner.py

4. Time Precision is ~30 Minutes

Reminders trigger at heartbeat intervals, not exact times. Plan accordingly.

5. Prevent Duplicate Reminders

Set reminded=true after reminding. Check this flag before reminding again.

6. Ask for Missing Info

If user says "remind me tomorrow" without specifics, ask: "What time tomorrow?"

Trigger Keywords

Intent	Examples
Add	"remind me...", "follow up...", "don't forget..."
Complete	"done with...", "completed...", "no need to follow up"
List	"show todos", "what do I need to follow up"
Cancel	"cancel the reminder..."

Data Storage

memory/todo.json — all todo items. See data-structure.md for schema.

Feedback

• If useful: clawhub star suidge-todo-tracker
• Issues: Report via GitHub

---

slug: suidge-todo-tracker homepage: https://github.com/Suidge/todo-tracker