Sync CLAUDE.md Files

Recursively scan project directories and create or update per-folder CLAUDE.md and AGENTS.md files with auto-detected content including languages, purpose, key files, and test indicators.

When to Use

• After creating new directories or packages

• After a major refactoring that moves files between folders

• After adding a new language or framework to the project

• Periodic maintenance to keep folder context accurate

• When onboarding a new project with many existing directories

Process

Step 1: Run Sync

Sync all directories (recursive, unlimited depth)

samuel sync

Preview changes first

samuel sync --dry-run

Only top-level directories

samuel sync --depth 1

Overwrite user-customized files

samuel sync --force

Step 2: Review Output

The command reports what happened for each directory:

• Created — New CLAUDE.md + AGENTS.md files generated

• Updated — Existing auto-generated files refreshed with current analysis

• Skipped — User-customized files preserved (no auto-gen marker)

Step 3: Customize as Needed

After syncing, review generated files and add folder-specific instructions:

• Open any generated CLAUDE.md

• Add project-specific context below the auto-generated sections

• The auto-gen marker ensures samuel sync won't overwrite your changes next time — remove it to protect the file from future updates

What Gets Detected

Detection Examples

Languages Go, Python, TypeScript, Rust, Java, etc. (by file extension)

Purpose cmd/ → entry points, internal/ → private packages, tests/ → test files

Key files main.go , package.json , Dockerfile , Makefile

Tests test.go , test.py , *.spec.ts , *.test.js

Update Strategy

Condition Action

File doesn't exist Create new file

File has <!-- Auto-generated by Samuel marker Update (overwrite)

File exists without marker Skip (user-customized)

--force flag Always overwrite

Manual Fallback

If the CLI is not available, create per-folder CLAUDE.md files manually:

folder-name

<!-- Auto-generated by Samuel. Customize with folder-specific instructions. --> <!-- AI agents load this file when working in this directory. -->

Purpose

Description of what this folder contains.

Languages

• Go (10 files)

Key Files

• main.go — Entry point

Post-Sync Verification

After running sync, verify the results:

• Check that generated content matches folder reality

• Ensure no sensitive directories received CLAUDE.md files

• Confirm AGENTS.md mirrors CLAUDE.md in each folder

• Add custom instructions where auto-detected content is insufficient