Metadata-Version: 2.4
Name: syncagents
Version: 1.0.2
Summary: One AGENTS.md, every AI coding assistant in sync. Generate CLAUDE.md, Cursor rules, GitHub Copilot instructions, Windsurf, Cline, Gemini, Aider & Zed from a single source of truth. Zero-dependency CLI for the AGENTS.md standard.
Project-URL: Homepage, https://pypi.org/project/agentsync/
Project-URL: Repository, https://pypi.org/project/agentsync/
Project-URL: Issues, https://pypi.org/project/agentsync/
Project-URL: Changelog, https://pypi.org/project/agentsync/
Author: agentsync contributors
License-Expression: MIT
License-File: LICENSE
Keywords: agent-rules,agents-md,agents.md,agentsync,ai,ai-agents,ai-coding-assistant,ai-config,ai-rules,ai-workflow,aider,automation,claude,claude-code,claude-md,cli,cline,codex,coding-assistant,coding-rules,copilot,copilot-instructions,cross-platform,cursor,cursor-rules,cursorrules,developer-tools,devtools,gemini,llm,llm-config,open-source,prompt-engineering,rules,single-source-of-truth,sync,vibe-coding,windsurf,zed,zero-dependency
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: Software Development :: Code Generators
Classifier: Topic :: Utilities
Classifier: Typing :: Typed
Requires-Python: >=3.9
Description-Content-Type: text/markdown

<div align="center">

# 🔄 agentsync

### One `AGENTS.md`. Every AI coding assistant in sync.

**Stop maintaining the same rules in 6 different files.** Write your project's AI
instructions once — `agentsync` generates and keeps in sync `CLAUDE.md`, Cursor rules,
GitHub Copilot instructions, Windsurf, Cline, Gemini, Aider, Zed and more.

