https://github.com/driversti/claude-cuckoo
π¦ A durable personal reminder for Claude Code β date/time reminders that resurface at your next session on/after the due date.
https://github.com/driversti/claude-cuckoo
claude-code claude-code-plugin plugin
Last synced: 15 days ago
JSON representation
π¦ A durable personal reminder for Claude Code β date/time reminders that resurface at your next session on/after the due date.
- Host: GitHub
- URL: https://github.com/driversti/claude-cuckoo
- Owner: driversti
- License: mit
- Created: 2026-06-03T13:45:15.000Z (18 days ago)
- Default Branch: main
- Last Pushed: 2026-06-03T13:59:25.000Z (18 days ago)
- Last Synced: 2026-06-03T15:23:18.128Z (18 days ago)
- Topics: claude-code, claude-code-plugin, plugin
- Language: Shell
- Homepage:
- Size: 35.2 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Cuckoo π¦
π¬π§ English Β· [πΊπ¦ Π£ΠΊΡΠ°ΡΠ½ΡΡΠΊΠ°](README.uk.md)
**A durable personal calendar for Claude Code.** Set a reminder for a future date (optionally a
time), and Cuckoo brings it back the next time you start a Claude Code session on or after that date
β like a cuckoo clock popping out at the right moment. It's a *tickler file* for Claude Code.
Reminders live in plain files, so they survive restarts. When nothing is due, Cuckoo costs you
essentially **zero context tokens**.
## How it works
- A **SessionStart hook** runs a tiny command (`cuckoo check`) at the start of every session. It
reads a small index and prints any due reminders β or stays completely silent.
- A **`/cuckoo:schedule`** command lets you add, list, complete, and reschedule reminders.
- Reminders are stored in two tiers:
- π **Global** β `~/.claude/cuckoo/` β personal, works in any project.
- π **Project** β `/.cuckoo/` β tied to a specific repo (git-ignored by default).
> **Session-triggered, not an alarm clock.** Cuckoo can't push to your phone, and it is not a terminal
> popup. At session start the hook hands any due reminders to Claude, which announces them in its
> **first reply once you send a message** β so a brand-new session you just stare at (without typing
> anything) shows nothing until you say something. A time of day is the *earliest* surfacing moment,
> not a real-time alert. (Calendar/push integration is on the roadmap.)
## Install
```
/plugin marketplace add driversti/claude-cuckoo
/plugin install cuckoo@cuckoo
```
Then restart Claude Code (or run `/reload-plugins`).
## Usage
```
/cuckoo:schedule add tomorrow "email the tax form"
/cuckoo:schedule add 2026-07-01 09:00 "quarterly review"
/cuckoo:schedule add next friday "call the dentist" --global
/cuckoo:schedule list
/cuckoo:schedule done call-the-dentist
/cuckoo:schedule reschedule quarterly-review "next monday 8am"
```
- Dates resolve in your local timezone; natural language ("tomorrow", "next friday 9am", "in 3
days") works.
- Default tier is **global**. Inside a git repo, if you don't pass a flag Cuckoo asks whether to
scope the reminder to the repo (**project**) or keep it **global** β pass `--global`/`--project`
to skip the prompt.
When a reminder is due, your next session opens with a note like:
```
β° CUCKOO β scheduled task(s) due
β’ [global] call-the-dentist (due 2026-06-20) -> ~/.claude/cuckoo/call-the-dentist.md
```
Claude reads the task, brings it up, offers to act on it, then asks whether to mark it done or
reschedule.
## Why near-zero token cost
The SessionStart hook runs in your shell, not in the model. It reads only a tiny index
(`date Β· status Β· slug`) and prints nothing unless something is due. The full text of a reminder
lives in its own file and is read only on the day it fires. An idle session pays only for the
one-line command description.
## Data & privacy
- Everything is local files. No network, no telemetry.
- Project reminders live in `/.cuckoo/`, which ships with a `.gitignore` (`*`) so your personal
reminders are never committed.
## Development
```bash
# Load the plugin locally without installing:
claude --plugin-dir /path/to/claude-cuckoo
# After edits:
/reload-plugins
# Run the test suite (zero dependencies):
bash tests/run.sh
```
The data layout and CLI:
```
~/.claude/cuckoo/ # global tier
βββ _index.md # DUE STATUS SLUG (tiny; the hook reads only this)
βββ .md # the reminder body (read only when due)
/.cuckoo/ # project tier (same layout, + .gitignore '*')
bin/cuckoo check | list | dir | add | remove | done | reschedule
```
## Roadmap
- **Google Calendar** two-way sync β real device push notifications.
- **In-session precision timer** β fire at the exact minute while a session is open.
- **Recurring** reminders, **snooze**.
## License
MIT Β© 2026 Yurii Chekhotskyi