Scheduled Runs

A scheduled run is an unattended run of a code plugin command, recorded on the board whatever its result. The code plugin's /analyze, /monitor and /ground take --scheduled for a schedule you create, such as a desktop scheduled task in Claude Code. The flag runs the command without prompts, so a run that stopped shows on the board instead of waiting for an answer.

Set up

Create the schedule in your host, with a task prompt that passes --scheduled:

Run the /analyze task in the repo where you ran /analyze: the local analysis a scheduled run refreshes lives there. The task prompt is one line:

Run /pmap-code:analyze --scheduled.

The run pulls the latest code itself with git pull --ff-only, so the prompt needs no git step. For /monitor and /ground, pass --scheduled the same way.

A cloud routine starts from a fresh clone, which has no local analysis, so /analyze --scheduled stops there. /monitor --scheduled and /ground --scheduled can run in a routine, reading the board from ProvenMap. Set PMAP_BINDING_TOKEN and PMAP_API_SECRET in the routine's environment settings, not in its prompt.

What stops a scheduled analysis

Before it reads any code, /analyze --scheduled stops when:

• ProvenMap isn't connected in this repo
• the checkout is on a branch other than the bound one
• tracked files have uncommitted changes, so half-finished work never reaches the board
• git pull --ff-only fails: the branch needs an upstream it can reach without a credential prompt, and no local commits that aren't on that upstream
• the repo has no local analysis; run /analyze there once first

See what the runs did

Every scheduled run is recorded on ProvenMap, whether it refreshed something, found nothing to do or stopped. Its outcome is Refreshed, Up to date, Partial (it refreshed some boards and left the rest) or Stopped, with the reason.

Expand

1. 1

   Reason and fix

   A stopped run says why it stopped and what clears it.

2. 2

   The pushes it made

   Each button opens the footprint of a push the run made.

3. 3

   Scheduled marker

   A push made by a scheduled run carries this marker.

• /status lists the last five runs. When the newest one stopped, its next steps name the reason and the fix. If ProvenMap can't be reached, it lists the runs recorded in this repo instead.
• On the app board's hub, select the repo's chip on the Bindings card. Its history lists the Scheduled runs above the push sessions, each with its reason and the fix, branch, commits and board counts, and links to the pushes it made. Those pushes carry a Scheduled marker there, in their footprint and in the root hub's Recent activity. See App Boards & the Hub.
• The chip itself reads Scheduled run stopped when the newest run stopped. It reads Last scheduled run and how long ago that run started when a repo that has run on a schedule goes quiet. Quiet means no run for 48 hours, or for the workspace's own threshold.

Expand

A run that can't reach ProvenMap is kept in the repo's .provenmap/ and sent by the next run that can; a cloud routine's clone keeps no such record. Recording notifies no one. When a run is recorded, ProvenMap removes that repo's runs older than 90 days.

Fix a stopped run

The binding history shows each stopped run's reason with its fix, and /status shows the same pair for the newest run:

Expand

Change when a quiet repo is flagged

Note

Owners and admins only.

Scheduled runs gone quiet, in Workspace settings → Reporting, sets how many hours a repo can go without a scheduled run before it is flagged. The default is 48 hours, and any value from 6 to 720 hours is allowed. The value applies to every repo in the workspace, and only a repo that has run on a schedule before is flagged. Workspace Settings lists the other Reporting fields.

What's next