Docs

Procore-Bot bulk-edits due dates on Procore Action Plan items. You feed it the week’s lookahead: a CSV or an Excel sheet. It reads what’s in Procore today, writes every change it wants to make to a file you can read line by line, and waits. You confirm once. Then it applies the changes, re-checks every item, and logs every write.

It runs on your own computer (or the crew’s always-on box), with your own signed-in Procore session. There are two ways to drive it: this command line, and the web console.

The five stages

1 · Preflight

Checks your file, your session, and your settings before it touches the network.

2 · Plan

Reads what’s in Procore today and writes change_plan.json, a read-only list of every date it wants to change.

3 · Review

You read the plan and confirm once. The only gate, and it’s yours.

4 · Apply

Applies the confirmed plan. Safe to stop and re-run: it never applies the same change twice.

5 · Verify

Re-checks every item and flags anything that doesn’t match what you approved.

What it will never do

• Sign items off as complete, add signatures, or create and delete sections. These are permanently out of scope. Do them in Procore directly.
• Change anything but due dates unless you switch it on. Assignee and plan-item writes (add and delete items) exist in the code but ship switched off; each needs an explicit sign-off flag to activate.
• Store your password. It borrows the session you already signed into (SSO and MFA included) and keeps it on your hardware.
• Move a date without your confirmation. The plan file is the approval; no plan, no writes.
• Model schedule logic. No predecessor locks, no dependency math. If a date is governed by a workflow, use Procore directly.

You need three things:

• Python 3.10 or newer, and the uv package manager.
• A Procore account with Action Plans Admin permission on the target project.
• A personal desktop. The tool is single-user and single-machine by design.

Install (one-time per machine)

Four commands: get the code, install the dependencies, install the browser it drives. On Windows, launch.cmd walks the same steps for you.

Sign in once

This opens a real Chrome window. Log into Procore with your normal SSO and MFA; when you can see your project list, press Enter in the terminal. The session is saved to your machine, readable by you only. Re-run it only when preflight says it expired, typically every 14-30 days.

First run

The wizard walks the whole cycle interactively (session, file, plan, confirm, apply, verify) and is the easiest way to learn the shape of it.

Every lookahead session is the same steps. On a 50-item plan the whole cycle is about ten minutes, most of it your review.

1 · Refresh your sign-in (only when it expired)

2 · Prepare the lookahead file

Build items.csv from the refined lookahead. Action Plan items have no per-item link, so each row is addressed by the plan’s URL plus the item’s exact title as displayed. A row is a due-date edit unless its action column says otherwise.

Clearing a date: put CLEAR (any case) in the date column to set an item back to “no date set.” The plan preview shows it as (clear) and the audit row records it. To restore later, apply the original date in a fresh run.

Lookahead lives in Excel? A P6 / MS Project export or a hand-kept sheet can feed the bot directly: no intermediate CSV. See Input files.

3 · Preflight

Checks everything cheap before anything expensive: Python, the browser, your session, the file, the URLs, the dates, and every assignee against the project directory, since Procore 422s any assignment to a user who isn’t active there. Fix and re-run until it’s green.

4 · Plan

Reads the current due date for every row, writes change_plan.json, and prints the diff. Plan is read-only: running it changes nothing in Procore. This is your gate; read it like you’d read a submittal.

5 · Apply

Consumes the plan, asks once, then works through it: creates first, then edits, deletes last. Progress prints per item; audit rows are written as it goes.

6 · Verify

Re-fetches every item and reports anything that doesn’t match what you approved. Run it before you call the update done.

Every command you’d actually run, in plain terms. Any of them takes --help for the full flag list.

Flags worth knowing: plan

--allow-missing

Skip rows whose title isn’t in the plan (template drift) instead of stopping. Skipped rows are marked error in the plan.

--shift-working-days N

Nudge every target date by N working days (Mon-Fri, weekends skipped), for a lookahead whose whole schedule slipped. Add --shift-section "Title" to scope it.

--sheet · --header-row

For Excel trackers with scope-specific sheets or preamble rows above the real header.

--external-schedule-config

Read a lookahead XLSX directly via a small column map. See Input files.

Flags worth knowing: apply

--resume --run-id <uuid>

Continue a stopped run. Items already applied are looked up in the audit log and skipped.

--reverse

Roll a run back: swaps current ↔ target for every change and writes a fresh run id.

--workers N

Parallel browser workers, one plan per worker at a time.

--no-confirm

Skips the confirmation prompt. For saved presets and automation only.

Input files

items.csv is the everyday input. Seven columns (two always required), addressed by plan URL + exact item title; action defaults to a due-date edit. The full column table is in the runbook.

External lookahead (XLSX): a 3-week lookahead exported from P6 / MS Project / Smartsheet, or a hand-kept forecast sheet, consumed directly. A small TOML file maps your column headers to the bot’s fields (plan_url, item_title, target_due_date, optional notes) and names the sheet and header row. Columns are matched by header name, so your column order is free.

change_plan.json is the written plan. Output of plan, input of apply and verify. It carries the run id and every proposed change; the file, not a dialog box, is what you approve.

Every run leaves a paper trail on disk, and a few commands turn that trail into something you can hand to someone.

What a run leaves behind

change_plan.json

The plan exactly as approved, in ~/.procore-bot/runs/<run_id>/.

log.jsonl

Every event in the run, timestamped, machine-readable.

resume.sh

The exact command to continue the run if it was interrupted.

data.sqlite

The audit database: every run, every write. See Audit trail.

Show your work

report writes a standalone HTML file from the audit log: counts, timings, and outcomes, accounted for line by line. It opens anywhere; no bot required to read it.

history answers the smaller question (what happened to this item) across every run that ever touched it.

digest and aging-digest summarize activity: a daily read and a weekly aging-and-blockers read. Both print to the terminal, and can post to a Slack webhook if you configure one.

The harvest sidecar exists for one situation: the bot runs on a machine that isn’t the one where you’re signed in (say, the crew’s always-on mini PC) and you’d rather not type your password anywhere new.

A small Chrome extension watches your normal, signed-in Procore tab. On demand (or automatically, if you opt in), it pushes that session (cookies, never credentials) to the bot’s box over an authenticated channel: Cloudflare Access in front, plus a shared secret. Your password and MFA never leave your browser.

• The session lands on hardware you control; nothing sits on the open internet.
• At-rest encryption for the stored session is available as an opt-in.
• A keep-alive loop stretches the session between Mondays; the extension badge counts down to expiry.
• Every push is logged to its own audit table, including whether the Cloudflare identity check passed.

Every write is remembered in a single SQLite file: ~/.procore-bot/data.sqlite. The log only grows. The bot never edits or deletes a row. Undoing something is a new run (apply --reverse), which writes its own rows and shows up in Procore’s own audit log as its own event.

What’s in it

Looking things up

Schema upgrades are automatic and additive: opening an old database with a new build migrates it in place, and your history stays.

The short version: almost everything is recoverable with --resume, and nothing the bot does is hidden from the audit trail.

A run stopped partway

Resume with the same run id. Items already applied are looked up in the audit log and skipped. That’s the idempotency contract; resuming is always safe.

Stopped it with Ctrl+C? The bot writes an executable resume.sh into the run folder with the exact command:

Rolling back

Swaps every applied change back (current ↔ target) under a fresh run id, so the rollback is itself on the record.

Common symptoms

When not to use it

• A single one-off edit: the Procore UI is faster for one item.
• Dates governed by a workflow: predecessor locks, baseline freezes. The bot doesn’t model dependencies.
• Real-time sync from an external schedule: feed it a file instead.