Skip to content
On this page

Scheduled Runs

A scheduled run is an unattended run of a code plugin command, recorded on the board whatever its result. Schedule each repo once and its boards, aspects and comparisons follow the code without anyone running a command. /scheduled-runs works out what the repo needs and composes the routine. You create the task in your desktop app, and come back to the same command to see how its runs are doing.

Schedule a repo

Do this once per repo. One task runs every command the repo needs, one after another.

Analyse the repo once

In the repo, on the binding's branch, run /analyze, then /sync. A scheduled run keeps that analysis current; it never builds one.

Run /scheduled-runs

It reads the repo and prints the routine. /analyze is in it for the boards, /aspects with the kinds that are on the board, /ground when the board is grounded, and /monitor when monitoring is set up. Under it come the fields for the task and a sentence you can paste into a session. Then comes anything the repo has not taken yet, such as a comparison that tracks one of its branches with no aspect to feed it.

If the repo isn't ready, the command says which check a run would stop on and what clears it. The checks are the connection, the analysis, and an origin that answers without asking for a credential.

Create the task

Where the session can create a local desktop scheduled task, /scheduled-runs offers to create it for you, and you approve it in the app. Otherwise use what it printed:

Warning

The task must be Local, in the repo's folder, with Worktree off. A cloud task or a worktree has no local analysis, so every run stops before it reads any code, and a task in another folder is never recorded. The first run recorded in the repo is the proof the task is in the right place.

In the Claude desktop app, choose Code → Scheduled → New task → Local and fill in the fields the command printed:

FieldValue
NameThe name the command printed, or any name
DescriptionOne line; the app requires it
InstructionsThe routine, as printed
FolderThe repo where you ran /analyze
ScheduleDaily, at a time the computer is usually awake
The task as the app shows it: the routine in Instructions, the repo as its folder, Worktree unselected, Daily.
  1. 1

    The routine

    Paste the instructions the command printed, one command per line.

  2. 2

    Worktree unselected

    The task runs in the repo's folder, where the analysis lives.

  3. 3

    Daily

    At a time the computer is usually awake.

Or paste the sentence the command printed into any session of the desktop app. For a repo at /path/to/my-repo whose board has aspects, it reads:

Create a local scheduled task named my-repo-upkeep that runs daily at 09:30 in /path/to/my-repo with the instructions "Run /pmap-code:analyze --scheduled. Then run /pmap-code:aspects --scheduled."

With no kind named, /aspects --scheduled extracts every kind. To keep a task to the kinds you care about, name them, as in a repo that only serves an API:

Create a local scheduled task named my-repo-upkeep that runs daily at 09:30 in /path/to/my-repo with the instructions "Run /pmap-code:analyze --scheduled. Then run /pmap-code:aspects --api --scheduled."

The Codex sentence takes the same flag in its prompt.

The task must run in the folder where /analyze ran: that folder's .provenmap/ holds the analysis the run refreshes. A task with the app's Worktree option on runs in a fresh checkout without it, and stops every time with "No local analysis in this checkout". Leave the option unselected in the task's Edit form, as it is by default. Which branch your checkout is on does not matter: the run reads the binding's branch from origin through a scratch checkout of its own and never touches yours.

A task runs while the app is open and the computer is awake. If the computer slept through a run, the app makes one catch-up run when it wakes. Keep computer awake in the app's settings keeps it from sleeping. Closing a laptop's lid still sleeps it.

Run it once and allow the tools

Open the task and choose Run now. When it asks to use the plugin, node and git, choose to always allow each one. Later runs reuse those approvals; an approval for one run only stops every later run at the same prompt. Then run /scheduled-runs again: it lists the run and its outcome.

Repeat the steps for each repo. A task runs in one folder, so each repo gets its own.

In the routineWhen /scheduled-runs adds itWhat it does each run
/analyze --scheduledThe repo has an analysed board; always firstRefreshes the boards whose files changed, syncs them, then records the change periods
/aspects --scheduledAt least one aspect kind is on the boardExtracts every kind onto the board (add --db, --api or --aspect <kind> to extract only those), and into every open comparison that tracks a branch of the repo
/ground --scheduledThe board is grounded in the repo's documentsChecks the evidence links against the documents and re-links what drifted
/monitor --scheduledYou ran /monitor setupMatches the latest production signals to the board and pushes the matches as insights
/inspect --pages --env <name> --scheduledPages are on the board, and you have already pushed page captures of your default /inspect environment from this repo yourself; always lastCaptures every page of the named environment again and uploads the page captures that changed

