Skip to content

PlaybookDiff v0.1.0

Choose a tag to compare

View all tags
@JacobisEpic JacobisEpic released this 01 Sep 20:15
· 28 commits to main since this release
v0.1.0
51df7bc

Initial public beta.

PlaybookDiff is a read-only compatibility checker for repositories that configure more than one coding agent. It compiles the configuration Claude Code and Codex each actually receive, compares it deterministically, and explains where the two diverge.

What it does

  • Compiles the effective Claude Code configuration for a given startup context
  • Compiles the effective Codex configuration for the same context
  • Compares instructions, including path scoping and load phase
  • Compares skills, including frontmatter fields one harness recognizes and the other does not
  • Compares MCP server definitions
  • Models --cwd versus --path scope differences explicitly
  • Checks a Git revision pair for newly introduced regressions, so pre-existing divergence never blocks anyone
  • Ships a GitHub Action for CI

Design properties

  • Deterministic: the same inputs always produce the same findings
  • Read-only: the analyzed repository is never modified
  • No model calls
  • No execution of anything from the analyzed repository (no scripts, hooks, or binaries)
  • No MCP connections
  • No secret resolution
  • Explicit unknown instead of guessing: where the evidence cannot decide a question, it says so rather than inventing an answer

Usage

The CLI is not published to npm yet. Build it from source:

git clone https://github.com/JacobisEpic/playbookdiff.git
cd playbookdiff
pnpm install
pnpm build
node packages/cli/dist/bin.js check /path/to/your/repo

Requires Node.js 24 (24.11.0 or newer, within 24.x) and pnpm 11.24.0.

GitHub Action:

on: pull_request

permissions:
  contents: read

jobs:
  playbookdiff:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: JacobisEpic/playbookdiff@v0

@v0 is a movable tag tracking the latest 0.x release. Pin @v0.1.0 or a commit SHA to control upgrades yourself.

Beta limitations

0.x means the CLI output shape, the JSON contract, and the Action's output set may still change between minor versions. Semantic comparison, PR comments, a hosted service, and additional harnesses are intentionally not implemented.

Read docs/limitations.md before relying on a result, and docs/security.md for the read-only analysis posture.

Assets 2
Loading