Keep Claude Code and Codex in sync.

PlaybookDiff checks the instructions, skills, and MCP configuration each coding agent actually receives, and catches differences before they land.

 playbookdiff check .
Get the CLIView on GitHub
playbookdiff check .1 finding
Claude CodeCodex

Instructions

CLAUDE.mdAGENTS.md

MCP servers

.mcp.json.codex/config.toml

Skills

.claude/skills/review/.agents/skills/review/
.claude/skills/deploy/not received

  • mediumSkill capability gap

An illustrative repository. The example below is pinned to a checked-in fixture.

Matching files are not matching configuration.

The two harnesses discover configuration under different rules, scopes, imports, and conventions. PlaybookDiff compiles what each one effectively receives across three surfaces, then compares those instead of the files.

SurfaceClaude CodeCodex
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

Run it locally, then keep it there.

On your machine

 playbookdiff check .

Prints every proven configuration gap, with the source file behind each one. Exits non-zero on actionable findings. Not on npm yet, so build the CLI from source.

In pull requests

uses: JacobisEpic/playbookdiff@v0

The released GitHub Action compares the pull request base against the head and fails only on newly introduced findings. Existing debt stays green.

Every file exists. One agent still never sees it.

This repository has matching root and apps/api instructions and skills for both agents, and an agent working on apps/api/file.ts. Only the launch directory changes.

Where the agent was launched
playbookdiff check . --cwd . --path apps/api/file.ts2 findings, 2 equivalent
Claude CodeCodex

Instructions

CLAUDE.mdAGENTS.md
apps/api/CLAUDE.mdnot received

Skills

.claude/skills/root-skill/.agents/skills/root-skill/
apps/api/.claude/skills/api-skill/not received

  • mediumInstruction missing in Codex

    Claude Code has an instruction for this effective scope. Codex has no deterministic corresponding instruction.

    apps/api/CLAUDE.md

  • mediumSkill capability gap

    The api-skill skill is repository-discovered for Claude Code only. Codex has not discovered it from this launch directory.

    apps/api/.claude/skills/api-skill/SKILL.md

Every file exists on both sides. Codex builds its chain from the launch directory, so from the repository root it never reaches the two nested files at all.

Reproduced from the checked-in fixture by a test that asserts both results.

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.
View on GitHubRead the limitations