Getting Started

1 Prerequisites

Ensure you have the following installed on your machine:

• Python 3.8+
• pip (Python package manager)
• Git (To clone the repository or sync rules)

2 Installation

Install the package directly from PyPI:

pip install agentsync-vcs

Or install from source:

git clone https://github.com/sumanthp/agent-sync.git
cd agent-sync
pip install -e .

3 Initialize Your Project

Navigate to your project root and run the initialization command:

$ agentsync-vcs init

This creates a sample-rule.md and a .agent-sync/config.json file.

4 Connect Remote Rules (Optional)

If your team has a shared repository for agent rules, add it as a remote:

$ agentsync-vcs remote add https://github.com/my-org/agent-rules.git
$ agentsync-vcs sync

The sync command clones the repository to a local cache on your machine.

Other Remote Commands:

$ agentsync-vcs remote list     # View configured remotes
$ agentsync-vcs remote remove https://github.com/my-org/agent-rules.git   # Remove a remote

5 Define a Rule

Create Universal Markdown rules with YAML frontmatter. You can define advanced routing via the type field (e.g., skill or global):

---
name: api-expert
description: Specialized FastAPI skill
type: skill
globs: ["src/api/**/*.py"]
---
- Use Pydantic for validation.
- Return HTTP 400 for bad input.

6 Sync to Your Tools

Use the pull command followed by your target tool. This will compile both local and remote rules into the specific IDE formats:

# For Cursor (.cursor/rules/*.mdc)
$ agentsync-vcs pull cursor

# For Claude Code (.claude/skills/)
$ agentsync-vcs pull claude

# For Windsurf (.windsurf/rules/*.md)
$ agentsync-vcs pull windsurf

# For Trae (.trae/rules/*.md)
$ agentsync-vcs pull trae

# For Hermes (.hermes/skills/*.md)
$ agentsync-vcs pull hermes

# For Kiro (.kiro/steering/*.md)
$ agentsync-vcs pull kiro

# For GitHub Copilot (.github/instructions/*.md)
$ agentsync-vcs pull copilot

# For Gemini (GEMINI.md)
$ agentsync-vcs pull gemini

# For Codex (AGENTS.md)
$ agentsync-vcs pull codex