Skip to content

brickhouse-tech/sync-agents

BranchesTags

Repository files navigation

sync-agents

One set of agent rules to rule them all. sync-agents keeps your AI coding agent configurations in a single .agents/ directory and syncs them to agent-specific directories (.claude/, .windsurf/, .cursor/, .github/copilot/) via symlinks. This ensures all agents follow the same rules, skills, and workflows without duplicating files.

AGENTS.md serves as an auto-generated index of everything in .agents/ and is symlinked to CLAUDE.md for Claude compatibility.

Installation

npm

npm install @brickhouse-tech/sync-agents

or globally:

npm install -g @brickhouse-tech/sync-agents

Standalone (no npm required) — deprecated

Deprecated. The bash script is kept as a fallback for unsupported triples but will be removed in a future major. Prefer the npm install above; it ships native Go binaries via per-platform optional packages.

curl -fsSL https://raw.githubusercontent.com/brickhouse-tech/sync-agents/main/src/sh/sync-agents.sh -o /usr/local/bin/sync-agents
chmod +x /usr/local/bin/sync-agents

Topology

.agents/ is the source of truth. It contains all rules, skills, workflows, and state for your agents:

.agents/
  ├── config              # sync targets (claude, windsurf, cursor, copilot)
  ├── rules/
  │   ├── rule1.md
  │   ├── rule2.md
  │   └── ...
  ├── skills/
  │   ├── skill1/
  │   │   └── SKILL.md
  │   ├── skill2/
  │   │   └── SKILL.md
  │   └── ...
  ├── workflows/
  │   ├── workflow1.md
  │   ├── workflow2.md
  │   └── ...
  └── STATE.md

Note: Skills use a directory layout (skills/name/SKILL.md) rather than flat files. This allows skills to include supporting files alongside their definition. The fix command can convert legacy flat skill files to the directory layout automatically.

Running sync-agents sync creates symlinks from .agents/ subdirectories into .claude/, .windsurf/, .cursor/, and .github/copilot/. Any changes to .agents/ are automatically reflected in the target directories because they are symlinks, not copies.

AGENTS.md is also symlinked to CLAUDE.md so that Claude reads the index natively.

STATE.md

.agents/STATE.md tracks the current state of your project from the agent's perspective. It serves as a resumption point after failures or interruptions -- the agent can read STATE.md to determine where it left off and what tasks remain. Update it regularly to keep agents in sync with progress.

Commands

Command Description
init Initialize the .agents/ directory structure with rules/, skills/, workflows/, STATE.md, and generate AGENTS.md
sync Create symlinks from .agents/ into all target directories, and symlink AGENTS.md to CLAUDE.md
watch Watch .agents/ for changes and auto-regenerate AGENTS.md
import <url> Import a rule/skill/workflow from a URL
hook Install a pre-commit git hook for auto-sync
inherit <label> <path> Add an inheritance link to AGENTS.md
inherit --list List current inheritance links
inherit --remove <label> Remove an inheritance link by label
status Show the current sync status of all targets and symlinks
add <type> <name> Add a new rule, skill, or workflow from a template (type is rule, skill, or workflow)
index Regenerate AGENTS.md by scanning the contents of .agents/
clean Remove all synced symlinks and empty target directories (does not remove .agents/)
fix [type] Migrate legacy dirs into .agents/, convert flat skill files to directory layout, and repair broken symlinks. Type: skills, rules, workflows, or all (default)

Options

Option Description
-h, --help Show help message
-v, --version Show version
-d, --dir <path> Set project root directory (default: current directory)
--targets <list> Comma-separated list of sync targets (default: claude,windsurf,cursor,copilot)
--dry-run Show what would be done without making changes
--force Overwrite existing files and symlinks
--no-clobber (fix only) Skip items that already exist in .agents/ instead of merging

Configuration

sync-agents init creates .agents/config with default sync targets:

# sync-agents configuration
# Comma-separated list of sync targets (available: claude, windsurf, cursor, copilot)
targets = claude,windsurf,cursor,copilot

Edit this file to limit which targets sync writes to by default. The --targets flag on any command overrides the config.

Fix

The fix command handles three scenarios:

  1. Legacy directory migration — Moves top-level skills/, rules/, or workflows/ directories into .agents/ and replaces them with symlinks.
  2. Flat skill conversion — Converts .agents/skills/name.md flat files to the directory layout .agents/skills/name/SKILL.md.
  3. Symlink repair — Recreates missing or broken symlinks in target directories (.claude/, .windsurf/, etc.) and the CLAUDE.md symlink.
# Fix everything (all types)
sync-agents fix

# Fix only skills
sync-agents fix skills

# Preview without changing anything
sync-agents fix --dry-run

# Don't overwrite items already in .agents/
sync-agents fix --no-clobber skills

A reproducible demo is available in examples/fix/:

