Automatically Synchronizing CLAUDE.md with AGENTS.md

Codex uses AGENTS.md, while Claude Code uses CLAUDE.md.

Despite containing nearly identical content, these files exist in separate locations. You fix one version while leaving the other outdated.

To address this issue, I created agent-sync, a command-line interface tool.

go install github.com/lef237/agent-sync@latest
agent-sync

What it does

With AGENTS.md serving as the definitive source, this tool generates only a thin adapter for Claude Code.

The generated CLAUDE.md contains only this minimal content:

<!-- agent-sync:start -->

@AGENTS.md

<!-- agent-sync:end -->

The @AGENTS.md syntax is a Claude Code import directive that loads the AGENTS.md file from the same directory.

The key point is that it doesn’t copy the content, as any manual copy would immediately reintroduce the dual-management problem.

Regarding Skills, since it’s a symlink, if you edit .agents/skills/review/SKILL.md, those changes will automatically propagate to Claude Code as well.

Only when adding or removing Skills does synchronization need to be performed.

Manually Written Content Remains Intact

The agent-sync system leaves everything outside the marker untouched.

<!-- agent-sync:start -->

@AGENTS.md

<!-- agent-sync:end -->

## Claude-Specific Notes

This section will not be overwritten by agent-sync.

The same applies to any files you manually place in .claude/skills/.

Even if there’s a file with the same name, it will not override your version and will instead issue a warning and step back.

Usage

agent-sync              # Perform synchronization
agent-sync --dry-run    # Just preview what changes would occur
agent-sync --check      # Exit with status 1 if there are differences
agent-sync --version

It determines the repository root by traversing upwards through .git, then searches for AGENTS.md.

Even if the file is nested under services/billing/AGENTS.md, it will create a CLAUDE.md file in the same directory.

If AGENTS.override.md exists, it will import that instead (following Codex’s priority system).

Note: Only the .agents/skills/ directory at the repository root is checked for Skill files, as Claude Code specifically reads .claude/skills only from the project’s root directory.

Integrating with CI

Since --check returns an exit code of 1 when differences are detected, it can be directly integrated into CI pipelines.

- run: go install github.com/lef237/agent-sync@latest
- run: agent-sync --check

This configuration will prevent pull requests from proceeding if AGENTS.md has been added but the corresponding CLAUDE.md file was forgotten, ensuring the issue gets addressed before review.

Performing cleanup operations

.claude/.agent-sync.json maintains a record of “what agent-sync created.”

This tracking mechanism ensures that when pulling changes back, you can accurately restore only your own modifications.

• When a Skill is deleted, the corresponding symlink will also be removed
• When AGENTS.md is deleted, the corresponding management block will also be retracted.
  • If CLAUDE.md contained only adapter definitions, it will be deleted; for files with manually edited sections, only those portions will be preserved

After implementation

The most critical aspect was maintaining strict “non-intervention” principles.

As a tool that modifies files in other repositories, it adopts a policy of “when in doubt, don’t modify - and if you can’t avoid it, issue a warning rather than silently proceeding.”

• All write operations use temporary files followed by rename operations
• If unexpected content is present in target locations, it won’t overwrite but will instead produce an error
• It never writes to locations accessed through symlinks

Licensed under the MIT License. If you’re interested, please give it a try.

GitHub - lef237/agent-sync: Sync Codex instructions and skills to Claude Code.

Sync Codex instructions and skills to Claude Code. - lef237/agent-sync

github.com