clawdo - Todo List for Agents

Todo list and task management for AI agents. Add, track, and complete tasks with autonomy levels — agents propose work, humans approve. Works in heartbeats, cron, and conversations. Persistent SQLite CLI with structured JSON output.

Security Scan

The skill's declared purpose (agent todo list) matches its requirements and instructions; it is an instruction-only wrapper that expects an npm-installed CLI, but the actual executable is fetched from npm (not included), so you should review the package source before installing.

Purpose & Capability

The name/description (todo/task management for agents) aligns with the declared requirement of a 'clawdo' binary and the npm install spec. There are no unrelated environment variables, credentials, or config paths requested that would be unexpected for a local task queue CLI.

Instruction Scope

SKILL.md instructs agents to run the clawdo CLI (add, inbox, next, start, done, propose). Examples show integration in heartbeats and cron. The doc does not instruct reading arbitrary host files or exfiltrating data, but the examples leave the step '... do the work ...' open-ended — the agent will run whatever commands are needed to complete tasks, which is expected but broad in practice. The SKILL.md claims input sanitization and parameterized SQL, but those claims cannot be verified from the documentation alone.

Install Mechanism

Installation is via npm (package 'clawdo' → global binary). This is a standard distribution mechanism and matches the declared binary requirement. However, npm packages run arbitrary code at install and runtime; because the skill package contains only docs and not the CLI source, you must inspect the npm package or its GitHub repo before installing to ensure it doesn't perform unexpected actions.

Credentials

No environment variables, credentials, or config paths are required. That is proportionate for a local CLI that stores state in SQLite and integrates with agent workflows.

Persistence & Privilege

The skill is not marked always:true and does not request special system-level privileges. Persistence is local (SQLite) as advertised. The skill permits normal autonomous invocation (platform default), which is expected for agent tools.

Assessment

This skill is internally consistent with its stated purpose: it simply wraps a CLI named 'clawdo' distributed via npm. The package distributed in this skill bundle contains only documentation — the actual code comes from npm/GitHub. Before installing or giving agents the ability to run it: 1) inspect the 'clawdo' npm package and its GitHub source (check for unexpected network endpoints, shelling out, or writing to unusual paths); 2) confirm the publisher identity and package history on npm; 3) run the CLI in a sandboxed environment (or with limited FS/network permissions) to observe behavior; 4) verify where the SQLite DB is stored and whether logs or audit trails might contain sensitive data; and 5) don't rely solely on the SKILL.md security claims (e.g., SQL parameterization) without code review. If you cannot review the npm package, treat it as higher risk.

🦞 clawdo — The missing todo list for AI agents

Your agent has memory files, cron jobs, and chat. It has no todo list.

No way to say "do this when you get to it." Not "do this at 14:00 UTC." Not "do this right now in this conversation." Just... remember to do it. Track it. Pick it up when there's a gap.

That's clawdo.

Install

clawhub install clawdo    # installs skill + docs into your workspace
npm install -g clawdo     # install the CLI binary

Requirements: Node.js ≥18

Quick Start

# Capture a task
clawdo add "update dependencies" --urgency soon

# Agent checks its queue (heartbeat, cron, conversation — wherever)
clawdo inbox --format json

# Agent works it
clawdo start a3f2
clawdo done a3f2 --json

add → inbox → start → done. Persistent state in SQLite. Every command has --json so agents parse structured output, not terminal art.

Where it fits

clawdo works everywhere agents work:

• Heartbeat loops — "anything in my queue? let me do it between checks"
• Cron jobs — "every hour, process one task"
• Conversations — "J mentioned fixing the auth module, let me capture that"
• Pipes and sub-agents — non-TTY safe, no interactive prompts

Heartbeat integration example

# In HEARTBEAT.md — runs every ~30 minutes
TASKS=$(clawdo inbox --format json)
AUTO=$(echo "$TASKS" | jq '.autoReady | length')

if [ "$AUTO" -gt 0 ]; then
  TASK=$(clawdo next --auto --json | jq -r '.task.id')
  clawdo start "$TASK" --json
  # ... do the work ...
  clawdo done "$TASK" --json
fi

Autonomy levels

Tasks can be tagged with permission tiers that control what the agent is allowed to do unsupervised:

Level	Time Limit	What it means
auto	10 min	Agent does it silently. Fix a typo, run tests.
auto-notify	30 min	Agent does it, tells the human when done.
collab	Unlimited	Human required. Complex, risky, or ambiguous.

Default: collab (safe).

Key rule: Autonomy is a permission, not a suggestion. Once set, agents can't change it. If an agent fails 3 times, autonomy demotes to collab. Safety only moves down, never up.

Agents propose, humans approve. Agent tasks always start as proposed. The human runs clawdo confirm <id> or it doesn't happen.

Usage

For humans

# Add tasks — inline metadata parsing
clawdo add "deploy new API +backend auto-notify now"
#           └── text ──────┘ └project┘ └─level──┘ └urg┘

# View
clawdo list                       # active tasks
clawdo list --status proposed     # agent suggestions
clawdo next                       # highest priority

# Review agent proposals
clawdo confirm <id>               # approve
clawdo reject <id>                # reject

# Work
clawdo start <id>
clawdo done <id>
clawdo done abc,def,ghi           # complete several

For agents

# Check inbox (structured)
clawdo inbox --format json

# Propose work
clawdo propose "add input validation" --level auto --json

# Execute
TASK=$(clawdo next --auto --json | jq -r '.task.id // empty')
if [ -n "$TASK" ]; then
  clawdo start "$TASK" --json
  # ... do the work ...
  clawdo done "$TASK" --json
fi

The inbox returns: autoReady, autoNotifyReady, urgent, overdue, proposed, stale, blocked.

Inline syntax

clawdo add "fix auth bug +backend @code auto soon"

• +word → project
• @word → context
• auto / auto-notify / collab → autonomy level
• now / soon / whenever / someday → urgency
• due:YYYY-MM-DD → due date

Security

• Immutable autonomy — agents cannot escalate permissions
• Proposal limits — max 5 active, 60s cooldown
• Prompt injection defense — input sanitization, parameterized SQL
• Audit trail — append-only log of every state change
• Secure IDs — crypto.randomInt(), no modulo bias

Resources

• GitHub: https://github.com/LePetitPince/clawdo
• npm: https://www.npmjs.com/package/clawdo
• Full docs: clawdo --help

License

MIT