Typing a command with --scheduled in a session makes one run straight away; it creates no schedule.

Warning

Keep one task per repo, not one per command. If two scheduled runs in the same repo overlap, the second removes the first one's scratch checkout and the first is recorded as Stopped. One task runs its commands one after another, so they never overlap.

Note

Scheduled runs can't currently run in a Claude Code cloud scheduled task. Set them up in the desktop app on your machine, as above.

Check on the runs

Run /scheduled-runs in the repo whenever you want to know how the routine is doing. Its first line says where things stand:

  • Task created, no run recorded yet: choose Run now on the task's page. After a day without a run, the line says the task is running in the cloud, in a worktree, or in another folder, and /start says the same.
  • Running, with how long ago the last run started.
  • The last scheduled run stopped, with the reason and the fix under the table.
  • Gone quiet: no run for 48 hours, because the app or the computer was off. Run now on the task's page catches up.
  • The task's instructions are behind this repo: a command in the routine has never run, so its sentence is missing from the task. Or runs are recorded for a command the repo no longer needs. The line under the table says which sentence to add or remove.

Under the headline, the table shows each command's last run, and Worth adding lists what the repo could schedule next, such as /monitor setup or /ground. Edit the task's instructions, or pause or delete the task, on its page in the desktop app.

The same runs show elsewhere:

  • /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, both commands list 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. 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 Synced with how long ago, with a calendar-clock icon when the last sync was a scheduled /analyze or /aspects run, even one that found nothing new. A badge reads Scheduled run stopped when the newest run stopped, and Last scheduled run with how long ago when a repo has gone quiet. The governing repo's sync shows beside the app's name at the top of the hub as well.
  • The attention queue at the top of the app board's hub gets a row for the same stopped or quiet run, and so does the root hub's fleet attention. get_hub_status returns the same row to an agent.

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. Each run gives two counts, the boards it refreshed and the boards it pushed, and under them the nodes and edges its pushes added, changed and removed. Only a board whose push changed something counts as pushed.

  1. 1

    Reason and fix

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

  2. 2

    What its pushes changed

    The nodes and edges the run's pushes added, changed and removed, in total.

  3. 3

    Scheduled marker

    A push made by a scheduled run carries this marker.

A run's record holds the command, when it started and finished, and its outcome and reason. It also holds the branch and the range of commits it read, the board counts, the plugin version and the host app. A run that can't reach ProvenMap is kept in the repo's .provenmap/ and sent by the next run that can. Recording notifies no one. When a run is recorded, ProvenMap removes that repo's runs older than 90 days.

How a run reads your code

A run works in the repo the task names, because that is where the local analysis lives. It fetches the binding's branch from origin and reads its latest commit through a scratch checkout under the repo's .provenmap/ folder, which it removes when it ends. Your own checkout is never read and never changes, so the branch you are on, your uncommitted edits and your unpushed commits never stop a run. That is why the task's own Worktree option stays off: a worktree the app makes has no local analysis in it.

The run reads origin's latest through its own checkout, so nothing you are doing in yours can stop it.

Before it reads any code, the run makes three checks. The repo is connected to ProvenMap, it has been analysed there once, and it can fetch the binding's branch from origin without a credential prompt. A repo with no origin reads its local branch. A run that finds a check unmet stops before it reads any code, and records the reason. /scheduled-runs makes the same checks before you create the task.

Tip

If git asks for a passphrase or a password when it fetches, every run stops with Couldn't fetch the latest code from origin. Load your SSH key into your SSH agent or keychain, or set up a credential helper, so git fetch in the repo works without asking.

/aspects reads each branch an open comparison tracks the same way, through a scratch checkout of its own, one branch at a time. Those contracts land in the comparison; the board stays as the binding's branch pushed it.

Important

The board shows the code on origin, not your working copy. Commits you haven't pushed reach the board on the first run after you push them. If you run /analyze yourself on unpushed work, the board shows that work until the next scheduled run refreshes the boards it changed from origin.

What a run changes, and what it sends

The analysis happens locally in your own session; only derived metadata is pushed, with one exception: /inspect --pages uploads page captures of your running app. A scheduled run sends what the same commands send when you run them yourself, and leaves your work as you left it.

