English · 日本語
An MCP server that queues homework for your future Claude Code self. At the due time, a fresh Claude Code session opens in a new terminal window with your prompt pre-loaded as the first user message.
For development decisions you want to revisit in N days / N weeks / N months — when your own memory is no longer reliable.
npm install -g homework-mcp
claude mcp add --scope user homework npx homework-mcpThe first run writes a config template to ~/.homework-mcp/config.json and exits. Fill it in for your OS:
Schedule from Claude Code:
homework_schedule({
due_at: "2026-06-02T09:00:00+09:00",
prompt: "Check whether the auth middleware rewrite landed cleanly. Look for new bugs around session token storage.",
title: "auth-rewrite-followup"
})When the time comes, a new terminal window opens with a fresh claude session, prompt already loaded.
When you develop fast with Claude Code, you accumulate decisions like:
- "Watch this code for a month, then decide if it can be deleted."
- "Re-evaluate whether we still need a workaround in N days."
- "After upgrading this dependency, verify behavior in 2 weeks."
These pile up. You forget them. They never get processed.
homework-mcp solves this by making the OS scheduler open a new Claude Code session at the due time, with the original prompt and an "elapsed time" header automatically prepended. You see a new terminal window appear when the time comes — the homework re-enters your awareness exactly when you said it should.
| Tool | Why it doesn't fit |
|---|---|
Claude Code /loop / natural-language reminders |
Sessions expire in 7 days |
| Claude Desktop scheduled tasks | Requires the desktop app to be running, doesn't spawn a fresh CLI session |
claude.ai/code/scheduled cloud tasks |
Fully background, invisible |
claude_scheduler (GitHub) |
Unattended-only, daemon-style |
Remind Me skill / claude-mcp-reminders |
Notifications only, no fresh session |
The unique combination this tool delivers: fresh session + foreground new window + multi-month horizon + auto-resume after machine restart.
flowchart TD
A["MCP server (stdio)<br/>homework_schedule"] -->|"BEGIN IMMEDIATE → INSERT"| B[("~/.homework-mcp/tasks.db<br/>SQLite (WAL mode)")]
A -->|"register one-shot"| C{"OS scheduler<br/>schtasks / launchd / systemd"}
C -. "at due_at" .-> D["bin/homework-mcp-fire<br/>--task-id <uuid>"]
D -->|"DB lookup + year guard"| E["atomic UPDATE<br/>scheduled → firing"]
E -->|"build prompt + script"| F["~/.homework-mcp/runs/<br/><uuid>.txt + <uuid>.sh"]
F -->|"spawn"| G["new terminal window<br/>(wt / Terminal / iTerm / gnome-terminal / ...)"]
G -->|"bash script"| H["fresh claude session<br/>with prompt as initial user message"]
H -->|"status = fired"| I["self-cleanup<br/>(plist / unit / schtasks auto-delete)"]
fire path: scheduled → firing → fired
cancel path: scheduled → cancelled
firing is an atomic checkpoint. If the fire-script crashes between firing and fired, the row stays in firing for human review (no auto re-fire). homework_list({filter:{status:"firing"}}) surfaces these.
Two concurrent fires of the same task: one wins the atomic UPDATE WHERE status='scheduled', the other sees changes()=0 and exits without launching claude. Verified end-to-end in tests.
homework_schedule(due_at, prompt, title?)
Schedule a homework task.
due_atmust be ISO 8601 with timezone offset and at least 5 minutes in the future.promptis stored verbatim in SQLite. No structure required — write it like a natural-language note.- The current working directory of the calling process is captured automatically and used when the task fires.
When the task fires, a new terminal window opens in the original cwd, and a fresh claude session starts with this prompt as the initial user message:
[homework-mcp からの宿題]
このタスクは {created_at} に仕込まれたものです。
現在は {now} で、{elapsed} 経過しています。
コードベース・状況が変わっている可能性が高いため、
着手前に必ず現状を確認してください。
---
{your prompt}
The "elapsed time" header tells the future Claude session that conditions may have changed and to verify the current state before acting.
homework_list(filter?)
homework_list() // scheduled tasks (default)
homework_list({ filter: { status: "fired" } }) // already fired
homework_list({ filter: { status: "firing" } }) // crash candidates
homework_list({ filter: { status: "cancelled" } })homework_cancel(id)
Cancel a scheduled task. Throws if the task does not exist or is already in firing / fired / cancelled.
| Platform | Tested |
|---|---|
| Windows + WSL2 | ✅ End-to-end (the author's environment) |
| Windows native | |
| macOS | |
| Linux |
Linux / Windows native prerequisites
Linux requires:
loginctl enable-linger $USER(so user-systemd survives logout)- A live GUI session at registration time (DISPLAY or WAYLAND_DISPLAY set), so the GUI terminal can be reached when the timer fires
Windows native requires bash on PATH (Git for Windows or the WSL launcher).
This project follows a strict no-silent-fallback rule:
- Missing config fields → throw at call time, no defaults.
- Scheduler registration failure → DB row is rolled back, error propagates.
- Unknown OS / WSL1 / unconfigured Linux terminal → throw, never guess.
- Prompt files are passed via
bash $(cat <path>)argument substitution, not stdin redirection (Claude CLI's TUI is not initialized by stdin pipes, verified empirically).
If a homework task can't be scheduled or fired correctly, you find out now, not at the due time when it silently fails to appear.
- Caveat — long-term storage of "negative knowledge" (traps), the inspiration for the elapsed-time prompt header.
- Relay-MCP — the SQLite + MCP server pattern this project reuses.
- Throughline — context compression and cross-session memory carry-over.
MIT — see LICENSE.

{ "os_kind": "wsl2", "wsl_distro": "Ubuntu-22.04", "macos_terminal": null, "linux_terminal": null }