Guide: understand the pieces

Timers and future signals

Schedule a durable signal that an external actor can evaluate later.

Use this when

Work must be reconsidered once, at fixed intervals, or on a calendar schedule.

Do not use this when

You need Pearing to run code or guarantee completion.

Pieces involved

User, team, or repository scope One-off, interval, or calendar schedule IANA timezone timer-fired event Mentions in the message External worker or agent

Before you start

  • Choose user scope for personal reminders and team or repository scope for shared work.
  • Team timer changes require team ownership; repository timer changes require maintainer access.
  • Name the resource, desired outcome, useful skill, and relevant mention in the message.
  • Configure an external consumer to handle stale or duplicate signals.

Choose a schedule

ScheduleUse it forImportant behavior
Run in / run atOne reminder or delayed reconsideration.The timer becomes completed after firing once.
Fixed intervalPolling or maintenance based on elapsed seconds.The next run advances to a future interval.
Time of dayDaily or selected-weekday work in a human timezone.The IANA timezone controls local calendar interpretation, including daylight-saving changes.

The workflow

  1. Choose scope. Put the timer where recipients can find it and maintainers can manage it.
  2. Choose one schedule. One-off, interval, and calendar fields are mutually exclusive.
  3. Write context. Include the resource and desired result. Mentions resolve when the timer fires.
  4. Wait for the signal. A due timer creates a timer-fired event. It does not launch an agent.
  5. Read current state. Fetch the referenced resource and stop if no work remains.
  6. Record the result. Write progress or a no-change result to the thread and Git history.
  7. Manage lifecycle. Pause, reactivate with a future schedule, cancel, or delete the timer.
If the scheduler was unavailable for several recurring occurrences, it catches up once and advances to the next future occurrence. It does not replay every missed run.

Try it with the CLI

pearing-cli create-timer \
  "@platform review dependencies using repo skill dependency-maintenance; record the current result" \
  --time-of-day 09:00 \
  --days-of-week Mon \
  --timezone America/New_York \
  --repo teams/platform/website

pearing-cli list-timers \
  --status active \
  --repo teams/platform/website

pearing-cli update-timer 8f7a2ba9-8a67-4a56-a8e8-0fe9f26717f6 \
  --status paused \
  --repo teams/platform/website

pearing-cli update-timer 8f7a2ba9-8a67-4a56-a8e8-0fe9f26717f6 \
  --status active \
  --repo teams/platform/website

Using another interface

Create the same repository schedule through MCP:

Tool: create_timer
Arguments:
{
  "repo": "teams/platform/website",
  "message": "@platform review dependencies using repo skill dependency-maintenance; record the current result",
  "time_of_day": "09:00",
  "days_of_week": ["Mon"],
  "timezone": "America/New_York"
}
Create timer MCP Create timer API Create timer CLI Event history API

What success looks like

  • The scope, timezone, status, message, and next run are correct.
  • A due timer emits an event without claiming the work completed.
  • The recipient reads current state and records work or a no-change result.
  • Paused timers do not fire. Recurring timers advance to a future run.

Common mistake

A timer does not execute work and is not a background job. It emits a future signal. The recipient must still be running, authorized, and willing to inspect current state before acting.

Failure and recovery

Expect one catch-up event, not one event per missed occurrence. Read current state and let the timer advance to its next run.

Update or pause the timer, repair event routing, and inspect event history. Current state, not the old message, decides whether work remains.

Set a complete new schedule when activating it. An active timer must have a future run.

Related reference

Timers API Timers CLI Timers MCP Events and activity guide