Skip to content

getting-started.md

Latest commit

 

History

History
123 lines (86 loc) · 2.67 KB

getting-started.md

File metadata and controls

123 lines (86 loc) · 2.67 KB
Raw

Getting Started

This guide takes you from zero to your first synced agent config in about a minute.

Alpha-scope notice (v0.1.0-alpha). Only the Claude Code and Cursor compilers emit files today. Aider, GitHub Copilot, and AGENTS.md are registered as stubs and will start emitting in v0.2. See ROADMAP.md for the delivery plan.

Install

npm install -g agentsync

Verify:

agentsync --version

Initialize Your Project

cd ~/your-project
agentsync init

This creates:

.agentsync/
├── config.yaml
├── rules/
│   └── stack.md
└── prompts/
    └── code-review.md

It also adds a managed block to your .gitignore so personal-override files (.agentsync/local.yaml, .agentsync/.cache/) won't get committed by accident. The block is delimited by sentinel comments and is removed by agentsync eject --full.

If init finds sensitive files in your project root that aren't already git-ignored (e.g., .env, id_rsa, *.pem), it prints a friendly warning naming each file. AgentSync never auto-edits those files for you — it just points them out so you can decide what to do.

Edit Your Rules

Open .agentsync/rules/stack.md and replace the placeholders with your project's real tech stack. Add more files (rules/testing.md, rules/architecture.md, etc.) as needed.

Build

agentsync build

You should see generated files appear:

  • CLAUDE.md
  • .cursor/rules/*.mdc

Commit

Commit both your source and the generated files. Teammates without AgentSync installed still benefit from the generated configs.

git add .agentsync CLAUDE.md .cursor
git commit -m "Add AgentSync"

Watch Mode

While actively writing rules:

agentsync watch

Edit any file under .agentsync/; all agent configs rebuild automatically.

Catching Drift in CI

Add to your CI pipeline:

npx agentsync check

Exit code is 1 if anyone edited .agentsync/ without rebuilding.

Leaving AgentSync

agentsync eject

Strips the AGENTSYNC:GENERATED header from every generated file, leaving the body intact. Your CLAUDE.md, .cursor/rules/*.mdc, etc. become normal hand-maintained files. .agentsync/ is not touched, so you can re-adopt later by running agentsync build again.

For a complete removal:

agentsync eject --full

Additionally archives .agentsync/ to .agentsync.backup/ (timestamped if a backup already exists) and removes the managed block AgentSync added to your .gitignore. No lock-in.

Next Steps