Repository navigation
First release of homework-mcp — an MCP server that queues a fresh Claude Code session, in a new terminal window, at a future date you specified.
Highlights
- 3 MCP tools:
homework_schedule/homework_list/homework_cancel - OS scheduler integration: Windows schtasks / WSL2 (Windows-host schtasks via cmd.exe) / macOS launchd / Linux systemd --user timer
- Re-entrancy-safe firing: atomic
UPDATE WHERE status='scheduled'makes double-fires impossible by construction - No-fallback policy: missing config / unsupported OS / scheduler failure all throw at call time, no silent defaults
- Elapsed-time prompt header: when the task fires, the prompt is prepended with how long ago it was scheduled, prompting the future Claude session to verify current state before acting
Verified end-to-end
- Windows + WSL2 (the author's environment): scheduling, firing 5+ minutes out, fresh Claude window opening with prompt loaded, cancel removing both DB row and Windows schtasks entry, atomic re-entrancy under concurrent fires, year guard preventing unintended re-fires
- Pathological prompt verification:
\", newlines,\$(echo INJECT), backticks,;,%VAR%,&,<angle>all preserved verbatim and reach Claude as initial user message
Beta status
macOS and Linux launchers are implemented but not exercised in the author's environment. PRs welcome.
Install
npm install -g homework-mcp
claude mcp add --scope user homework npx homework-mcp