Skip to content

Claude Project Sync

This page explains how the automated Claude Project sync notification system works, how to configure it, and what to do when you receive a sync notification.

How It Works

Every time a pull request is merged into main, GitHub Actions runs a workflow that:

  1. Detects which .md files changed in the push
  2. Reads claude-projects.yml at the repo root to determine which Claude Projects contain those files
  3. Posts a Slack notification listing the changed files, the affected projects, and clear instructions for re-uploading

This ensures the Doc Syncer (currently Joshua Curci) is always notified when a Claude Project needs updating — without needing to manually track what changed.

The workflow only fires if at least one .md file changed. Other file types (images, config files, etc.) do not trigger a notification.

Files Involved

File Purpose
claude-projects.yml Config file defining all projects, their doc patterns, and project IDs
.github/workflows/claude-sync-notify.yml GitHub Actions workflow that detects changes and sends the notification
scripts/sync-check.js Node.js script used by both the workflow and the Doc Syncer locally
scripts/package.json Dependencies for the scripts (js-yaml, minimatch)

Receiving and Acting on a Slack Notification

When a merge triggers the workflow, a message arrives in the Slack channel connected to the SLACK_WEBHOOK_URL secret. It will show:

  • Which .md files changed
  • Which Claude Projects are affected (with direct links if project_id is set)
  • Step-by-step instructions for re-uploading

What to do

  1. Pull the latest main locally: 
    git checkout main && git pull origin main
  2. Open each affected project at claude.ai/projects
  3. In the project knowledge base, find each file listed in the notification
  4. Click ... next to the file → Delete
  5. Click Upload files and re-upload the updated version from your local clone
  6. Start a test chat inside the project and ask a question related to the updated content — confirm Claude references the new version

Always delete before re-uploading. Claude does not auto-update files. Uploading without deleting first creates a duplicate.

Filling in project_id Values

When you first create a project in Claude, you need to copy its ID into claude-projects.yml so the Slack notifications include direct links.

  1. Go to claude.ai/projects and open the project
  2. Copy the ID from the URL: https://claude.ai/project/<project_id>
  3. Open claude-projects.yml and paste the ID into the matching project_id field: 
    - name: "Trove Internal Knowledge"
  project_id: "abc123xyz"   # ← paste here
  4. Commit and push the change — future Slack notifications will include a direct link to the project

Adding a New Claude Project

  1. Create the project in Claude at claude.ai/projects
  2. Add an entry to claude-projects.yml: 
    - name: "My New Project"
  project_id: ""            # fill in after creating
  instructions: >
    One or two sentences describing what this assistant is for.
  docs:
    - docs/section/*.md
    - docs/other/specific-file.md
  3. Upload the relevant docs to the new project manually (first-time setup)
  4. Commit and push claude-projects.yml — future merges will notify you when those docs change

Adding or Moving a Doc to a Different Project

To include a file in an additional project, add its path (or a glob pattern that matches it) to that project's docs list in claude-projects.yml.

To move a doc out of a project, remove it from the docs list. Note: you also need to manually delete it from the Claude Project knowledge base — the automation only notifies, it does not delete or upload files automatically.

Glob pattern examples

docs:
  - docs/brand/*.md           # all .md files directly in docs/brand/
  - docs/**/*.md              # all .md files anywhere under docs/
  - docs/operations/breach-response-plan.md   # a single specific file

Running the Sync Check Locally

The Doc Syncer can run sync-check.js at any time to check what would need updating without triggering the full workflow.

Install dependencies (first time only)

cd scripts
npm install
cd ..

Check what changed since the last commit

node scripts/sync-check.js

Check since a specific commit

node scripts/sync-check.js --since abc1234

Replace abc1234 with any valid commit hash. You can find recent hashes with:

git log --oneline -10

Example output

=== Claude Project Sync Check ===

Changed .md files (2):
  - docs/operations/acceptable-use-policy.md
  - docs/security/information-security-policy.md

Affected Claude Projects (1):

  Project : Trove Internal Knowledge
  URL     : https://claude.ai/project/abc123xyz
  Files to re-upload:
    - docs/operations/acceptable-use-policy.md
    - docs/security/information-security-policy.md

To sync: open each project at https://claude.ai/projects, delete the
old version of each file, and re-upload from your local clone.

Setting Up the Slack Webhook

The workflow posts to Slack via an incoming webhook URL stored as a GitHub Secret.

Create the webhook

  1. Go to your Slack workspace → Apps → search for Incoming Webhooks
  2. Click Add to Slack
  3. Choose the channel to post to (e.g. #wiki-updates)
  4. Copy the webhook URL

Add it to GitHub Secrets

  1. Go to the wiki-and-docs repository on GitHub
  2. Click Settings → Secrets and variables → Actions
  3. Click New repository secret
  4. Name: SLACK_WEBHOOK_URL
  5. Value: paste the webhook URL
  6. Click Add secret

Updating the webhook URL

If the webhook URL changes (e.g. the Slack app is re-installed or the channel changes):

  1. Follow the steps above to create a new webhook URL
  2. Go to Settings → Secrets and variables → Actions in the repo
  3. Find SLACK_WEBHOOK_URL and click Update
  4. Paste the new URL and save

The workflow will use the new URL on the next push to main — no code changes required.

Troubleshooting

No Slack message arrived after a merge

  • Check the Actions tab in the GitHub repo to see if the workflow ran
  • If it ran and passed, check that SLACK_WEBHOOK_URL is set correctly in GitHub Secrets
  • If the workflow was skipped, confirm that at least one .md file was included in the merge

The Slack message shows "(project_id not set)"

The project_id field in claude-projects.yml is empty for that project. Fill it in with the ID from the project URL on claude.ai.

A changed file is not showing up in the affected projects list

Check that the file's path matches one of the glob patterns in claude-projects.yml for that project. Run the local sync check to test:

node scripts/sync-check.js --since HEAD~1

Duplicate files in the Claude Project knowledge base

This happens when a file was re-uploaded without deleting the old version first. Manually delete all duplicates in the Claude Project and keep only the most recently uploaded version.