What is AgentSync?

agent_sync is a thin Dart wrapper over the AgentSync shell engine.

The engine remains the single source of truth (agent/.ai/system/*.sh). The Dart package executes this engine locally using Isolate resolution to ensure scripts are always synced natively with your installed package version.

Table of Contents

• What is AgentSync?
• Getting Started
• Workflow
• CLI Commands
• Project Configuration
• Dart API
• Notes

Getting Started

Installation

Add the package via standard pub.dev dependency:

dependencies:
  agent_sync: ^0.0.1-dev05

Then run:

dart pub get

Minimal workflow for users

1. Add package to pubspec.yaml.
2. Create .ai/ in your project and put:
   • .ai/AGENTS.md
   • .ai/rules/*.md
   • .ai/skills/*/SKILL.md
   • .ai/tools/*.yaml
3. Run:

dart run agent_sync:agent_sync sync

Generated files appear in destinations from .ai/tools/*.yaml (for example .codex/*, .claude/*, .github/*, .gemini/*).

CLI

dart run agent_sync:agent_sync sync --project-dir .
dart run agent_sync:agent_sync sync --project-dir . --only codex,cursor --dry-run
dart run agent_sync:agent_sync check --project-dir .
dart run agent_sync:agent_sync setup-hooks --project-dir .

Useful options:

Option	Description
--repo-url / --repo-ref	Point to a remote GitHub repository instead of the locally installed package
--cache-dir	Where the cloned remote engine repo is cached (if using --repo-url)
--no-update	Use existing remote cache without git fetch (default behavior)
--update	Refresh cached repository before command execution
--local-repo-path	Run scripts from a local checkout instead of cloning

Note: Local repository auto-detection is used only when repo options are not explicitly provided.

Optional project config

You can customize source paths via agent_sync.yaml in project root:

source:
  agents: ".ai/AGENTS.md"
  rules: ".ai/rules"
  skills: ".ai/skills"
  tools: ".ai/tools"

Flat keys are also supported:

agents: ".ai/AGENTS.md"
rules: ".ai/rules"
skills: ".ai/skills"
tools: ".ai/tools"

Dart API

You can also use AgentSync programmatically from Dart:

import 'package:agent_sync/agent_sync.dart';

Future<void> main() async {
  final client = AgentSyncClient();
  await client.sync(projectDirectory: '.', dryRun: true);
}

Notes

• Requires bash available in PATH. (git is only required if using remote --repo-url overrides).
• Scripts are executed with AGENTSYNC_REPO_ROOT=<project-dir>.
• Source layout is auto-detected for both .ai/src/* and .ai/*. If omitted, fallback defaults are extracted securely from your local pub-cache directly!

---