🦉 nightowl
A tiny Claude Code plugin that notices when you're working late at night,
nudges you to get some sleep, and saves a handoff summary so you can stop now
and pick up tomorrow without re-discovering everything.
Four pieces:
late-check hook (UserPromptSubmit) — checks the local clock on each
prompt. Inside the late-night window it injects a one-line reminder telling
Claude to suggest wrapping up and mention /roost. The tone escalates the
later it gets (gentle → firm → urgent). Rate-limited so it nags at most once
every 30 min.resume-check hook (SessionStart) — when a recent /roost handoff
is sitting in .nightowl/, injects a one-line pointer so Claude reminds you
that you can /rouse to resume. Surfaces once per handoff, and prunes
stale handoffs so the folder doesn't grow forever./roost skill — writes a dated handoff summary to
.nightowl/handoff-YYYY-MM-DD-HHMM.md and prints it in chat: what you did,
where you left off (file:line), in-flight work (Cache), dead ends you
already hit (Pellet), open next steps, gotchas, and the command to resume./rouse skill — the counterpart: loads the latest handoff,
re-grounds it against current git state (flagging anything that changed
overnight), recovers the Cache, respects the Pellet, and tees up the next step
so you start oriented.
Owl instincts
The skills aren't just owl-named — each step is framed as a real owl capability,
so the bird is a mnemonic for an actual best-practice. No flavor without value.
| Owl trait | What it does in the skill |
|---|
| 📡 Facial disc (funnels sound to the ears) | /roost sweeps the whole session and funnels it to signal — distill, don't dump. |
| ✊ Talon grip (two-forward-two-back crush hold) | The handoff grips exact state so nothing leaks overnight. |
| 📦 Cache (owls stash uneaten prey) | A handoff section for in-flight work — a stash, a WIP edit, a forgotten branch — that git won't show and you'd silently lose. |
| 🦴 Pellet (owls cough up indigestible bones) | A handoff section for approaches you already tried that didn't work — so tomorrow-you doesn't re-chew a dead end. |
| 🪶 Silent flight (prey hears nothing) | /roost is read-only — it writes one file and disturbs nothing: no commit, no push. |
| 👁️ Night vision (max light in near-dark) | /rouse reconstructs a full session from one sparse handoff. |
| 🔄 270° head swivel (look behind without moving) | /rouse scans both ways: drift since the handoff, and forward to recover the Cache. |
| 🎯 Asymmetric ears (pinpoint prey in total dark) | The morning brief lands on one exact next move — file:line, not a vague direction. |
Requirements
The hook and statusline are POSIX shell scripts (bash), so they run on
macOS and Linux out of the box. Windows is not supported — there's no
native bash, and no PowerShell (.ps1) twin is shipped. Windows users would
need WSL, Git Bash, or a port. (The /roost and /rouse skills are
just instructions to Claude and work anywhere; only the late-night hook and the
statusline owl are shell-dependent.)
How it works
The hook reads the system clock with date, so it follows your machine's local
timezone — no config needed. State for throttling lives in
$TMPDIR/nightowl-last-nag-<project> — keyed by the current project directory,
so parallel Claude sessions in different projects each nag on their own clock
instead of sharing one machine-wide timer. The hook never blocks or fails your
prompt: on any error it exits cleanly and your request goes through.
The /roost summary is written under .nightowl/ in the current project
(git-ignored by default), named handoff-YYYY-MM-DD-HHMM.md so a second wrap-up
the same day doesn't clobber the first. /rouse reads the newest
handoff-*.md back out of that folder. The resume-check hook also looks there
at session start: if the newest handoff is recent it nudges you to
/rouse, and it prunes handoffs older than the retention window.
Install
As a plugin (recommended)
This repo is its own Claude Code plugin marketplace. Add it, then install:
/plugin marketplace add tkrisztian95/nightowl-claude-plugin
/plugin install nightowl@nightowl
(nightowl@nightowl = the nightowl plugin from the nightowl marketplace.)
Update later with /plugin marketplace update nightowl.
Manual (no marketplace)
Without the marketplace you can clone the repo and wire it up by hand: copy
skills/roost and skills/rouse into ~/.claude/skills/, and replicate
hooks/hooks.json into ~/.claude/settings.json with
${CLAUDE_PLUGIN_ROOT} swapped for the absolute clone path. The plugin install
above does all of this for you — prefer it unless you can't use a marketplace.
Configuration
Override via environment variables (defaults shown):
