pi-wakeup

Singleton wake-up scheduler extension for the pi coding agent.

Start Here

• Project Context
• Open Backlog
• Changelog
• Documentation

Features

• WAKEUP.md is the durable schedule
• /wakeup-start selects the active pi instance
• /wakeup-stop explicitly releases the scheduler lock
• wakeup tool: check, schedule, done
• The wakeup tool is active only in the singleton owner session, keeping inactive pi contexts free of schedule prompt guidance
• Footer status: wakeup off, wakeup on, or wakeup [hh:mm:ss]
• Fired tasks become [~] until closed with wakeup done or wakeup done N
• If pending tasks become overdue while another task is [~], the oldest one fires after the current task is closed
• Wake-up messages and schedule checks include monotonically increasing task indexes
• Completed tasks are kept while work remains, then WAKEUP.md resets to the empty template when all tasks are done

Install

From npm:

pi install npm:@llblab/pi-wakeup

From git:

pi install git:github.com/llblab/pi-wakeup

Usage

/wakeup-start
wakeup schedule "in 10m | Read one AAA spec section deeply"
wakeup check
wakeup done
/wakeup-stop

Scheduling

Schedule with relative time to avoid timezone mistakes:

wakeup schedule "in 10m | Review WAKEUP.md"
wakeup schedule "1h30m | Deep work checkpoint"
wakeup schedule "2026-04-28T15:00:00Z | Absolute UTC task"

Supported duration units: s, m, h, d.

WAKEUP.md

Entries are stored as UTC ISO 8601 timestamps:

# Wakeup Plan

> Flat list of scheduled agent awakenings
> Format: `N. [status] YYYY-MM-DDTHH:MM:SSZ | action`
> N: task index, starts from 3
> Status: ` ` pending, `x` done, `~` in progress
> Timestamps are stored as UTC ISO 8601

---

0. [x] 2026-04-28T10:00:00Z | Finished task
1. [~] 2026-04-28T11:00:00Z | Current fired task
2. [ ] 2026-04-28T12:00:00Z | Future task

---

WAKEUP.md keeps human-edited order. > N: task index, starts from ... stores the next task index. Use direct file edits for rescheduling or removing tasks.

Runtime

• WAKEUP.md is editable schedule state and stores the next task index in > N: task index, starts from ...
• locks.json stores { "@llblab/pi-wakeup": { "pid": ..., "cwd": ... } }
• Timers are rebuilt from WAKEUP.md on startup, tool edits, and manual file changes
• Only the locked pi process sends ⏰ Wakeup
• Only the locked pi process keeps the wakeup tool active in the agent context
• /wakeup-start can move singleton ownership here when another live pi instance owns the lock
• /new and process restarts resume explicit ownership from the lock when pid/cwd semantics allow it
• The footer countdown is updated from cached schedule state, not by rereading WAKEUP.md every second
• No cron, daemon, or external service

Architecture overview: docs/architecture.md Lock standard: docs/locks.md