Precursor Sync Agent

A lightweight CLI tool that bridges the gap between Precursor plans and actual code execution in your repository. Automatically syncs Cursor-ready rules and context from Precursor plans into your GitHub workflow.

Overview

The Precursor Sync Agent downloads plan.json files from Precursor, extracts .cursor/rules and .cursor/context.md content, and automatically creates pull requests when changes are detected. This reduces manual effort and provides full traceability for your development workflow.

Installation

npx precursor-sync-agent --plan-url <url> --repo <owner/repo> --pat <token>

Usage

Basic Sync

npx precursor-sync-agent \
  --plan-url https://example.com/plan.json \
  --repo myorg/myrepo \
  --pat ghp_your_token_here

Dry Run (Preview Changes)

npx precursor-sync-agent \
  --plan-url https://example.com/plan.json \
  --repo myorg/myrepo \
  --pat ghp_your_token_here \
  --dry-run

Verbose Output

npx precursor-sync-agent \
  --plan-url https://example.com/plan.json \
  --repo myorg/myrepo \
  --pat ghp_your_token_here \
  --verbose

Requirements

• Node.js >= 18.0.0
• GitHub Personal Access Token with repo scope
• Must be run from within the target repository

Authentication

Provide your GitHub PAT via:

• Command line: --pat your_token
• Environment variable: GITHUB_PAT=your_token

Plan Format

Your plan.json should contain:

{
  "cursorRules": "string containing cursor rules",
  "cursorContext": "string containing cursor context"
}

Output Files

The tool creates/updates:

• .cursor/rules - Cursor IDE rules
• .cursor/context.md - Cursor IDE context
• .precursor-sync/audit.json - Local audit trail

Features

• Automatic Change Detection - Only creates PRs when content changes
• Branch Management - Creates timestamped branches with collision handling
• Audit Logging - Tracks all sync operations locally
• Error Handling - Clear error messages and validation
• Dry Run Mode - Preview changes without creating PRs

Development

Setup

git clone https://github.com/AntipasBen23/precursor-sync-agent.git
cd precursor-sync-agent
npm install

Build

npm run build

Test

npm run type-check
npm run format:check
npm test

License

MIT License - see LICENSE file for details.

Author

Antipas Ben

---

Note: This is a proof-of-concept tool designed to demonstrate integration possibilities with the Precursor platform.