One .agents/ directory. Every AI coding assistant. Always in sync.
sync-agents is a package manager and sync engine for AI-agent context — the rules, skills, workflows, subagents, plans, and specs you feed to Claude, Cursor, Windsurf, Copilot, Codex, opencode, and OpenClaw. Write everything once in .agents/, and sync-agents delivers it to every tool at the path that tool reads, and lets you pull shared context from other repos as safely and reproducibly as you'd install an npm package.
If you use more than one AI coding tool — or more than one repo — you already know the pain: the same rules copy-pasted into .claude/, .cursor/, .windsurf/, and .github/copilot/, drifting apart the moment you edit one of them. Team conventions living in a wiki nobody's agent reads. A "cool skill" pasted from the internet with zero review of what it actually tells your agent to do.
sync-agents fixes all three:
- Zero drift.
.agents/is the single source of truth. Tool directories are symlinks into it, and the per-tool files in.agents/index/are rebuilt from it bysync,index, andwatch. Edit once, every tool gets the change. If a tool already created its own directory (say.wave/skills/), sync links each artifact into it and leaves the tool's entries alone. Existing tool directories are merged, never deleted. Sync → - Real distribution. Declare upstream rules/skills/whole trees in
sources.yaml, get SHA-pinned, lockfile-verified installs — a package manager, not a copy-paste culture. - Supply-chain safety by default. Everything fetched remotely is statically scanned and quarantined until you approve it. Your agent's instructions are an attack surface; treat them like one.
Think of the instructions you give AI coding assistants as software. This tool is npm for your AI's brain.
- Your project gets one folder (
.agents/) that holds everything you've taught your AI: house rules, reusable how-to guides, step-by-step playbooks. - Every AI tool you use reads from that one folder — like several TVs all tuned to the same channel. Change the channel once, every screen updates.
- Want a rule or skill someone else published? "Install" it like an app from an app store, pinned to an exact version so it can't silently change under you.
- And just like you wouldn't run a random downloaded program without a virus scan, anything you install from the internet is scanned and held in a waiting room until you say it's okay.
No more copy-pasting the same instructions into four different tools, and no more wondering where that one config file came from.
# go install (Go 1.21+)
go install github.com/brickhouse-tech/sync-agents/v4@latest
# Homebrew — prebuilt binary, no Go toolchain needed
brew install brickhouse-tech/tap/sync-agentsPre-built archives (with SHA-256 checksums) are also on the Releases page. More detail in docs/install.md.
cd your-project
# 1. Create .agents/ (rules/, skills/, workflows/), .agents/config, and an AGENTS.md stub if you have none
sync-agents init
# 2. Add your first rule and skill
sync-agents add rule no-secrets
sync-agents add skill code-review
# 3. Deliver to every tool: rules folders for Claude and Windsurf, .agents/index/ for the rest
sync-agents sync
# 4. Install a shared skill from another repo (SHA-pinned + scanned + quarantined)
sync-agents source add skill:anthropic/skill-pack@v1.2.0/skills/code-review
sync-agents quarantine # review the scan findings
sync-agents approve code-review # promote it into .agents/
# 5. Check that everything is wired up
sync-agents statusIf sync finds a real file or directory where one of your artifacts belongs, it warns, leaves it untouched, and exits non-zero. Rerun with --overwrite to move it aside as <path>.replaced-by-sync-agents.
That's it. Every supported tool is now wired to load the same rules. AGENTS.md stays yours: sync-agents never writes it after creating the stub.
Rules, skills, workflows, subagents, plans, and specs each get a first-class home under .agents/, routed to the right place per tool. Topology →
Define a subagent once in .agents/agents/ and it lands in .claude/agents/, .cursor/agents/, and .opencode/agents/ — the three harnesses with a native subagent surface. Already have one? add agent <name> --from <path> imports it, or --link leaves the original authoritative. add →
sources.yaml + sources.lock: every upstream artifact resolves to a commit SHA, downloads are content-hashed, and a tampered tarball aborts before anything touches disk. pull, update, source list — reproducible like a real package manager. Sources →
Remote installs are treated like a hostile supply chain. Fetched artifacts are scanned for curl | bash patterns, credential-access-plus-network combos, obfuscation, and prompt injection — then held in .agents/.quarantine/ until you approve them. Quarantine →
npm link for agent context: point a source at a live local checkout instead of a frozen snapshot. Edits flow both ways, git pull reaps updates, and the link is recorded declaratively so it survives clones. Linked sources →
sync-agents lock writes agents.lock (provenance — where every rule, skill, hook, and spec came from) + agents.sum (go.sum-style content hashes for the whole tree). sync-agents verify then proves the tree is exactly what was reviewed — a post-install edit to a pulled artifact, an injected file that skipped quarantine, or a swapped symlink all fail verify --json with a non-zero exit. PLEX-style drift detection for your AI context. Integrity lock →
Drop rules into rules/macos/, rules/linux/, or rules/unix/ and they only sync on matching machines. One committed tree, no brew-rules noise on your Linux box. OS routing →
Each tool gets your rule bodies at a path its vendor documents. Claude and Windsurf read the linked rules folder. Cursor, Copilot, Codex, and opencode each get one generated file in .agents/index/, linked or listed where the tool looks, sized to the tool's limit. CLAUDE.md -> AGENTS.md is created only for Claude Code older than 2.1.281. Upgrading from 1.x? Read the migration guide. Delivery channels →
sync-agents lint validates every SKILL.md against Claude's published authoring rules (name format, description quality, reserved words) and --fix mechanically repairs what it can. It also flags import: true frontmatter, which has no effect since 2.0. CI-friendly exit codes. Lint →
promote an artifact from a project to your user-level ~/.agents/, then global sync fans it out to every tool's user config dir with semantic-aware routing. Global commands →
The full manual lives in docs/:
- Command reference — every command and flag
- Topology & configuration — the
.agents/tree,config,STATE.md - Sources, lockfile & provenance · Quarantine · Linked sources · Integrity lock
- Delivery channels · Migrating to 4.0 · Migrating to 2.0
- Inheritance · OS-scoped routing
- Architecture — scope resolution, semantic routing, global roots
- Examples — ready-to-import rules, skills, and workflows
MIT © Brickhouse Tech