nudgr

name: nudgr description: Schedule reminders, sync to calendar, and launch unattended Claude Code sessions in tmux. Triggered when the user wants to set a reminder ("remind me about X in 5 days"), schedule work for later ("add this to my calendar"), ask "what's coming up?", recall recent completions ("what did we ship 3 weeks ago?"), or schedule an unattended Claude session ("kick off a Claude session next Monday at 9am to do X"). The skill calls the local `nudgr` CLI for all operations and never re-implements logic. tools: Bash, Read

Local-first task scheduling, calendar sync, and Claude session launcher. The skill is a thin wrapper around the nudgr CLI — its job is to translate natural-language requests into CLI calls and surface results in the user's voice.

When to invoke

"Remind me about X in N days/weeks/hours"
"Add Y to the calendar" / "schedule Y for "
"What's coming up?" / "what's on my plate?"
"What did we finish last week / 3 weeks ago / recently?"
"Schedule a Claude session at to "
The SessionStart hook has surfaced upcoming or missed items and you need to act on them
The user references a nudgr-context block in the conversation

Do NOT invoke for narrow questions about scheduling logic ("what does cron 0 9 * * 1-5 mean") — that's general knowledge, not a nudgr operation.

Core flow

User: "remind me to review the audit doc tomorrow at 9"
Skill → nudgr add "review the audit doc" --due "tomorrow 9am"
Skill confirms briefly: "Added — pinged tomorrow at 9am, also on your calendar."

Never narrate every CLI call you're going to make. Just make it and report the result.

CLI cheatsheet

Full reference in docs/cli-reference.md. Most-used:

nudgr add "<title>" --due <when> [--project <p>] [--rrule <RRULE>] [--on-miss <policy>]
nudgr upcoming [--days N] [--format json|table|claude-prompt]
nudgr history --since "3 weeks ago" [--grep <q>] [--project <p>]
nudgr done <id>
nudgr defer <id> --to <when>
nudgr cancel <id>

nudgr schedule "<task>" --at <ts> --working-dir <path> --mode autonomous|safe [--yes]
nudgr sessions list
nudgr sessions logs <id>
nudgr sessions attach <id>

nudgr sync [--provider google|eventkit]
nudgr calendars
nudgr config show
nudgr doctor

Voice rules (important)

See docs/voice.md for full guidance. Summary:

If nudgr upcoming --days 7 is empty and there's no missed item, say nothing about scheduling.
1-2 upcoming items: mention conversationally if natural, offer to start one if relevant.
More than 2 upcoming: surface only the most relevant given current conversation. Offer "want me to list the rest?"
Missed items (on_miss=ask): bring up explicitly. "Last Friday's drift check didn't fire — laptop was probably asleep. Want me to run it now?"
Never dump the whole <nudgr-context> block at session open. The user has eyes on it; you don't need to recite it.
Past-tense recall ("what did we finish?"): hit nudgr history --json and answer from the result.

Common patterns

Casual reminder

User: "remind me to follow up with the lawyer next Wednesday"
Skill: `nudgr add "follow up with the lawyer" --due "next Wednesday"`
Reply: "Added — calendar will ping you Wednesday."

Recurring task

User: "every Monday at 8am, do a quick review of last week's PRs"
Skill: `nudgr add "review last week's PRs" --due "next Monday 8am" --rrule "FREQ=WEEKLY;BYDAY=MO"`
Reply: "Set — recurring weekly Mondays at 8am."

Unattended Claude session

User: "schedule a Claude session for June 14 at 9am to audit the webapp-template-stack skill"
Skill: First check if a prompt file is needed; if the user gives free text, write it to a temp MD then pass via --prompt-file. Otherwise pass the title and let Claude pick up context from the working dir.
Skill: `nudgr schedule "audit webapp-template-stack" --at 2026-06-14T09:00 --working-dir ~/.claude/skills/webapp-template-stack --mode autonomous --yes`
Reply (always include the trust-boundary warning verbatim, even when --yes is used so confirmation didn't trigger):
  "Scheduled #N — fires June 14 9am.
  ⚠ Autonomous mode runs Claude with full tool access (no approval prompts for
  Write/Edit/Bash). The prompt is the trust boundary. Want approval prompts in
  your notification bar instead? Just say 'use safe mode' and I'll re-schedule."

Autonomous trust-boundary vocabulary (IMPORTANT)

When the user schedules a Claude session, always surface the autonomous-mode warning in chat — even when nudgr's CLI confirmation is suppressed by --yes or by config.scheduling.confirm_autonomous=false. The warning is the user's permanent visibility into what they just authorized.

If the user expresses any of these in natural language, schedule with --mode safe (CLI alias for interactive) instead:

"use safe mode" / "with approvals" / "ask me before tool use"
"I want to approve / want to confirm before it does anything"
"this is risky" / "be careful"
"interactive" / "let me see what it's doing"

--mode safe (or equivalently --mode interactive) creates a tmux session that pre-loads the prompt and waits for the user to attach. Claude runs with normal permission prompts; the user approves each tool call. The notification when the session fires gets an "Attach to approve" button that opens the user's preferred terminal at the tmux session.

Default is autonomous unless the user signals otherwise. Don't ask "autonomous or safe?" on every schedule — that's friction. Just default to autonomous, surface the warning, and let the user redirect to safe if their reply suggests caution.

Recall (history)

User: "what did we ship like 3 weeks ago?"
Skill: `nudgr history --since "4 weeks ago" --until "2 weeks ago" --format json`
Skill: parse, summarize 3-5 most relevant items with dates.

Acting on a missed item

<nudgr-context>
Missed (need decision):
- 2026-05-01 03:00 (2 days ago): Weekly skill drift check
</nudgr-context>

You (when first turn allows): "Heads up — last Friday's drift check didn't fire. Want me to kick it off now, defer 24h, or skip this round?"
After answer: `nudgr <action> <id>`.

SessionStart hook

This is the wiring that makes nudgr surface itself automatically. Configure in ~/.claude/settings.json:

{
  "hooks": {
    "SessionStart": [
      { "command": "nudgr upcoming --days 14 --format claude-prompt", "timeout": 3000 }
    ]
  }
}

The output appears in your context as a <nudgr-context> block: upcoming items, missed items needing a decision, and recent completions. Use it; don't recite it.

Setup pointer

Setup steps (install nudgr, grant Calendar permission, OAuth Google, install dispatcher) live in docs/setup.md. If the user is just starting, walk them through that file rather than re-deriving the steps.