pi-wake

A pi extension that adds a /wake command and model-callable wake tool for scheduling future user messages in the current session.

This is useful when an agent starts a long-running background job (for example, a build or test run in tmux) and should check back later without blocking the foreground bash tool with sleep.

Install

pi install npm:@phillipleblanc/pi-wake

You can also install directly from GitHub:

pi install git:github.com/phillipleblanc/pi-wake

Reload or restart pi after installation:

/reload

Usage

Schedule a wake-up message:

/wake 2m
/wake 1h30s check the tmux build output
/wake 30s continue debugging the failed test

If no message is provided, pi sends continue.

Durations support ms, s, m, h, and d, including combined forms such as 1h30m, 1h30s, or 1h 30m.

Commands

/wake <duration> [message]  Schedule a future user message
/wake list                  List active pi and ad wake jobs
/wake cancel [message]      Cancel the wake job for a message; defaults to "continue"
/wake clear                 Cancel all wake jobs

Multiple wake jobs can be active at once, keyed by message. Scheduling the same message replaces the previous job for that message:

/wake 2m
/wake 5m

The second command replaces the first because both use the default continue message.

Model tool

The extension also registers an LLM-callable tool named wake with this shape:

{
  "duration": "2m",
  "message": "check tmux build"
}

Tool guidance tells the model to use wake when waiting for long-running background jobs instead of calling sleep in the foreground bash tool.

Footer

When a wake job is active, the existing pi footer shows the next wake after context usage:

36.7%/400k (auto) • next wake: 10s

The countdown refreshes about every 10 seconds while wake jobs are active. Pending ad wake timers are included in that countdown. Script and PID wakes, which fire when a process exits, show as watching.

ad wakes

When this session has an ad identity and ad is on PATH, pending ad wake jobs are included in the footer and /wake list. pi-wake only displays them. ad delivers its own reminder, so pi-wake does not send a message or notification when an ad wake fires.

/wake cancel and /wake clear do not change ad jobs. Cancel those with ad wake cancel or ad wake clear.

Notes

Wake jobs are session-scoped and run while the pi process is alive. They are restored from the current session branch on reload or session-tree navigation when possible. ad wakes are read from ad and are not stored in the pi session.