Nex Task Cli

What it does

• Generates task.py, a single-file Python CLI (around 600 lines, stdlib only) with a flat JSON store at ~/nex-data/taskboard.json, no database, no daemon
• Ships the canonical command set: list, today, overdue, done, stats, add, check, snooze, delete, search, cleanup, help
• Handles priorities (urgent/high/normal/low), categories, due dates, dedupe on add, and recurrence (daily, weekday, weekly, monthly) that regenerates the next instance on check
• Prefix-id matching: task check 9f3e matches the full UUID, with a clear error on ambiguity
• Includes pyproject.toml for pip install -e ., an agent-tool.md reference with --json output schemas and exit codes, and a pytest suite covering recurrence, dedupe, and snooze

Why use this

Every command supports --json, so the same tool your morning shell prompt runs is a tool an orchestrator agent can call to schedule its own followups. Atomic writes (tmp plus os.replace) mean the JSON store never corrupts mid-write. Pattern-derived from the production CLI ZeroClaw uses, shipped as a clean reimplementation of the same contract.

See it in action

Prompt:

Build me a CLI todo list my agent can also call as a tool.

Result:

$ task add Email Bob --due 2026-05-29 --cat followup --high
Added [9f3e] Email Bob (high, followup, due 2026-05-29)

$ task today
H  9f3e  Email Bob            followup  due today
N  a41c  Water the plants     task      recurring daily

$ task check 9f3e
Done: Email Bob

$ task add Standup notes --recur weekday --json
{id: c7d2e1a0-..., title: Standup notes,
 recur: weekday, due: 2026-08-07, done: false}

Checking a recurring task closes today's instance and tees up the next one automatically.

Use cases

• A personal task CLI without a SaaS dependency, living in one JSON file
• Giving an orchestrator agent a shell tool to schedule its own followups
• A task today line in your morning shell prompt
• Porting the JSON-as-DB pattern to any small list-shaped CLI (notes, bookmarks, snippets)

Known limitations

• Single-user, local-first: no multi-user lists, no cross-device sync (pair with Dropbox, syncthing, or git yourself)
• Knows due dates but pushes no notifications; pair with cron if you want pings
• JSON reads get slow above roughly 5000 tasks; move to SQLite at that scale

FAQ

What exactly is in the download?

SKILL.md, four asset templates (task.py.template, pyproject.toml.template, agent-tool.md.template, test_task.py.template), and four references covering the command set, recurrence semantics, the agent-tool contract, and the JSON-as-database pattern.

Which agents does it work with?

Claude Code, Claude Cowork, Cursor, Codex CLI, and any agent that reads SKILL.md skills. The generated CLI is callable by any agent that can run shell commands.

Do I need anything else?

Python 3.10 or newer. The core is stdlib only; rich is optional for prettier color output.

How does recurrence work?

Checking off a recurring task marks it done and inserts a fresh instance with the next due date (daily, next weekday, plus 7 days, or plus 1 month). Today's instance closes, tomorrow's is already teed up. Snoozing never triggers regeneration.