duecard

A dated card with a pointer. The pointed-at thing can change. The reminder does not.

CLI for follow-ups you meant to keep: old agent chats, x.com bookmarks, anything with a URL or session id.

Install

npm install -g duecard

Store: ~/.duecard/cards.jsonl (override with DUECARD_HOME).

From a checkout (development):

npm install
npm run build
npm link

Usage

duecard add "Check X post stats" --due 1d --url https://x.com/brooksy4503/status/2088193435140518024
duecard due
duecard list --status open
duecard show dc_01
duecard snooze dc_01 3d
duecard done dc_01
duecard drop dc_01
duecard open dc_01

--due accepts now, 2h, 1d, 3d, a calendar date (2026-08-16, local 09:00), or an ISO timestamp.

Human default is a short table. Agents pass --json.

Agent skill

Portable Agent Skill in skills/duecard/. Same SKILL.md format used by skills.sh: Claude Code, Cursor, Codex, Grok Build, and any other client that loads the open skill format.

npx skills add brooksy4503/duecard -g

# from this checkout
npx skills add ./ -g

The skill teaches the agent to call duecard … --json. The CLI must still be on PATH (npm install -g duecard). Use the CLI to change the store.

A session-start hook only needs duecard due --json (print at most 3 titles).

Agent contract

Full contract: AGENTS.md. Short version:

• --json → stdout is only JSON
• errors live in the JSON (ok, error); stderr only with --verbose
• exit 0 = success and (for due) at least one card
• exit 1 = success, nothing due / nothing found
• exit 2 = hard error
• no TTY prompts; never wait for stdin
• ids are the only handle

duecard due --json

Tests

npm test

Runs against a temp DUECARD_HOME.

Plan

See PLAN.md. Phase 1 is this CLI. Phase 2 is the portable skill in skills/duecard/. A menubar wrap comes later, and only if this gets used.