bash examples/fix/run-demo.sh

Inheritance

Projects can inherit agent rules from parent directories (org, team, global) using a convention-based approach. This enables hierarchical rule sharing without duplicating files.

How It Works

Add an ## Inherits section to your project's AGENTS.md that links to parent-level agent configs:

## Inherits
- [global](../../AGENTS.md)
- [team](../AGENTS.md)

AI agents (Claude, Codex, etc.) follow markdown links natively — when they read your project's AGENTS.md, they'll traverse the inheritance chain and apply rules from all levels.

Hierarchy Example

~/code/                     # Global: security norms, universal rules
  ├── .agents/
  ├── AGENTS.md
  └── org/                  # Org-level: coding standards, shared workflows
      ├── .agents/
      ├── AGENTS.md
      └── team/             # Team-level: language-specific rules
          ├── .agents/
          ├── AGENTS.md
          └── project/      # Project: project-specific rules + inherits
              ├── .agents/
              └── AGENTS.md  → ## Inherits links to team, org, global

Inheritance is upward-only. A project declares what it inherits from. Parent directories don't need to know about their children — when an agent works at the org level, it already has access to org-level rules.

Managing Inheritance

# Add an inheritance link
sync-agents inherit global ../../AGENTS.md
sync-agents inherit team ../AGENTS.md

# List current inheritance links
sync-agents inherit --list

# Remove an inheritance link
sync-agents inherit --remove global

The ## Inherits section is preserved across sync-agents index regenerations.

Full Example

Set up a three-level hierarchy: global rules → org standards → project config.

# 1. Create global rules (e.g. ~/code/.agents/)
cd ~/code
sync-agents init
sync-agents add rule security
cat > .agents/rules/security.md << 'EOF'
---
trigger: always_on
---
# Security
- Never commit secrets or API keys
- Validate all external input
- Use parameterized queries for database access
EOF

# 2. Create org-level rules (e.g. ~/code/myorg/.agents/)
cd ~/code/myorg
sync-agents init
sync-agents add rule go-standards
cat > .agents/rules/go-standards.md << 'EOF'
---
trigger: always_on
---
# Go Standards
- Use `gofmt` and `golangci-lint` on all Go files
- Prefer table-driven tests
- Export only what consumers need
EOF

# 3. Create project with inheritance
cd ~/code/myorg/api-service
sync-agents init
sync-agents add rule api-conventions

# Link to parent levels
sync-agents inherit org ../AGENTS.md
sync-agents inherit global ../../AGENTS.md

# Sync to agent directories
sync-agents sync

The project's AGENTS.md now looks like:

## Inherits
- [org](../AGENTS.md)
- [global](../../AGENTS.md)

## Rules
- [api-conventions](.agents/rules/api-conventions.md)

## Skills
_No skills defined yet._

## Workflows
_No workflows defined yet._

When an AI agent reads this file, it follows the ## Inherits links and applies rules from all three levels — project-specific API conventions, org-wide Go standards, and global security rules.

Verifying Inheritance

# Check what's inherited
sync-agents inherit --list
# Output:
# - [org](../AGENTS.md)
# - [global](../../AGENTS.md)

# Remove a link if no longer needed
sync-agents inherit --remove global

# Re-add with a different path
sync-agents inherit global ../../AGENTS.md

Examples

The examples/ directory contains ready-to-use rules, skills, and workflows. Import them directly:

sync-agents import https://raw.githubusercontent.com/brickhouse-tech/sync-agents/main/examples/rules/no-secrets.md
sync-agents import https://raw.githubusercontent.com/brickhouse-tech/sync-agents/main/examples/skills/code-review.md
sync-agents import https://raw.githubusercontent.com/brickhouse-tech/sync-agents/main/examples/workflows/pr-checklist.md

See examples/README.md for the full list.

Usage

# Initialize .agents/ structure in the current project
sync-agents init

# Add a new rule
sync-agents add rule no-eval

# Add a new skill
sync-agents add skill debugging

# Add a new workflow
sync-agents add workflow deploy

# Sync to all targets (.claude/ and .windsurf/)
sync-agents sync

# Sync to a specific target only
sync-agents sync --targets claude

# Preview sync without making changes
sync-agents sync --dry-run

# Force overwrite existing symlinks
sync-agents sync --force

# Check sync status
sync-agents status

# Regenerate the AGENTS.md index
sync-agents index

# Remove all synced symlinks
sync-agents clean

# Fix legacy layouts and broken symlinks
sync-agents fix

# Fix only skills (migrate + convert flat files + repair symlinks)
sync-agents fix skills

# Work in a different directory
sync-agents sync --dir /path/to/project

About

DRY Agent Rules, Worflflows, Skills

Resources

Readme

License

MIT license
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

1 fork
Report repository

Releases

21 tags

Packages

 
 
 

Contributors

Languages