Open source. Deterministic. Read-only.

Same code.
Different playbook.

Claude Code and Codex can read the same files and receive different instructions. PlaybookDiff proves exactly where.

$ npx playbookdiff check .

Watch the demo View on GitHub

Read the docs

See it catch a real mismatch.

CLI + GitHub Action · 40 seconds

Recorded against a real repository (opens in a new tab).

One launch directory apart.

Matching files are not matching configuration. Follow the paths to see why.

Where do both agents start?

The same task. A different launch location.

Start

Not received

apps/api/AGENTS.md

This instruction exists, but Codex does not receive it here. Launch from apps/api to include it.

Hover, focus, or tap a file to inspect it.

2 findings2 equivalent items. The nested instruction and skill differ in effective scope.

View evidence

CLAUDE.mdAt startup
AGENTS.mdAt startup
.claude/skills/root-skill/At startup
.agents/skills/root-skill/At startup
apps/api/CLAUDE.mdOn demand
apps/api/AGENTS.mdNot received
apps/api/.claude/skills/api-skill/On demand
apps/api/.agents/skills/api-skill/Not received

medium Claude Code has an instruction for this effective scope, while Codex has no deterministic corresponding instruction.
apps/api/CLAUDE.md
medium The api-skill skill is repository-discovered only for Claude Code, not Codex.
apps/api/.claude/skills/api-skill/SKILL.md

View CLI output

$ playbookdiff check . --cwd . --path apps/api/file.ts

PlaybookDiff

Claude Code <-> Codex

Repository: your-repo
Launch cwd: .
Target: apps/api/file.ts

Findings: 2 medium, 0 low, 0 info

MEDIUM  Instruction missing
        Claude Code has an instruction for this effective scope, while Codex has no deterministic corresponding instruction.
        Evidence:
          - Claude Code instruction: apps/api/CLAUDE.md:1-2 (repository)
            "API shared playbook."
        ID: instruction:missing:right:appliesto-apps-api-excludedfrom-loadphase-on-dem:a5921426b5e0

MEDIUM  Skill capability gap
        The api-skill skill is repository-discovered only for Claude Code, not Codex.
        Evidence:
          - Claude Code skill: apps/api/.claude/skills/api-skill/SKILL.md (repository)
            "api-skill: API shared skill."
        ID: skill:capability-gap:right:api-skill:5059ed3d0455

Summary
  Instruction 1 equivalent, 1 divergent, 0 unknown
  Skill       1 equivalent, 1 divergent, 0 unknown
  MCP         0 equivalent, 0 divergent, 0 unknown

Result: compatibility issues found

Real analyzer output. Fixture (opens in a new tab) · Verified results (opens in a new tab) · Discovery rules: Claude Code / Codex.

Run it locally, then keep it there.

01 / Check

On your machine

$ npm install -g playbookdiff
$ playbookdiff check .

Prints every proven configuration gap, with the source file behind each one, and exits non-zero on actionable findings. explain expands one finding and diff compares two Git revisions. CLI reference.

02 / Keep in sync

In pull requests

- uses: actions/checkout@v4
  with:
    fetch-depth: 0

- uses: JacobisEpic/playbookdiff@v0

The Action compares the pull request base against the head and fails only on a finding the change introduced. Divergence common to both revisions is counted and reported, never failed on, so adopting it does not mean fixing your history first. It needs contents: read and no token. Action reference.

Prefer to build from source, or read it first? The repository (opens in a new tab)

What it compares.

PlaybookDiff compiles what each harness effectively receives across three surfaces, then compares the two compilations.

Surface	Claude Code	Codex
InstructionsContent, scope, and load phase.	`CLAUDE.md` `.claude/CLAUDE.md` `imports` `nested instructions`	`AGENTS.md` `AGENTS.override.md` `fallback names` `nested chain`
SkillsDiscovery, invocation policy, and description.	`.claude/skills/*/SKILL.md`	`.agents/skills/*/SKILL.md` `agents/openai.yaml`
MCP serversTransport, command, arguments, and environment.	`.mcp.json`	`mcp_servers in .codex/config.toml`

The full supported-semantics matrix

It reports what it can prove.

Read-only: Never edits the repository it checks.
No execution: Never runs scripts, skills, binaries, hooks, or MCP servers.
No model calls: Deterministic comparison. No network, no API key.
Unknown beats guessed: Different wording is never reported as a conflict.

How each of these is enforced, and tested

FAQ

Why can't I just keep CLAUDE.md and AGENTS.md identical?

Identical files do not guarantee identical configuration, because the two harnesses do not discover files the same way. They read different filenames, build their nested instruction chains from different starting points, support different import and settings conventions, and look for skills in different directories. The example above is one real case: every file exists on both sides, and one agent still never receives two of them.

Keeping the files in step is worth doing. It is just not the same thing as proving the configuration is in step. Scope and limitations lists what is modelled on each side.

Does PlaybookDiff run Claude Code or Codex?

No. It models the documented, fixture-tested discovery rules of each harness and compiles the repository configuration each one would receive for a given launch directory and work target. The rules it models, and the official documentation behind them, are written down in the Claude Code and Codex harness specifications.

Does it send my repository anywhere?

No. There is no PlaybookDiff service to upload anything to, and the analysis never opens a connection at all: no GitHub API, no Git fetch, no MCP connection. Nothing from the repository leaves the machine.

Secrets are never resolved. ${VAR} stays symbolic, a configured literal appears only as redacted with its variable name, and MCP evidence is limited to structural facts. The security model states each property and how it is enforced.

If the configuration matches, will the two agents behave the same?

No, and PlaybookDiff never claims that. It compares supported configuration surfaces: instructions, skills, and MCP server definitions. Two agents given the same instructions can still do different things, and the report says only that no deterministic configuration difference was proven. Even the Action’s result deliberately says no-new-regressions rather than “compatible”.

What happens when it is not sure?

It says so. A result is equivalent when a deterministic rule matches, divergent when a structural difference is proven from repository evidence, and unknown when the available evidence cannot decide without guessing. Differently worded prose is the common unknown: PlaybookDiff can prove two instruction bodies differ, not that they conflict. Unknowns are informational and never fail CI. The comparison specification has the rules.

Which agents are supported?

Claude Code and Codex. Those are the two harnesses with adapters, fixtures, and written specifications, and the tool does not pretend to cover others. Additional harnesses are out of the current release scope.

Anything else is in the documentation, or worth opening an issue (opens in a new tab).

Same code.Different playbook.