WhereWhat a scheduled run does there
Your checkoutNothing. Its branch, staged and unstaged changes, stashes and local branches stay as you left them.
Your repo's historyNothing. A run never commits, merges or pushes to your repo.
origin/<branch> in your repoUpdated by the fetch, as git fetch would update it. Your local branch of the same name doesn't move.
.provenmap/worktrees/Holds the scratch checkout while the run goes, which also shows in git worktree list. The run removes it when it ends. A run that crashed leaves it until the next run, or until you run a ProvenMap command in the repo other than /status or /scheduled-runs.
.provenmap/The run updates the local analysis, the plan and a log of the last 20 runs. /login adds the folder to .gitignore, so none of it is committed.
ProvenMapThe boards it refreshed, the aspects rows, the change period records, the page captures a scheduled /inspect --pages took, and the run's record. Nodes and edges carry file paths unless you turn source references off.
Your Claude Code or Codex usageThe model's part of each run is spent from the account of whoever's app runs the task. How much one run refreshes bounds it.
Warning

A scheduled /inspect --pages uploads page captures that nobody has looked at. Each one shows what the page showed to the account last signed in to the inspection browser, and a published board carries the latest capture of each page you select. The command captures only the environment its task names, and only one whose captures you have already pushed yourself. Leave its sentence out of the task when that environment holds data that should not be seen on the board.

Warning

If you run a ProvenMap command such as /analyze, /sync or /aspects in the repo while a scheduled run is going, your command wins. It removes the scratch checkout, and the scheduled run stops at its next step and is recorded as Stopped. The next scheduled run starts afresh. /status and /scheduled-runs only read, so they never stop a run.

How much one run refreshes

A scheduled /analyze refreshes at most 15 boards per run. Most boards it refreshes are analysis that runs on your Claude Code or Codex usage, in a session nobody is watching. When a board's only changes are edits to files its nodes already cover, a script refreshes it and none of that usage is spent. The limit keeps that run's cost and length bounded. An ordinary day's commits stay under it; a large merge, or a repo that hasn't run for weeks, can go over.

A run that reaches the limit refreshes and syncs 15 boards and is recorded as Partial with the reason Refresh limit reached; the next run continues. The other changed boards wait for the next run, which takes the boards that have waited longest first.

To bring every board current now, run /analyze --auto in the repo: a run you start yourself isn't held to this limit. To change the limit, set analysis.plan.maxScheduledRefreshes in the repo's .provenmap/config.json:

JSON
{
  "analysis": {
    "plan": { "maxScheduledRefreshes": 25 }
  }
}

A higher limit catches up on more in one run, and makes that run longer and costlier. Tuning settings lists the other plan settings.

Fix a stopped run

/scheduled-runs, /status and the binding history show each stopped run's reason with its fix:

ReasonFix
Not connectedRun /login to connect this project.
Couldn't resolve the board bindingRun /status to see the binding, then /login to reconnect or switch.
Couldn't fetch the latest code from originMake origin reachable without a prompt: the run reads the binding's branch from origin, so it needs network access and credentials that don't ask.
No local analysis in this checkoutRun /analyze once in this repo. A run from a worktree the app made says so and names the folder the analysis is in: turn the task's Worktree option off.
Refresh limit reached; the next run continuesNothing to fix: the next run continues. Raise analysis.plan.maxScheduledRefreshes to refresh more per run.
A round refreshed nothingRun /analyze by hand to see why those boards did not refresh.
Sync failedRun /sync to push the refreshed boards.
The command failedRun the command by hand to see the error.
Select the badged chip to open the run that stopped, with its reason and the fix.

Runs made by a plugin older than the scratch checkout can still show two retired reasons, Checkout was on another branch and Uncommitted changes in tracked files. Updating the plugin clears both, since a run no longer reads your checkout.

Change when missed runs are flagged

Scheduled runs stop when the computer is off or the desktop app is closed. After 48 hours without a run, the repo's chip on the Bindings card shows Last scheduled run and how long ago it was. The hub's attention queue gets a row for it too.

To change the wait, open Workspace settings → Reporting and set Scheduled runs gone quiet to any number of hours from 6 to 720. Only workspace owners and admins can change it. The setting applies to every repo in the workspace, and only to repos that have run on a schedule at least once. Workspace Settings lists the other Reporting fields. /scheduled-runs in the repo always uses 48 hours.

What's next

Last updated November 17, 2026