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 --forceStep 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 syncwon'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 pointPost-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