docsync

Catch outdated documentation before you commit. docsync reads your staged Git changes and runs a swarm of local Cursor SDK agents in parallel — each one reviewing a small batch of your repository's docs — then merges their findings into a single docs-impact report. By default it can also block the commit when the impact is significant.

It does not edit your documentation for you. It tells you what to update and why. Soon we'll add a option to fix as well!

Install

Install the CLI globally:

npm install -g @buondevid/docsync

Or run one-off commands without installing:

npx @buondevid/docsync doctor

Requirements:

• Node.js (used by the CLI).
• Git (docsync runs inside a Git repo and reads the staged diff).
• A CURSOR_API_KEY with access to the Cursor SDK.

Quick Start

1. Set your Cursor API key. Either export it in your shell:

   export CURSOR_API_KEY="your-key"

   or add it to your repository's .env file (kept out of Git):

   CURSOR_API_KEY="your-key"

   docsync automatically loads .env from the repo root.

2. Verify the SDK is reachable in the repo:

   docsync doctor

3. Install the pre-commit hook so future commits are checked automatically, and run a first manual check:

   docsync init
   docsync check --staged

4. Add the generated report and summary cache to .gitignore:

   docsync-report.md
   .docsync/

docsync init creates docsync.config.json with defaults, respects the repository's configured Git hook path (including Husky's user-owned .husky/pre-commit), and starts docsync index in the background when CURSOR_API_KEY is set.

Commands

| Command | Description | | --- | --- | | docsync init | Install the pre-commit hook and create docsync.config.json if missing. | | docsync check --staged | Run the docs-impact check on staged changes. | | docsync doctor | Verify the Cursor SDK is reachable and that the configured model exists. Prints the available model IDs and how many documentation files docsync would review (and the resulting swarm size). | | docsync index | Build or refresh the optional documentation summary index. | | docsync clean | Remove only the docsync block from the pre-commit hook. Does not delete docsync-report.md or .docsync/. |

Common flags for docsync check

| Flag | Purpose | | --- | --- | | --fail-on <level> | Block the commit at this confidence level or above. One of off, low, medium, high. | | --model <id> | Override the configured Cursor model for this run (for example composer-2). | | --json | Emit machine-readable JSON instead of human output. | | --debug | Include SDK diagnostics in stderr and the Markdown report. |

If you want docsync to keep updating the Markdown report but never block a commit, set "blockCommits": false in docsync.config.json rather than --fail-on off.

Generated Files

• docsync.config.json stores repository-specific configuration. If it is deleted, docsync falls back to its built-in defaults.
• docsync-report.md contains the latest documentation impact report. Existing notes outside docsync's generated block are preserved.
• .docsync/index.json stores optional documentation summaries used to pick relevant docs faster in larger repositories.

Configuration

Create docsync.config.json in the repository root to override defaults:

{
  "docGlobs": ["README*", "**/*.md", "**/*.mdx", "**/*.txt", "**/*.rst", "**/*.adoc", "**/*.asciidoc"],
  "ignoreGlobs": [
    "**/node_modules/**",
    "dist/**",
    ".git/**",
    "coverage/**",
    "docsync-report.md",
    ".docsync/**",
    ".claude/**",
    ".cursor/**",
    ".github/copilot-instructions.md",
    ".github/instructions/**",
    ".github/prompts/**",
    ".windsurf/**",
    ".roo/**",
    ".clinerules/**",
    "AGENTS.md",
    "**/AGENTS.md",
    "CLAUDE.md",
    "**/CLAUDE.md",
    "GEMINI.md",
    "**/GEMINI.md"
  ],
  "maxDocFiles": 100,
  "docsPerAgent": 10,
  "maxDocBytes": 64000,
  "maxDiffBytes": 120000,
  "blockCommits": true,
  "failOn": "medium",
  "model": "default",
  "reportPath": "docsync-report.md",
  "indexPath": ".docsync/index.json",
  "autoIndex": true,
  "debug": false,
  "timeoutMs": 120000
}