[![PyPI version](https://img.shields.io/pypi/v/agentsync.svg?color=3775A9&logo=pypi&logoColor=white)](https://pypi.org/project/agentsync/)
[![Python versions](https://img.shields.io/pypi/pyversions/agentsync.svg?color=3775A9)](https://pypi.org/project/agentsync/)
[![zero dependencies](https://img.shields.io/badge/dependencies-0-brightgreen.svg)](https://pypi.org/project/agentsync/)
[![license](https://img.shields.io/pypi/l/agentsync.svg?color=blue)](./LICENSE)

<br>

---

## The problem

Your team uses Cursor. And Copilot. And Claude Code. And someone's trying Windsurf.
Every one of them reads its **own** config file:

```
CLAUDE.md
.cursor/rules/*.mdc
.github/copilot-instructions.md
.windsurf/rules/*.md
.clinerules/*.md
GEMINI.md
CONVENTIONS.md          # aider
.rules                  # zed
```

So your "use type hints", "never touch `/legacy`", "tests live in `tests/`" rules get
copy-pasted into all of them — and **drift out of sync the moment anyone edits one.**
New conventions land in `CLAUDE.md` but never reach Cursor. The AI happily violates rules
half your tools never saw.

## The fix

Keep **one** source of truth — [`AGENTS.md`](https://agents.md), the emerging open
standard — and let `agentsync` project it into every tool's native format.

```bash
uvx agentsync init     # detect your tools, create AGENTS.md, generate every config
uvx agentsync watch    # edit AGENTS.md → all configs update on save
```

```text
$ uvx agentsync

agentsync · source: AGENTS.md
  + Claude Code      CLAUDE.md                          created
  + Cursor           .cursor/rules/agentsync.mdc        created
  + GitHub Copilot   .github/copilot-instructions.md    created
  ~ Windsurf         .windsurf/rules/agentsync.md       updated

✔ synced 4 of 4 target(s)
```

Edit `AGENTS.md`. Run `agentsync`. Done. **Every assistant now reads the same rules.**

---

## Quick start

No install required with [uv](https://docs.astral.sh/uv/):

```bash
uvx agentsync init     # set up (auto-detects the AI tools already in your repo)
# edit AGENTS.md, then:
uvx agentsync          # sync once
uvx agentsync watch    # keep it live while you work
```

Or install it:

```bash
pip install agentsync      # or: pipx install agentsync
agentsync init
```

## Supported assistants

| Tool | Generated file | Format |
| --- | --- | --- |
| **Claude Code** | `CLAUDE.md` | markdown (managed block) |
| **Cursor** | `.cursor/rules/agentsync.mdc` | `.mdc` + frontmatter |
| **GitHub Copilot** | `.github/copilot-instructions.md` | markdown (managed block) |
| **Windsurf** | `.windsurf/rules/agentsync.md` | markdown |
| **Cline** | `.clinerules/agentsync.md` | markdown |
| **Gemini CLI** | `GEMINI.md` | markdown (managed block) |
| **Aider** | `CONVENTIONS.md` | markdown (managed block) |
| **Zed** | `.rules` | markdown |
| **Anything else** | custom path you define | markdown |

> **Your hand-written content is safe.** For shared files like `CLAUDE.md`, agentsync only
> manages the region between its `<!-- agentsync:start -->` / `<!-- agentsync:end -->`
> markers. Anything outside those markers is preserved on every sync.

## Keep your AI configs honest in CI

```yaml
# .github/workflows/agentsync.yml
name: agentsync
on: [push, pull_request]
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: astral-sh/setup-uv@v5
      - run: uvx agentsync check
```

`agentsync check` writes nothing and exits `1` if any config has drifted from `AGENTS.md`.

Pre-commit hook:

```yaml
# .pre-commit-config.yaml
repos:
  - repo: local
    hooks:
      - id: agentsync
        name: agentsync check
        entry: agentsync check
        language: system
        pass_filenames: false
```

## Configuration

Zero config works out of the box. To customize, `init` writes `agentsync.config.json`:

```json
{
  "source": "AGENTS.md",
  "targets": ["claude", "cursor", "copilot", "windsurf"]
}
```

You can also configure it from `pyproject.toml`:

```toml
[tool.agentsync]
targets = ["claude", "cursor"]
```

Custom target not shipped by default:

```json
{
  "targets": [
    "claude",
    { "path": "docs/ai-guidelines.md", "format": "md", "strategy": "block" }
  ]
}
```

- `strategy: "full"` — agentsync owns the whole file.
- `strategy: "block"` — only the marked region is managed; the rest is yours.

## Commands

| Command | What it does |
| --- | --- |
| `agentsync init` | Create `AGENTS.md` + config, detect tools, run first sync |
| `agentsync` / `agentsync sync` | Regenerate all configs from `AGENTS.md` |
| `agentsync check` | CI mode — exit 1 if anything is out of sync |
| `agentsync watch` | Re-sync automatically on every save |
| `agentsync list` | Show supported assistants and which are detected |

Flags: `--cwd <dir>`, `--source <file>`, `--quiet`, `--version`.

## Python API

```python
from agentsync import sync, init, detect_targets

report = sync()
print(report.in_sync, [r.path for r in report.results])
```

## Why agentsync?

- **Zero dependencies.** Nothing to audit, installs instantly, nothing to be
  compromised in a supply-chain attack.
- **Non-destructive.** Managed blocks mean your existing `CLAUDE.md` notes survive.
- **Idempotent.** Running it twice changes nothing the second time — safe in any hook.
- **Standards-first.** Built around the open [`AGENTS.md`](https://agents.md) format.
- **Mirror on npm.** JS shop too? [`syncagents` on npm](https://www.npmjs.com/package/syncagents)
  produces byte-identical output — `npx syncagents`.

## FAQ

### What is AGENTS.md?

[`AGENTS.md`](https://agents.md) is the open, vendor-neutral standard for AI coding-assistant
instructions (donated to the Linux Foundation, used by 60,000+ repos and read natively by
Codex, Cursor, Copilot, Gemini CLI, Aider, Windsurf and Zed). agentsync makes it the single
source of truth and generates every tool-specific file from it.

### How do I sync Cursor rules, CLAUDE.md and Copilot instructions from one file in Python?

Run `uvx agentsync init`, write your rules in `AGENTS.md`, then `uvx agentsync`. It generates
`.cursor/rules/agentsync.mdc`, `CLAUDE.md`, `.github/copilot-instructions.md`, Windsurf,
Cline, Gemini, Aider and Zed configs — and keeps them in sync.

### AGENTS.md vs CLAUDE.md vs Cursor rules vs Copilot instructions — do I need all of them?

Each AI tool reads its own file, so today you do. agentsync removes the duplication: maintain
one `AGENTS.md` and it projects the content into each tool's native format, so they never
drift apart.

### How is this different from rule-porter or copy-pasting?

agentsync is a zero-dependency CLI with a `check` mode (CI fails on drift), `watch` mode,
non-destructive managed blocks (your hand-written `CLAUDE.md` notes survive), and idempotent
output. It treats `AGENTS.md` as the canonical source rather than converting between formats
ad hoc.

## License

[MIT](./LICENSE) — free for personal and commercial use.

<div align="center">
<sub>If agentsync saves you from one more copy-pasted rule, give it a ⭐ — it helps other devs find it.</sub>
</div>