| Option | Default | Description | | --- | --- | --- | | model | default | Cursor model used for SDK runs. Keep default to let Cursor pick, or set a specific id (for example gpt-5.4-nano is a good lightweight option for structured documentation review). Run docsync doctor to see the model ids available to your API key. | | blockCommits | true | Whether docsync can stop a commit. Set to false to keep writing the Markdown report while letting the commit through. | | failOn | medium | Minimum confidence level that fails the run. One of off, low, medium, high. | | maxDocFiles | 100 | Maximum number of ranked documentation files reviewed per run. Protects API usage, rate limits, and final-assembly prompt size. | | docsPerAgent | 10 | Documentation files per parallel Cursor SDK agent. Lower values mean more parallel agents but more requests. | | maxDocBytes | 64000 | Per-doc byte cap when reading documentation excerpts. Larger files are truncated. | | maxDiffBytes | 120000 | Cap on the staged diff sent to the agent. Larger diffs are truncated. | | docGlobs | text docs | Git-tracked documentation files to consider. Limited to text formats, so broad globs like docs/**/* won't pick up binaries. | | ignoreGlobs | generated and agent files | Excludes generated files and common AI-agent instruction files (AGENTS.md, .cursor/**, etc.). Override if your project treats those as product docs. | | reportPath | docsync-report.md | Where the Markdown report is written. Keep it ignored so the report doesn't become documentation input. Content outside docsync's generated block is preserved. | | indexPath | .docsync/index.json | Where docsync stores doc summaries. When the repo has more docs than maxDocFiles, docsync check uses this index, if present, to pick the most relevant docs first. | | autoIndex | true | Start docsync index in the background after each check so the next run has fresh summaries. Does not block the current check. | | debug | false | Include SDK diagnostics in stderr and the Markdown report. The --debug flag enables this for a single run. | | timeoutMs | 120000 | Maximum Cursor SDK run time before docsync tries to cancel it. |

How It Works

docsync check --staged:

1. Resolves the Git repo root and reads staged files plus git diff --cached.
2. Discovers documentation files from Git-tracked files matching docGlobs (and not matching ignoreGlobs).
3. Splits the selected docs into batches of docsPerAgent files. Each batch is reviewed by its own local Cursor SDK agent, all running in parallel. With the defaults, 100 docs become roughly 10 concurrent agents.
4. Writes each agent's result to its own temporary JSON file. When every agent returns clean, structured findings, docsync merges them deterministically — no extra model call is needed.
5. If any agent returns raw output, SDK diagnostics, or inconsistent JSON, a final Cursor SDK agent merges the swarm's outputs into one docs-impact report.
6. Prints a concise summary and writes the full Markdown report to docsync-report.md.
7. When autoIndex is enabled, starts docsync index in the background for the next run.

You can tune the swarm with docsPerAgent (lower = more parallel agents, smaller prompts) and maxDocFiles (cap on how many docs are reviewed at all).

The pre-commit hook installed by docsync init runs docsync check --staged. It never edits documentation for you.

When --debug is passed, or Cursor returns an error, no text, or non-JSON output, the Markdown report includes diagnostics such as run status, agent ID, run ID, status events, tool calls, parse errors, remediation steps, and raw response text when available.

Development

npm install
npm run check
npm test
npm run build
npm link

Re-run npm run build after editing TypeScript source. You only need to run npm link again if the link was removed or you switched checkouts.

Test the linked CLI in another repo:

cd /path/to/target-repo
docsync doctor
docsync index
docsync check --staged

Inspect package contents before publishing:

npm pack --dry-run

Publishing

package.json publishes the docsync binary from dist/cli.js, links the npm package to github.com/buondevid/docsync, and includes only dist, README.md, and docsync.config.example.json.

Publish a new release:

npm login
npm run check
npm test
npm run build
npm version patch
npm publish --access public
git push origin main --follow-tags
gh release create "$(git describe --tags --abbrev=0)" --generate-notes --title "$(git describe --tags --abbrev=0)"

Use npm version minor or npm version major when the release is not a patch. The package is scoped as @buondevid/docsync, so --access public is required on the first public publish.

gh release create creates the GitHub release page using GitHub's generated notes as the changelog.